LINK Guida di Implementazione di Mobilità REST API SMS
LINK Mobility furnisce un serviziu per a spedizione di messagi, i micro pagamenti è i servizii basati in locu. A piattaforma agisce cum'è un acquistore di cuntenutu trasparente è biancu è un router di transazzione trà i Fornitori di serviziu è Operatori.
LINK Mobility furnisce una API RESTful chì pò esse usata per accede à i servizii di LINK Mobility cum'è l'inviu di SMS. Questa API hè pensata per esse faciule d'utilizà è cumpatibile cù tutte e lingue è i framework muderni. Utilizendu a lingua di a vostra scelta, a vostra applicazione pò utilizà l'API REST di Link Mobility per implementà putenti capacità di messageria è pagamentu
© LINK Mobility, 10 di marzu di u 2021
Informazione Legale
L'infurmazione furnita in stu documentu hè a sola pruprietà è copyright di Netsize. Hè cunfidenziale è destinatu à un usu strettamente informativu. Ùn hè micca vincolante è pò esse sottumessu à cambiamenti senza avvisu. Ogni divulgazione o usu micca autorizatu serà cunsideratu cum'è illegale.
Netsize™ è linkmobility™ sò prutetti da e lege francese, CEE è internaziunale di pruprietà intellettuale.
Tutti l'altri marchi citati sò a sola pruprietà di i so rispettivi pruprietarii.
Nunda di ciò chì cuntene quì deve esse interpretatu cum'è cunferisce una licenza o un dirittu sottu a patente, copyright o marca di Netsize.
NETSIZE
Société anonyme au capital de 5 478 070 euros
Siège social : 62, avenue Emile Zola 92100 Boulogne - Francia
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Scopu di u Documentu
Stu documentu descrive cumu u Fornitore di serviziu usa l'API LINK Mobility REST per SMS. Hè destinatu à l'architetti tecnichi è i disegnatori chì implementanu i servizii di u Prestatore di serviziu.
1. Usage Basic
Hè assai faciule di mandà un SMS. Mandate una dumanda HTTP à LINK Mobility chì pò esse realizatu usendu solu a web navigatore.
2. Funziunale Overview
U sistema LINK Mobility furnisce e seguenti funziunalità di basa per i missaghji SMS:
Invià i missaghji SMS Mobile Terminated (MT), cum'è testu o binari (per esempiu WAP Push) messaggi premium è standard.
Riceve rapporti di consegna per i missaghji MT sottumessi.
Riceve SMS Originati Mobile (MO), tariffa premium è standard.
L'API REST di SMS hè dedicata à l'inviu di missaghji SMS di MT à tariffu standard.
L'API manda tutti i missaghji SMS in modu asincronu, attivendu funzioni cum'è:
"Fire-and-forget" - u Fornitore di serviziu vole avè tempi di risposta più prevedibile è ùn vole micca aspittà u risultatu da l'Operatore.
Ripruvà a funziunalità - LINK Mobility rinviarà u missaghju se l'Operatore hà prublemi tempuranee.
2.1 Mandà un missaghju SMS
Fornitore di serviziu Netsize Consumer
- Mandate un missaghju MT
- Ritorna l'ID di u missaghju
- Mandate un missaghju SMS
- Consegna un rapportu di consegna
- Mandate un rapportu di consegna
U flussu di basa per l'invio di missaghji SMS hè descrittu cum'è seguitu:
U Fornitore di serviziu face una dumanda per mandà un missaghju SMS à un destinatariu via u sistema LINK Mobility.
Un ID di missaghju hè tornatu à u Fornitore di serviziu. Stu ID pò esse usatu per es. correlate u messagiu cù u rapportu di consegna curretta.
LINK Mobility gestisce u routing è trasmette u messagiu SMS à u Consumatore indirizzatu.
Un rapportu di consegna hè attivatu, per esempiu, quandu u messagiu SMS hè mandatu à u dispusitivu di u Consumatore.
U rapportu di consegna hè mandatu à u Fornitore di serviziu. U rapportu cuntene u listessu ID di missaghju cum'è vultatu in u passu 2.
Flussu alternativu: dumanda invalida
Se i paràmetri furniti o credenziali di l'utilizatori in a dumanda ùn sò micca validi, un errore hè tornatu à u Fornitore di serviziu. L'errore indica u mutivu di u rifiutu è u flussu finisci. Nisun ID di missaghju hè tornatu.
3. Endpoint
A risorsa SMS hè accessata cù a strada:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Per a sicurità di cunnessione, l'API LINK Mobility REST hè accessibile solu per HTTPS.
U certificatu di u servitore Link Mobility hè firmatu da Thawte Server CA.
4. Operazioni
U serviziu SMS furnisce e seguenti operazioni:
| Nome | Strada |
| Mandate | /restapi/v1/sms/send |
4.1 Mandate
L'operazione di mandatu hè aduprata per mandà un SMS à un solu destinatariu.
Questa operazione hè destinata à l'utilizatori di basa è avanzati. In u casu più sèmplice, solu l'indirizzu di destinazione, è u testu di u missaghju sò obligati à purtà un SMS. LINK Mobility detecterà u Schema di Codificazione di Dati è eseguirà a concatenazione automatica di un missaghju in parechje parti di missaghju se ne necessariu.
Per un usu avanzatu, u Fornitore di serviziu pò aduprà paràmetri opzionali per u cuntrollu tutale di u furmatu di u messagiu cumpresu l'intestazione di dati d'utilizatore.
U Fornitore di serviziu pò mandà messagi cuncatenati, ma a preparazione di i dati di l'utilizatori è l'intestazione di i dati d'utilizatori deve esse fatta da u Fornitore di serviziu è u missaghju deve esse mandatu per mezu di più richieste di mandate versu LINK Mobility.
5. Autentificazione
U nome d'utilizatore è a password sò sottumessi in ogni dumanda utilizendu u Schema di Autentificazione Basic HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
I credenziali sò mandati in un capu d'Autorizazione in a dumanda HTTP. U cliente custruisce u campu di l'intestazione cum'è descrittu quì:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Per esample, se u nome d'utilizatore hè John è changeme hè a password, allora l'intestazione Autorizazione risultante hè:
Autorizazione: Basic am9objpjaGFuZ2VtZSA=
Cum'è fall-back, u nome d'utilizatore è a password ponu esse sottumessi cum'è parametri di dumanda. Questu hè cunsigliatu solu per i clienti chì ùn supportanu micca Basic Auth.
6. Invia una dumanda
6.1 Stringa di dumanda
I paràmetri di dumanda sò sottumessi cum'è una stringa di dumanda chì cuntene coppie nome / valore. A stringa di dumanda hè codificata cù u Percent Encoding (URL codificazione).
http://www.w3schools.com/tags/ref_urlencode.asp
Per esample, salutu mondu ! hè codificata cum'è Hello + World% 21.
6.2 Parametri di dumanda obbligatoria
| Nome | Lunghezza massima | Descrizzione |
| Indirizzu di destinazione | 40 | U MSISDN chì u messagiu SMS deve esse mandatu à, cuminciendu cù codice di paese. Esample: 46123456789. Per certi mercati (induve u Consumer MSISDN deve esse offuscatu) stu valore pò ancu esse un alias alfanumericu, prefissatu cù "#". |
| missaghju testu | 1600 | U cuntenutu di u messagiu SMS. |
6.3 Paràmetri di dumanda opzionale (per usu avanzatu)
| Nome | Lunghezza massima | Descrizzione |
| Indirizzu d'origine | 16 | L'indirizzu d'origine per u messagiu SMS in uscita. U tipu d'indirizzu d'origine hè definitu da u paràmetru originatorTON. A lunghezza massima di u numeru curtu hè 16. U mittente alfanumericu hè limitatu à l'alfabetu predeterminatu GSM cù una lunghezza massima di 11 caratteri. A lunghezza massima di u mittente MSISDN hè 15 (aduprendu u stessu formatu cum'è l'elementu destinationAddress). Pò esse omessi quandu l'indirizzu d'origine è uriginaleTON sò scelti da u sistema. Sta funzione dipende di u mercatu è di a cunfigurazione. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| l'origine TON | 1 | U tipu di numeru di l'indirizzu d'origine (TON): 0 - numeru curtu 1 - Alfanumericu (lunghezza massima 11) 2 - MSISDN Pò esse omessi quandu l'indirizzu d'origine è u TON d'origine seranu selezziunati da u sistema. Sta funzione dipende di u mercatu è di a cunfigurazione. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| UserDataHeader | 280 | L'intestazione di Dati di l'Usuariu inseme cù i Dati di l'Usuariu ponu cuntene sin'à 140, vale à dì 280 quandu sò codificati in hex, ottetti. Stu paràmetru hè sempre codificatu hex. |
| DCS | 3 | Schema di codificazione di dati. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| PID | 3 | ID di u protocolu. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| Tempu di Validità Relativa | 6 | Tempu di validità relative in seconde (relativu à u tempu per a sottumissione à LINK Mobility). U valore massimu hè 604800 (7 ghjorni) è u valore predeterminatu hè 48 ore. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| tempu di consegna | 20 | Timestamp quandu u messagiu SMS deve esse mandatu (tempu di consegna ritardatu). Vede a sezione nantu à u formatu di data ora. |
| status ReportFlags | 1 | Mandate a dumanda di rapportu: 0 - Nisun rapportu di consegna (predeterminatu) 1 - Rapportu di consegna dumandatu 9 - Rapportu di consegna di u servitore dumandatu (LINK Mobility ùn trasmette micca u rapportu à u Fornitore di serviziu, ma u rende dispunibule in rapporti etc.) |
| campignName | 50 | I transazzioni LINK Mobility sò tagcun stu nomu. Hè adupratu per raggruppà e transazzioni in i rapporti di Link Mobility. |
| maxConcatenatedMessages | 1 | Un valore trà 1 è 10 chì definisce quanti missaghji concatenati sò permessi. Default hè 3. |
| correlationId | 100 | ID furnita da u Fornitore di serviziu chì serà ritruvatu in u Rapportu di Consegna. |
| nome d'utilizatore | 100 | Furnitu cum'è una alternativa à l'autenticazione di basa HTTP. |
| codice | 100 | Furnitu cum'è una alternativa à l'autenticazione di basa HTTP. |
6.4 Metodi di dumanda HTTP
Per a massima interoperabilità, l'API supporta i metudi di dumanda HTTP GET è POST. Nisun altru mètudu HTTP hè permessu.
6.4.1 GET
A stringa di dumanda codificata hè aghjuntu à u URL.
GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Autorizazione: Basic am9objpjaGFuZ2VtZSA=
6.4.2 POST
A stringa di dumanda codificata hè sottumessa in u corpu di missaghju di dumanda HTTP. Content-Type hè applicazione/x-www-form-urlcodificati.
POST https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Cuntenutu-Tipu: application / x-www-form-urlcodificati
Autorizazione: Basic am9objpjaGFuZ2VtZSA=
Durata di u cuntenutu: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Data è ora
I paràmetri in l'API REST chì rapprisentanu a data è l'ora sò sempre in u fusu orariu UTC (Coordinated Universal Time). Timestamps sò rapprisentati cum'è una stringa cù stu formatu esatta:
2017-04-25T23:20:50Z
Questu rapprisenta 20 minuti è 50 seconde dopu à l'ora 23 di u 25 d'aprile 2017 in UTC.
7. Risposta missaghju
Dopu avè ricivutu è interpretatu un missaghju di dumanda, l'API risponde cù un missaghju di risposta HTTP.
7.1 Codice di statutu HTTP
L'API REST torna sempre u codice di statutu HTTP 200 OK per e dumande processate. U corpu di u messagiu cuntene un paràmetru responseCode chì hè utilizatu per determinà u risultatu esatta.
7.2 Corpu di messagiu
U corpu di u messagiu hè custituitu da JSON chì descrive u risultatu di a dumanda.
http://json.org/
Link Mobility JSON hè conforme à a Guida di Stile JSON di Google.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parametri di risposta
| Nome | Lunghezza massima | Descrizzione |
| risposta codice | 3 | 0 indica una transazzione successu. |
| Risposta Missaghju | 255 | A descrizzione testuale di a risposta, per esempiu, testu d'errore. |
| volteamp | 20 | Data è ora quandu LINK Mobility hà trattatu a dumanda. (Consultate a sezione di furmatu di data / ora). |
| traceId | 36 | Identificatore internu di Link Mobility. Adupratu per supportu è risoluzione di prublemi. |
| messageIds | 10 x 36 | Array of LINK Mobility IDs missaghju unichi per ogni missaghju riesciutu (ID di missaghju multipli sò restituiti se u messagiu hè cuncatenatu). Omessa in casu di fallimentu. |
7.4 Esample risposte
Successu
HTTP/1.1 200 OK
Tipu di cuntenutu: applicazione/json
Durata di u cuntenutu: 144
Data: Ghjovi, 15 Settembre 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Eccu u stessu JSON furmatu per a leggibilità:
{
“risposta codice":0,
“Risposta Missaghju":" Successu ",
“volteamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds":["1-4850879008"] }
fallimentu
HTTP/1.1 200 OK
Tipu di cuntenutu: applicazione/json
Durata di u cuntenutu: 148
Data: Ghjovi, 15 Settembre 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" Login invalidu o usu API micca autorizatu ","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Successu
HTTP/1.1 200 OK
Tipu di cuntenutu: applicazione/json
Durata di u cuntenutu: 144
Data: Ghjovi, 15 Settembre 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Eccu u stessu JSON furmatu per a leggibilità:
{
“risposta codice":0,
“Risposta Missaghju":" Successu ",
“volteamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds":["1-4850879008"] }
fallimentu
HTTP/1.1 200 OK
Tipu di cuntenutu: applicazione/json
Durata di u cuntenutu: 148
Data: Ghjovi, 15 Settembre 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" Login invalidu o usu API micca autorizatu ","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Codici di risposta
I seguenti codici di risposta ponu esse restituiti in a risposta di mandà:
| Codice | Testu | Descrizzione |
| 0 | Successu | Eseguitu cù successu. |
| 1 | Login invalidu o usu API micca autorizatu | U nome d'utilizatore o password sbagliatu o u Fornitore di serviziu hè impeditu da LINK Mobility. |
| 2 | U cunsumadore hè bluccatu da Link Mobility | U Consumatore hè bluccatu da LINK Mobility. |
| 3 | L'operazione ùn hè micca furnita da LINK Mobility | L'operazione hè bluccata per u Service Provider. |
| 4 | U cunsumadore hè scunnisciutu à LINK Mobility | U Consumatore hè scunnisciutu à LINK Mobility. O se alias hè stata utilizata in a dumanda; alias micca trovu. |
| 5 | U cunsumadore hà bluccatu stu serviziu in LINK Mobility | U Consumatore hà bluccatu stu serviziu in LINK Mobility. |
| 6 | L'indirizzu d'origine ùn hè micca supportatu | L'indirizzu d'origine ùn hè micca supportatu. |
| 7 | L'indirizzu di origine Alpha ùn hè micca supportatu da u contu | L'indirizzu d'origine alfa ùn hè micca supportatu da u contu. |
| 8 | L'indirizzu di origine MSISDN ùn hè micca supportatu | L'indirizzu di origine MSISDN ùn hè micca supportatu. |
| 9 | GSM allargatu ùn hè micca supportatu | GSM allargatu ùn hè micca supportatu. |
| 10 | Unicode ùn hè micca supportatu | Unicode ùn hè micca supportatu. |
| 11 | U rapportu di statu ùn hè micca supportatu | U rapportu di statu ùn hè micca supportatu. |
| 12 | A capacità necessaria ùn hè micca supportata | A capacità necessaria (alcuni da quì sopra) per mandà u messagiu ùn hè micca supportatu. |
| 13 | A rata massima di throttling di u fornitore di cuntenutu hè superata | U Fornitore di serviziu manda i missaghji SMS à LINK Mobility troppu veloce. |
| 14 | ID di u protocolu ùn hè micca supportatu da u contu | ID di u protocolu ùn hè micca supportatu. |
| 15 | U limitu di cuncatenazione di u messagiu hè superatu | U numeru di missaghji cuncatenati supera u numeru massimu dumandatu. |
| 16 | Impossibile di indirizzà u messagiu. | LINK Mobility ùn hà micca pussutu indirizzà u messagiu. |
| 17 | Periudu di tempu pruibitu | Ùn hè micca permessu di mandà missaghju durante u periodu di tempu |
| 18 | Saldo troppu bassu nantu à u contu di u fornitore di serviziu | Fornitore di serviziu hè bluccatu per via di un equilibriu troppu bassu |
| 50 | Successu parziale | Successu parziale quandu invià un missaghju SMS à parechji destinatari. |
| 99 | Errore di u servitore internu | Altro errore di Link Mobility, cuntattate l'assistenza LINK Mobility per più infurmazione. |
| 100 | Indirizzu di destinazione invalidu | L'indirizzu di destinazione (MSISDN, o alias) ùn hè micca validu. |
| 102 | ID riferitu (ligatu) invalidu | L'ID di riferimentu ùn hè micca validu, forse l'ID di riferimentu hè digià utilizatu, troppu vechju o scunnisciutu. |
| 103 | Nome di contu invalidu | U nome di u contu ùn hè micca validu. |
| 105 | Metadati di serviziu invalidu | I metadati di serviziu ùn sò micca validi. |
| 106 | Indirizzu d'origine invalidu | L'indirizzu d'origine ùn hè micca validu. |
| 107 | Indirizzu d'origine alfanumericu invalidu | L'indirizzu d'origine alfanumericu ùn hè micca validu. |
| 108 | Tempu di validità invalidu | U tempu di validità hè invalidu. |
| 109 | Tempu di consegna invalidu | U tempu di consegna hè invalidu. |
| 110 | Cuntenutu di messagiu invalidu / dati d'utilizatore | I dati di l'utilizatori, vale à dì u messagiu SMS, ùn sò micca validi. |
| 111 | Lunghezza di u messagiu invalidu | A durata di u messagiu SMS hè invalidu. |
| 112 | Intestazione di dati d'utilizatore invalida | L'intestazione di i dati di l'utilizatori ùn hè micca validu. |
| 113 | Schema di codificazione di dati invalidu | U DCS hè invalidu. |
| 114 | ID di protocolu invalidu | U PID hè invalidu. |
| 115 | Bandiere di rapportu di status invalidu | I bandieri di u rapportu di statutu ùn sò micca validi. |
| 116 | TON invalidu | U TON d'origine ùn hè micca validu. |
| 117 | Invalidu campnomu nomu | U campu nome d'aign hè invalidu. |
| 120 | Limite invalidu per u numeru massimu di missaghji cuncatenati | U numaru massimu di missaghji cuncatenati ùn hè micca validu. |
| 121 | Indirizzu d'origine msdn invalidu | L'indirizzu d'origine MSISDN ùn hè micca validu. |
| 122 | ID di correlazione invalidu | L'ID di correlazione ùn hè micca validu. |
8. Features Optional
8.1 Correzione MSISDN
A correzione di MSISDN hè una funzione opzionale chì pò esse attivata da u supportu LINK Mobility, se dumandatu.
Sta funziunalità vi curregge indirizzi di destinazione è align à u furmatu E.164 nicissarii. In più di a currezzione di u formatu, u sistema pò ancu eseguisce funziunalità specifichi di u mercatu, cum'è a traduzzione di numeri francesi internaziunali per curregge i numeri DOM-TOM (départements et territoires d'outre-mer) quandu applica.
Sottu sò un numeru di exampless de correction :
| Indirizzu di Destinazione Inviatu | Indirizzu di destinazione currettu |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| + 460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Numeru francese traduttu in un numeru DOM-TOM) |
Inoltre, hè pussibule di permette i numeri di telefunu naziunali per un mercatu sceltu. Quandu sta funzione hè attivata, ogni numeru internaziunale per altri mercati deve esse mandatu cù un signu iniziale "+" per distinguelli da u mercatu sceltu.
Sottu sò parechji examples di currezzione fattu quandu aduprà Svezia (codice di paese 46) cum'è mercatu predeterminatu per i numeri naziunali.
| Indirizzu di Destinazione Inviatu | Indirizzu di destinazione currettu |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| + 460702233445 | 46702233445 |
| + 458022334455 | 458022334455 |
| 45802233445 | Invalidu postu chì u segnu "+" manca |
Nota chì u MSISDN currettu serà utilizatu da LINK Mobility è serà tornatu in i rapporti di consegna.
Per piacè cuntattate l'assistenza LINK Mobility per più infurmazione.
8.2 Sostituzione di caratteri
A sostituzione di caratteri hè una funzione opzionale chì pò esse attivata da u supportu LINK Mobility se dumandatu.
Questa funzione traduce i caratteri di l'alfabetu non GSM in i dati di l'utilizatori (testu SMS) in caratteri di l'alfabetu GSM equivalenti quandu u DCS hè impostatu à "GSM" (17). Per esample “Seqüência de teste em Português” sarà tradotto in “Seqüencia de teste em Portugues”.
9. Rapporti di consegna
U Fornitore di serviziu pò, se furnitu, dumandà rapporti di spedizione di messagi SMS o notificazioni di consegna per i missaghji MT mandati. Questi rapporti sò attivati in l'Operatore SMSC quandu u messagiu MT hè o consegnatu à u Consumatore miratu o sguassatu, per esempiu, scadutu o, per una certa ragione, micca routable.
Solu u statutu finali di u messagiu SMS hè informatu à u Fornitore di serviziu, vale à dì, consegnatu o sguassatu. Solu un rapportu per messagiu MT hè generatu. Cù u statu sguassatu, un codice mutivu pò applicà. Stu codice mutivu specifichi u mutivu di u missaghju SMS ùn esse furnitu.
I rapporti sò mandati attraversu LINK Mobility è mandati à u Fornitore di serviziu utilizendu u protocolu HTTP.
Per riceve rapporti, u Fornitore di serviziu deve implementà per example un Servlet Java o una pagina ASP.NET. Tutti dui ricevenu richieste HTTP GET o POST.
Parametri
A dumanda include i seguenti parametri:
| Parametru | Tipu | M/O/I* | Valore predeterminatu | Lunghezza massima | Descrizzione |
| MessageId | stringa | M | – | 22 | U messagiu ID di u messagiu MT chì currisponde à stu rapportu. |
| Indirizzu di destinazione | stringa | M | – | 40 | MSISDN di u Consumatore, vale à dì l'indirizzu di destinazione di u messagiu MT uriginale. |
| StatusCode | interu | M | 1 | Status code indica u statutu di u messagiu MT. I codici di statutu applicabili sò: 0 - Cunsigliu 2 - Sguassatu (u codice di ragiuni si applica) |
|
| Tempu Stamp | stringa | M | – | 20 | U tempu chì indica quandu u rapportu di consegna hè statu ricevutu da LINK Mobility. U fusu orariu di u tempuamp hè CET o CEST (cù l'ora d'estate cum'è definita per l'UE). Formatu: aaaaMMgg HH:mm:ss. |
| Operatore | stringa | M | – | 100 | U nome di l'operatore utilizatu quandu invià u missaghju SMS o u nome di u contu utilizatu quandu invià u missaghju SMS. Una lista di Operatori dispunibuli hè furnita da u supportu LINK Mobility. |
| ReasonCode | interu | O | – | 3 | U codice di u mutivu indica perchè u missaghju hà finitu in u statu sguassatu. I codici di ragiuni applicabili sò: 100 - Scadutu 101 - Ricusatu 102 - Errore di furmatu 103 - Altru errore 110 - Abbonatu scunnisciutu 111 - L'abbonatu hè interdettu 112 - Abbonatu micca furnitu 113 - Abbonatu indisponibile 120 - fallimentu SMSC 121 - Congestion SMSC 122 - SMSC roaming 130 - Errore di u telefuninu 131 - A memoria di u telefuninu superata U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| OperatorTimeStamp | stringa | O | – | 20 | Tempu chì indica quandu u rapportu hè statu attivatu in u SMSC di l'Operatore (se furnitu da l'Operatore). U fusu orariu di u tempuamp hè CET o CEST (cù l'ora d'estate cum'è definita per l'UE). Formatu: aaaaMMgg HH:mm:ss. |
| StatusText | stringa | O | – | 255 | Placeholder per infurmazioni supplementari da l'Operatore, per esempiu, una descrizzione di testu chjaru di u statu / ragiò. U cumpurtamentu pò varià cù l'integrazioni di l'operatore. |
| CorrelationId | stringa | O | – | 100 | L'ID di correlazione furnita in SendRequest o SendTextRequest. |
| Operatore NetworkCode | interu | O | – | 6 | U codice di a rete mobile (MCC + MNC) di l'operatore. |
* M = Obligatoriu, O = Facoltativu, I = Ignoratu.
U Fornitore di serviziu hà da furnisce LINK Mobility cù u scopu URL per i rapporti di consegna (opcionalmente includendu credenziali per l'autentificazione di basa HTTP). U Fornitore di serviziu pò sceglie quale metudu HTTP preferitu aduprà:
HTTP POST (cunsigliatu)
HTTP GET.
Example utilizendu HTTP GET (furnitu cù successu):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example utilizendu HTTP GET (micca consegnatu, l'operatore hà furnitu timestamp per l'avvenimentu):
I paràmetri sò URL encodedi.
Codificazione di caratteri:
U Fornitore di serviziu pò sceglie quale codificazione di caratteri preferita aduprà:
UTF-8 (consigliatu)
ISO-8859-1.
9.1 Ricunniscenza di u Prestatore di serviziu
U Fornitore di serviziu deve ricunnosce ogni rapportu di consegna. U ricunniscenza pò esse pusitivu, vale à dì u rapportu di consegna ricevutu successu, o negativu, vale à dì fallimentu.
Per piacè nutate: LINK Mobility hà un timeout di lettura per ricunniscenza di 30 seconde per i rapporti di consegna. Un timeout attiverà una riprova di consegna (se riprova attivata) o una annullazione di a consegna (se riprova disattivata). Questu significa chì l'applicazione di u Fornitore di serviziu deve assicurà tempi di risposta rapida, soprattuttu durante a carica alta.
Hè assai cunsigliatu di ricunnosce u rapportu di consegna versu LINK Mobility prima di trasfurmà.
A regula per a ricunniscenza pusitiva è negativa hè descritta cusì:
Ricunniscenza pusitiva, ACK, rapportu di consegna consegnatu:
Codice di risposta di a gamma HTTP 200 in cumbinazione cù u cuntenutu furmatu XML seguenti:
Ricunniscenza negativa, NAK, rapportu di consegna micca consegnatu:
Ogni risposta altru ch'è ricunniscenza pusitiva, per esample, un ricunniscenza negativu hè attivatu da qualsiasi codice d'errore HTTP o u cuntenutu XML seguente:
U cuntenutu XML pò esse usatu per cuntrullà u mecanismu di ricuperazione di LINK Mobility. Un NAK pruvucarà un tentativu di novu tentativu, se attivatu. Per i Fornitori di serviziu chì ùn sò micca cunfigurati per u mecanismu di ricuperazione, u cuntenutu XML hè opzionale.
Quì sottu hè una dumanda HTTP POST è risposta example di un rapportu di consegna consegnatu à un Fornitore di serviziu:
Richiesta HTTP:
POST /context/app HTTP/1.1
Cuntenutu-Tipu: application / x-www-form-urlcodificati;charset=utf-8
Host: server:port
Durata di u cuntenutu: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
Risposta HTTP:
HTTP/1.1 200 OK
Content-Type: testu / pianu
9.2 Riprova
U sistema LINK Mobility pò eseguisce tentativi di riprova per e spedizioni di rapporti di consegna falluti, vale à dì micca ricunnisciuti. U Fornitore di serviziu pò sceglie u cumportamentu di retry preferitu:
Nisuna prova (default) - u messagiu serà scartatu se u tentativu di cunnessione falla, leghje time-out o per qualsiasi codice d'errore HTTP.
Riprova - u missaghju serà risentitu per ogni tipu di prublema di cunnessione, timeout di lettura, o ricunniscenza negativa.
Quandu u novu tentativu per NAK hè attivatu, hè impurtante capisce chì scenarii chì generaranu un tentativu di ritruvà da LINK Mobility è cumu funziona a riprova. Ogni Fornitore di serviziu hà a so propria fila di retry, induve i missaghji sò urdinati secondu u tempu di messagiuamp. Link Mobility sempre prova di trasmette missaghji più vechji prima, ancu s'è l'ordine individuale di i missaghji mandati à u Fornitore di serviziu ùn hè micca garantitu. U mutivu principalu per i missaghji chì sò scartati da a fila di retry hè unu di dui motivi: o u messagiu TTL scade o (teoricamente) a fila di retry diventa piena. U TTL hè dipendente di l'operatore è di u contu, vale à dì, pò varià secondu l'operatore è u tipu di messagiu, per esempiu, SMS premium o missaghju SMS standard.
Un Fornitore di serviziu cù riprova attivatu deve verificà l'ID unicu di u missaghju MT per assicurà chì u messagiu ùn hè micca digià ricevutu.
Hè impurtante per u Fornitore di serviziu di rispettà queste regule simplici quandu un errore si trova durante u processu di un rapportu di consegna, se u mutivu di l'errore hè: Pruvisoriu, per esempiu, a basa di dati ùn hè micca dispunibule, un NAK deve esse restituitu. LINK Mobility hà da rinvià u missaghju.
Permanente è un tentativu di ritruvà sò prubabile di causà u listessu tipu di prublema, un ACK deve esse tornatu. Per esample, quandu u missaghju ùn pudia esse analizatu currettamente o hà causatu un errore di runtime inespettatu.
Agisce in cunsequenza assicurarà chì nisun bloccu o degradazione di u throughput ùn sia causatu da un rapportu di consegna chì hè rimandatu ripetutamente.
10. Cunsiglii di implementazione
1. Hè pussibule aduprà u vostru web navigatore per mandà richieste à l'API. Questu hè assai faciule per scopre è valutà i servizii senza alcunu strumentu di sviluppu.
2. Chrome o Firefox sò cunsigliati cù una estensione cum'è JSONView per vede JSON abbastanza furmatu.
3. Avemu usatu SoapUI per pruvà POST, Autenticazione Basica è per inspeccionà a dumanda HTTP bruta è i missaghji di risposta.
4. U cURL L'utile hè utile per invià e richieste POST cù l'autenticazione basica. Vede example sottu.
curl POST \
-H "Tipu di cuntenutu: applicazione/x-www-form-urlcodificata" \
-H "Autorizazione: Basic am9objpjaGFuZ2VtZSA=" \
https://europe.ipx.com/restapi/v1/sms/send \
-data "destinationAddress=46123456789&messageText=Hello+World%21"
_______________
Trasfurmà a cumunicazione persunalizata
Documenti / Risorse
 |
LINK Guida di Implementazione di Mobilità REST API SMS [pdfGuida di l'utente Guida di implementazione di mobilità REST API SMS, Mobilità, Guida di implementazione REST API SMS, REST API SMS, API SMS, SMS |
