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.