Documentatia Tehnica API web2sms® - SOAP / REST (postpaid)

Detalii:

Versiune: 2.0.3 (recomandata)

Autor: NETOPIA

WSDL 

https://www.web2sms.ro/api?wsdl 

Serviciul de automatizare trimitere mesaje scurte dezvoltat de NETOPIA permite trimiterea de SMS-uri si urmarirea stadiului de livrare a acestora. Prin intermediul acestui serviciu pot fi trimise SMS-uri catre orice numar de telefon mobil din retelele GSM cu ai caror operatori NETOPIA are contracte de colaborare (Orange, Vodafone, Telekom Mobile, RCS&RDS Digi Mobil) si catre nr. de telefon apartinand operatorilor mobili internationali.

Procedura de trimitere este foarte simpla si se poate realiza numai pe baza unui client SOAP, dezvoltat prin resurse proprii de catre beneficiar, indiferent de mediul de dezvoltare sau sistemul de operare ales.

Pentru a putea folosi acest serviciu sunt necesari urmatorii pasi:

1. Trebuie sa fi inregistrat pe site-ul web2sms.ro

2. Contactateaza un reprezentant NETOPIA pentru a va activa si configura contul

3. Dezvoltarea clientului SOAP bazat pe detaliile oferite de WSDL

4. Testarea de trimitere a mesajelor prin intermediul clientului SOAP.

5. Dezvoltarea clientului SOAP API - sendSmsAuthKey & callbackURL

PHP composer - https://github.com/web2sms/composer

Metoda sendSmsAuthKey ($username, $authKey, $sender, $recipient, $message, $scheduleDate, $validity, $callbackUrl, $userData)

• Parametri:

- username - Acest parametru este obligatoriu. Numele de utilizator folosit pentru autentificarea in web2sms®

- authKey - Acest parametru este obligatoriu. Se va folosi cheia oferita de catre serviciul operational web2sms® 

- sender - Expeditorul mesajului. Acest parametru este optional. Lungimea expeditorului nu poate depasi 11 caractere. Setarea unui expeditor nu garanteaza folosirea lui la trasmiterea unui mesaj. Expeditorul trebuie sa fie in lista accepata si configurata de catre un reprezentant WEB2SMS. De asemena nu se pot folosi expeditori alfanumerici pentru toti operatorii. In cazul in care acest parametru nu este transmis sau este transmis gresit se va folosi expeditorul implicit. Expeditoul implicit este numarul scurt al conexiunii folosite pentru trimiterea SMS-ului

- recipient - Numarul de telefon mobil catre care se doreste trimiterea SMS-ului. Acest parametru este obligatoriu. Formatul corect al numarului de telefon este 07PPXXXXXX, 407PPXXXXXX sau 7PPXXXXXX pentru numerele nationale. Pentru cele internationale trebuie trimis numarul in format international fara sa fie prefixat cu + sau 00.

- message - Mesajul ce se doreste a fi trimis prin SMS. Acest parametru este obligatoriu. 

- scheduleDate - Data si ora la care doresti sa fie trimis mesajul. Acest parametru este optional. Formatul corect este formatul XML pentru campuri de tip data si ora YYYY-MM-DDTHH:MM:SS.mmmZ. Este acceptat si formatul YYYY-MM-DD HH:MM:SS. In cazul in care acest parametru nu este transmis sau este transmis intr-un format gresit, este folosita data si ora curenta de pe server-ul web2sms ®

- validity - Valabilitatea mesajului exprimata in minute. Acest parametru este optional. In cazul in care acest parametru este transmis si diferit de zero reprezinta cate minute de la data si ora pentru care a fost programat mesajul acesta este valabil. Daca mesajul nu poate fi transmis in intervalul de valabilitate specificat acesta nu va mai fi transmis si nu va mai fi contorizat in contul tau.

- callbackUrl -  Acest parametru este optional. Reprezinta URL-ul la care se doreste transmiterea rapoartelor de livrare a SMS-ului in cazul in care acesta este programat cu success.

- userData - Acest parametru este optional. Reprezinta o informatie (sub forma unui camp suplimentar) care va fi vizibila doar in sectiunea de raportare sau arhiva SMS. Spre exemplu: un identificator unic intern prin intermediul caruia poti urmari transmiterile SMS catre baza ta de date.

Rezultat:

• Daca metoda reuseste programarea unui mesaj cu succes va intoarce un string de minimum 32 si maximum 60 de caractere ce reprezinta identificatorul unic al mesajului in platforma web2sms®.

• Daca metoda esueaza serviciul web va intoarce un SOAP Fault. Codurile de eroare si mesajele aferente sunt prezentate in tabelul de mai jos:

