Integrare API

Aceasta sectiune reprezinta documentatia tehnica pentru integrarea serviciului nostru de trimitere SMS cu aplicatia/website-ul dvs. Pentru a obtine token-ul necesar folosirii API-ului este nevoie sa va creati un cont.

Trimitere SMS

Pentru a trimite sau programa un mesaj SMS trebuie sa faceti un request prin metoda POST catre adresa: https://www.smsadvert.ro/api/sms/ de tip application/json

Exemplu trimitere SMS prin dispozitive proprii

Livrarea SMS-ului se face imediat dupa request.

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "Acesta este continutul mesajului SMS"
}

Exemplu trimitere SMS prin dispozitive proprii cu redundanta

In cazul in care nu aveti nici un dispozitiv propriu conectat sau operatorul GSM raspunde cu un mesaj de eroare, SMS-ul va fi trimis prin numar scurt

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "Acesta este continutul mesajului SMS",
  "failover": "short"
}

Exemplu trimitere SMS prin numar scurt

Livrarea SMS-ului se face imediat dupa request.

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "Acesta este continutul mesajului SMS",
  "sendAsShort": true
}

Exemplu trimitere SMS programat

Livrarea SMS-ului se face conform parametrilor startDate si endDate.

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "Acesta este continutul mesajului SMS",
  "startDate": 1486883578036,
  "endDate": 1486889778036
}

Exemplu trimitere SMS cu destinatari multipli

Livrarea SMS-ului catre destinatari se face pe rand, imediat dupa request.

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456,+40740123457,+40740123458",
  "shortTextMessage": "Acesta este continutul mesajului SMS"
}

Exemplu trimitere SMS cu primirea raportului de livrare

Livrarea SMS-ului se face imediat dupa request. Ulterior veti primi un request la adresa din parametrul callback cu raportul de livrare.

POST https://www.smsadvert.ro/api/sms/ HTTP/1.1
Authorization: {API_AUTH_TOKEN}
Content-Type: application/json
{
  "phone": "+40740123456",
  "shortTextMessage": "Acesta este continutul mesajului SMS",
  "callback": "http://adresadvs.com/callback-url/"
}

Descrierea parametrilor

  • phone

    string, obligatoriu
  • Reprezinta numarul de telefon al destinatarului.
    Numarul trebuie sa fie in formatul international E.164 (Ex: +40740123456)

    Pentru destinatari multipli se pot introduce numerele de telefon despartite prin virgula, ex. "+40740123456,+40740123457".
    Se accepta maxim 1000 de numere de telefon, iar numerele duplicate nu vor fi inregistrate pentru trimitere.
    Atentie! Nu se accepta virgula la finalul listei.
  • shortTextMessage

    string, obligatoriu
  • Reprezinta continutul mesajului SMS si trebuie sa fie format din minim 3 si maxim 480 caractere.
  • sendAsShort

    boolean, optional
  • Pentru a trimite SMS-ul prin numar scurt acest parametru trebuie sa contina valoarea true. In cazul in care acest parametru are valoarea false sau nu este prezent, mesajul se va trimite prin dispozitivele dvs.
  • startDate

    integer, optional
  • Reprezinta data/ora/minutul/secunda ulterior careia se va incerca trimiterea mesajului. Formatul este UNIX time (milisecunde).
  • endDate

    integer, optional
  • Reprezinta data/ora/minutul/secunda ulterior careia nu se va mai incerca trimiterea mesajului. Formatul este UNIX time (milisecunde).
  • failover

    string, optional
  • Reprezinta canalul de trimitere secundar.
    In cazul in care mesajul nu poate fi livrat prin dispozitivele dvs. (nu exista cel putin un dispozitiv conectat sau operatorul GSM raspunde cu un mesaj de eroare) se va incerca trimiterea prin canalul secundar.

    Daca parametrul failover este setat ca si "short" atunci SMS-ul va fi trimis prin numar scurt.
  • callback

    string, optional
  • Reprezinta adresa web (URL) unde veti primi un request pentru comunicarea statusului de livrare a mesajului.

    Request-ul va fi de tip POST (application/json) si va contine doi parametrii: status cu valoarea "delivered" sau "failed" si msgId reprezentand id-ul mesajului primit la trimitere.

    Exemplu de request catre URL-ul dvs. setat ca si callback

    POST http://adresadvs.com/callback-url/ HTTP/1.1
    Content-Type: application/json
    {
      "status": "delivered",
      "msgId": "xxxxxx"
    }

Raspuns

Raspunsul primit in urma Request-ului este de tip application/json.

Exemplu de raspuns cu success

{
  "successMessage": "Mesajul a fost inregistrat!",
  "msgId": "xxxxxx"
}

Exemple de raspuns cu eroare

{
  "errors": {
    "phone": "Numar de telefon invalid!",
    "shortTextMessage": "Introduceti minim 3 caractere!"
  }
}
{
  "errorMessage": "There was a database error!"
}