Documentatie de integrare API

Urmatoarea sectiune descrie modul in care poti integra functionalitatea SMS in propriile aplicatii web / desktop-based prin intermediul API-ului whosms.ro

Cu ajutorul API-ului poti efectua urmatoarele:

  • Trimite SMS
  • Primi SMS
  • Obtine raportul de livrare
  • Verifica creditul contului

Daca ai nevoie de asistenta tehnica contacteaza-ne.

Trimitere SMS

Pentru a trimite cu succes un SMS trebuie facuta o cerere HTTP GET sau HTTP POST cu parametrii din tabelul de mai jos, catre urmatorul URL:
https://www.whosms.ro/send.php

Parametru
Descriere
user
Numele de utilizator de la whosms.ro
pass
Parola ta
catre
Destinatarul mesajului in format international excluzand "+" (ex. 40722xxxxxx)
dela
Expeditorul mesajului (minim 3, maxim 11 caractere).
Caractere valide: A-z, 1-9, fara spatii goale
mesaj
Continutul mesajului text. Poate avea pana la 612 caractere in lungime. Un singur mesaj are 160 de caractere, iar mesajele concatenate sunt formate din mesaje simple de 153 caractere (2 mesaje=306 caractere, 3 mesaje=459 caractere, 4 mesaje=612 caractere). Acest parametru trebuie sa fie URL ENCODED (http://php.net/manual/en/function.urlencode.php)
Observatie: conform specificatiilor GSM caracterele ^ { } \ [ ] ~ | sunt considerate caractere duble.
dataProgramare
(optional)
Data la care se doreste programarea SMS-ului.
Trebuie sa fie in format Y-m-d H:i:s sau in format Unix Timestamp.
Exemplu de data valida:
Y-m-d H:i:s -> 2018-09-21 18:40:00
Unix Timestamp 1537555200 -> 2018-09-21 18:40:00
json
Daca i se da valoarea 1 (&json=1) atunci raspunsul API-ului va fi in format JSON

Exemplu de cerere HTTP GET pentru trimiterea unui SMS:
https://www.whosms.ro/send.php?user=test&pass=parolamea&catre=40722XXXXXX&mesaj=mesaj+test&dela=Companie&json=1

Exemplu raspuns API in format JSON:
{"status":"1","mesaj":"Trimis","id":"9910c363-a036-5573","parti":"1","cost":"0.040"}

Raspuns JSON
Descriere
status
Daca mesajul este trimis cu succes va avea valoarea "1".
In cazul n care apare o eroare va avea o valoare negativa
mesaj
Scurta descriere a statusului
id
ID unic al mesajului
parti
Reprezinta numarul de parti al SMS-ului. Daca mesajul are pana in 160 caractere, atunci acest parametru va fi "1". Daca mesajul are 612 caractere (lungimea maxima) parametrul va fi "4"
cost
Costul mesajului (in euro)

Tabel cu codurile de raspuns ale API-ului (trimitere SMS):

Status
Descriere
1
Mesajul a fost trimis
-1
Autentificare esuata
-2
Credit insuficient
-3
Numar destinatar invalid
-4
Mesajul este gol
-5
Expeditor invalid

Citeste si exemplele de cod PHP.


Primire SMS

Dupa primirea unui raspuns la un SMS, acesta poate fi redirectionat catre tine la URL-ul setat n panoul de control (sectiunea Setari SMS Primit).

O cerere HTTP POST va fi facuta catre URL-ul tau cu urmatoarele variabile:

Parametru
Descriere
expeditor
Numarul de telefon care a trimis SMS catre numarul scurt
mesaj
Continutul mesajului primit
data
Data si ora receptionarii mesajului (in format Y-m-d H:i:s)
operator
Operatorul de telefonie mobila din care face parte expeditorul

In urma trimiterii cererii HTTP POST API-ul WhoSMS va astepta raspunsul: HTTP/1.1 200 OK

In caz contrar, se va reface trimiterea pana la primirea acelui header.

Un exemplu de script care primeste SMS se gaseste in sectiunea de exemple de cod.

Citeste si exemplele de cod PHP.


Raport de livrare

a) Manual

Pentru a verifica raportul de livrare al unui mesaj expediat trebuie facuta o cerere HTTP GET sau HTTP POST cu parametrii din tabelul de mai jos, catre urmatorul URL:
https://www.whosms.ro/raport.php

Parametru
Descriere
user
Numele de utilizator de la whosms.ro
pass
Parola ta
id
ID-ul unic al mesajului pe care sistemul l genereaza la expediere

Exemplu de cerere HTTP GET:
https://www.whosms.ro/raport.php?user=test&pass=parola&id=9910c363-a036-5573-95d5

Exemplu raspuns API n format JSON:
{"status":"1","mesaj":"Livrat","data":"2018-08-15 14:08:20"}

Tabel cu codurile de raspuns ale API-ului (raport livrare):

Status
Descriere
0
Mesaj trimis (catre operatorul de telefonie mobila)
1
Mesaj livrat
2
Mesaj nelivrat
3
Mesal trimis (in asteptare la operatorul de telefonie mobila)
4
Mesaj nelivrat (numarul nu este in serviciu)
-1
Autentificare esuata
-6
Mesaj inexistent

b) Automat

Vei primi raportul de livrare la URL-ul pe care il setezi in panoul de control (sectiunea Setari Rapoarte de livrare)

O cerere HTTP POST va fi facuta catre URL-ul tau cu urmatoarele variabile:

Parametru
Descriere
id
ID-ul unic al mesajului pe care sistemul il genereaza la expediere
status
Raportul de livrare al mesajului
mesaj
Scurta descriere a statusului (Livrat, Nelivrat, Trimis)
data
Data si ora primirii raportului de livrare (in format Y-m-d H:i:s)

In urma trimiterii cererii HTTP POST API-ul WhoSMS va astepta raspunsul: HTTP/1.1 200 OK

In caz contrar, se va reface trimiterea pana la primirea acelui header.

Un exemplu de script care primeste raportul de livrare se gaseste in sectiunea de exemple de cod.

Citeste si exemplele de cod PHP.


Verificare credit

Pentru verificarea creditului trebuie facuta o cerere HTTP GET sau HTTP POST cu parametrii din tabelul de mai jos, catre urmatorul URL:
https://www.whosms.ro/balanta.php

Parametru
Descriere
user
Numele de utilizator de la whosms.ro
pass
Parola ta

API-ul va returna un raspuns cu balanta contului tau.

Exemplu de cerere HTTP GET:
https://www.whosms.ro/balanta.php?user=test&pass=parolamea

Exemplu de raspuns:
353.6

Citeste si exemplele de cod PHP.