Cod (zecimal)           Cod (hexa)               Mesaj

536870913                0x20000001                Internal web2SMS error

268435457                0x10000001                No available account for the calling IP

268435463                0x10000007                Associated account is disabled

268435462                0x10000006                Associated account is missconfigured

268435464                0x10000008                Internal web2SMS error while creating SMS Sender                  

268435458                0x10000002                Parameter `phone` has a wrong format or it belongs to a GSM.Network that is not configured

268435466                0x1000000a                Phone number is black listed

268435520                0x10000040                Phone number belongs to a GSN Network that is not configured for the associated account

268435460                0x10000004                You’ve exceeded your monthly limit for SMS sendings

268435488                0x10000020                You are trying to schedule a SMS message outside the configured time interval restrictions

268435459                0x10000003                Parameter `message` is empty! Empty message are not allowed

268435465                0x10000009                Internal web2sms error while scheduling a SMS

ex:

 $soapClient = new SoapClient("https://www.web2sms.ro/api?wsdl");

    try {

        $resp = $soapClient->sendSmsAuthKey($username, $authKey, $sender, $recipient, $message, $scheduleDate, $validity , $callbackUrl, $userData);

        echo "Sending message succeded. MessageID is " . $resp;  

    }  catch (Exception $e)

    {

        echo "There was an error while trying to schedule an SMS!\n";

        echo "Code: " . $e->getMessage() . "\n";

        echo "Message: " . $e->getMessage() . "\n";

    }

Iar in cazul utilizarii $callbackURL-ului:

* URL-ul definit de catre tine trebuie sa fie public si vizibil din exterior

* pentru fiecare linie din URL (SMS request) trebuie asociat intern, de catre tine, un identificator unic (ex: messageID-ul returnat de catre noi) pentru diferentierea SMS-urilor

* setul de parametri ce pot fi apelabili prin $callbackURL:

 'id'                    => HASH ID,

 'status'            => STATUS, 

 'userData'      => USERDATA,

 'timestamp'   => DATA RAPORT LIVRARE SMSC

 'network'        => GSM NETWORK of the MSISDN (ex: 22601 = Vodafone, 22610 = Orange, 22603 / 22604 / 22606 = Telekom, 22605 = Digi Mobil) - lista completa

unde:

• HASH_ID = messageID – identificatorul unic al mesajului rezultat din apelul cu succes al uneia dintre metodele send 

• STATUS = status-ul mesajului *pentru mai multe detalii puteti consulta sectiunea pentru raportare.

• USR_DATA poate fi completat cu orice informatie suplimentara de catre tine. Aceasta informatie nu se va regasi in textul mesajului, insa va fi prezenta in rapoartele generate de catre web2sms. (ex: un ID de client, cu ajutorul caruia puteti identifica mai usor SMS-urile transmise catre clientul respectiv).

Caracterele permise pentru a respecta lungimea maxima a unui mesaj de 160 de caractere (sau 153 caractere per part in cazul SMS-urilor concatenate).

ASCII printable characters (character code 32-127)

Codes 32-127 are common for all the different variations of the ASCII table, they are called printable characters, represent letters, digits, punctuation marks, and a few miscellaneous symbols. You will find almost every character on your keyboard. Character 127 represents the command DEL.

https://www.ascii-code.com/

Toate aceste caractere se vor contoriza cu 1 octet / caracter.

- exceptie facand caracterele: 

form feed, ^ Caret / Circumflex, { Left curly bracket, } Right curly bracket, \ Backslash, [ Left square bracket, ` Tilde, ] Right square bracket, | Vertical Bar, € Euro sign (acestea se contorizeaza cu 2 octeti, desi fac parte din alfabetul GSM7bit)

*Atentie! Daca mesajul contine caractere speciale, acestea pot fi afisate incorect.

Mentionam ca in cazul in care se transmit caractere speciale in corpul mesajului (unde fiecare caracter este reprezentat pe 2 octeti), atunci, implicit lungimea mesajelor SMS se va reduce la 70 (63 de caractere pentru mesajele concatenate).

Caracterele speciale sunt cele prezente in alfabetul 

The extended ASCII codes (character code 128-255)

There are several different variations of the 8-bit ASCII table. The table below is according to Windows-1252 (CP-1252) which is a superset of ISO 8859-1, also called ISO Latin-1, in terms of printable characters, but differs from the IANA's ISO-8859-1 by using displayable characters rather than control characters in the 128 to 159 range. Characters that differ from ISO-8859-1 is marked by light blue color. 

https://www.ascii-code.com/