Guida all'implementazione della mobilità LINK REST API SMS
LINK Mobility fornisce un servizio per la consegna di messaggi, micropagamenti e servizi basati sulla posizione. La piattaforma funge da acquirente di contenuti white-label trasparente e router di transazioni tra Service Provider e Operatori.
LINK Mobility fornisce un'API RESTful che può essere utilizzata per accedere ai servizi LINK Mobility come l'invio di SMS. Questa API è progettata per essere facile da usare e compatibile con tutti i linguaggi e framework moderni. Utilizzando il linguaggio di tua scelta, la tua applicazione può utilizzare l'API REST Link Mobility per implementare potenti funzionalità di messaggistica e pagamento
© LINK Mobility, 10 marzo 2021
Informazioni legali
Le informazioni fornite in questo documento sono di esclusiva proprietà e copyright di Netsize. Sono riservate e destinate a un uso strettamente informativo. Non sono vincolanti e potrebbero essere soggette a modifiche senza preavviso. Qualsiasi divulgazione o utilizzo non autorizzato sarà considerato illegale.
Netsize™ e linkmobility™ sono protetti dalle leggi francesi, comunitarie e internazionali sulla proprietà intellettuale.
Tutti gli altri marchi citati sono di proprietà esclusiva dei rispettivi proprietari.
Nulla di quanto contenuto nel presente documento deve essere interpretato come conferimento di alcuna licenza o diritto su brevetto, copyright o marchio commerciale di Netsize.
DIMENSIONE NETTA
Société anonyme au capital de 5 478 070 euro
Siège social :62, avenue Emile Zola92100 Boulogne – Francia
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Ambito del documento
Questo documento descrive come il Service Provider utilizza la LINK Mobility REST API per SMS. È destinato ad architetti e progettisti tecnici che implementano i servizi del Service Provider.
1. Utilizzo di base
È molto semplice inviare un SMS. Si invia una richiesta HTTP a LINK Mobility, che può essere eseguita utilizzando solo un web browser.
2. Funzionaleview
Il sistema LINK Mobility fornisce le seguenti funzionalità di base per i messaggi SMS:
Invio di messaggi SMS MT (Mobile Terminated), come messaggi di testo o binari (ad esempio WAP Push) a tariffa premium e standard.
Ricezione di report di consegna per i messaggi MT inviati.
Ricezione di messaggi SMS originati da dispositivi mobili (MO), a tariffa premium e standard.
L'API REST SMS è dedicata all'invio di messaggi SMS MT a tariffa standard.
L'API invia tutti i messaggi SMS in modo asincrono, abilitando funzionalità quali:
“Fire-and-forget” – il fornitore del servizio desidera avere tempi di risposta più prevedibili e non vuole attendere il risultato dall’operatore.
Funzionalità di nuovo tentativo: LINK Mobility invierà nuovamente il messaggio se l'operatore riscontra problemi temporanei.
2.1 Invio di un messaggio SMS
Fornitore di servizi Netsize Consumer
- Invia messaggio MT
- ID messaggio di ritorno
- Invia messaggio SMS
- Consegnare il rapporto di consegna
- Invia rapporto di consegna
Il flusso di base per l'invio di messaggi SMS è descritto come segue:
Il fornitore del servizio effettua una richiesta per inviare un messaggio SMS a un destinatario tramite il sistema LINK Mobility.
Un ID messaggio viene restituito al Service Provider. Questo ID può essere utilizzato, ad esempio, per correlare il messaggio con il report di consegna corretto.
LINK Mobility gestisce l'instradamento e recapita il messaggio SMS al Consumatore destinatario.
Un rapporto di consegna viene attivato, ad esempio, quando il messaggio SMS viene recapitato al dispositivo del consumatore.
Il rapporto di consegna viene inviato al Service Provider. Il rapporto contiene lo stesso ID messaggio restituito nel passaggio 2.
Flusso alternativo: richiesta non valida
Se i parametri forniti o le credenziali utente nella richiesta non sono validi, viene restituito un errore al Service Provider. L'errore indica il motivo del rifiuto e il flusso termina. Non vengono restituiti ID messaggio.
3. Punto finale
Si accede alla risorsa SMS tramite il percorso:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Per la sicurezza della connessione, la LINK Mobility REST API è accessibile solo tramite HTTPS.
Il certificato del server Link Mobility è firmato da Thawte Server CA.
4. Operazioni
Il servizio SMS fornisce le seguenti operazioni:
| Nome | Sentiero |
| Inviare | /restapi/v1/sms/invia |
4.1 Invia
L'operazione di invio viene utilizzata per inviare un SMS a un singolo destinatario.
Questa operazione è pensata sia per utenti di base che avanzati. Nel caso più semplice, per recapitare un SMS sono richiesti solo l'indirizzo di destinazione e il testo del messaggio. LINK Mobility rileverà il Data Coding Scheme ed eseguirà la concatenazione automatica di un messaggio in più parti di messaggio, se necessario.
Per un utilizzo avanzato, il fornitore del servizio può utilizzare parametri opzionali per il controllo totale della formattazione del messaggio, inclusa l'intestazione dei dati utente.
Il fornitore del servizio può inviare messaggi concatenati, ma la preparazione dei dati utente e dell'intestazione dei dati utente deve essere effettuata dal fornitore del servizio e il messaggio deve essere inviato tramite più richieste di invio verso LINK Mobility.
5. Autenticazione
Nome utente e password vengono inviati a ogni richiesta utilizzando lo schema di autenticazione di base HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Le credenziali vengono inviate in un'intestazione Authorization nella richiesta HTTP. Il client costruisce il campo header come descritto qui:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Per esempioampAd esempio, se il nome utente è john e changeme è la password, l'intestazione di autorizzazione risultante è:
Autorizzazione: Base am9objpjaGFuZ2VtZSA=
Come fall-back, username e password possono essere inviati come parametri di richiesta. Questo è consigliato solo per i client che non supportano Basic Auth.
6. Invio di una richiesta
6.1 Stringa di query
I parametri di richiesta vengono inviati come stringa di query contenente coppie nome/valore. La stringa di query viene codificata utilizzando la codifica percentuale (URL codifica).
http://www.w3schools.com/tags/ref_urlencode.asp
Per esempioample, Hello World! è codificato come Hello+World%21.
6.2 Parametri obbligatori della richiesta
| Nome | Lunghezza massima | Descrizione |
| indirizzodestinazione | 40 | L'MSISDN a cui deve essere inviato il messaggio SMS, a partire dal prefisso internazionale. Esempioample: 46123456789. Per alcuni mercati (in cui il Consumer MSISDN deve essere offuscato) questo valore può anche essere un alias alfanumerico, preceduto da "#". |
| messaggioTesto | 1600 | Il contenuto del messaggio SMS. |
6.3 Parametri di richiesta facoltativi (per uso avanzato)
| Nome | Lunghezza massima | Descrizione |
| OriginariamenteIndirizzo | 16 | L'indirizzo di origine per il messaggio SMS in uscita. Il tipo di indirizzo di origine è definito dal parametro originatorTON. La lunghezza massima del numero breve è 16. Il mittente alfanumerico è limitato all'alfabeto GSM predefinito con lunghezza massima di 11 caratteri. La lunghezza massima del mittente MSISDN è 15 (utilizzando lo stesso formato dell'elemento destinationAddress). Può essere omesso quando il sistema seleziona producingAddress e producingTON. Questa funzione dipende dal mercato e dalla configurazione. Il comportamento può variare in base alle integrazioni dell'operatore. |
| originatoreTON | 1 | Tipo di numero dell'indirizzo di origine (TON): 0 – Numero breve 1 – Alfanumerico (lunghezza massima 11) 2 – MSISDN Può essere omesso quando il sistema selezionerà originatingAddress e originatingTON. Questa funzione dipende dal mercato e dalla configurazione. Il comportamento può variare in base alle integrazioni dell'operatore. |
| intestazione dati utente | 280 | L'intestazione dei dati utente insieme ai dati utente può contenere fino a 140, ovvero 280 se codificati in esadecimale, ottetti. Questo parametro è sempre codificato in esadecimale. |
| DCS | 3 | Schema di codifica dei dati. Il comportamento può variare in base alle integrazioni dell'operatore. |
| PID | 3 | ID protocollo. Il comportamento può variare in base alle integrazioni dell'operatore. |
| tempo di validità relativa | 6 | Tempo di validità relativo in secondi (relativo al tempo di invio a LINK Mobility). Il valore massimo è 604800 (7 giorni) e il valore predefinito è 48 ore. Il comportamento può variare in base alle integrazioni dell'operatore. |
| tempi di consegna | 20 | Orarioamp quando il messaggio SMS deve essere recapitato (tempo di recapito ritardato). Vedere la sezione sul formato data/ora. |
| statoSegnalazioni | 1 | Invia richiesta di report: 0 – Nessun rapporto di consegna (predefinito) 1 – Richiesta di rapporto di consegna 9 – Richiesta di report di consegna al server (LINK Mobility non inoltra il report al Service Provider ma lo rende disponibile nei report ecc.) |
| campNome identificazione | 50 | Le transazioni LINK Mobility sono tagcon questo nome. Viene utilizzato per raggruppare le transazioni nei report Link Mobility. |
| maxMessaggiConcatenati | 1 | Un valore compreso tra 1 e 10 che definisce quanti messaggi concatenati sono consentiti. Il valore predefinito è 3. |
| correlazioneId | 100 | ID fornito dal fornitore del servizio che verrà riportato nel rapporto di consegna. |
| nome utente | 100 | Fornito come alternativa all'autenticazione HTTP di base. |
| password | 100 | Fornito come alternativa all'autenticazione HTTP di base. |
6.4 Metodi di richiesta HTTP
Per la massima interoperabilità, l'API supporta sia i metodi di richiesta HTTP GET che POST. Non sono consentiti altri metodi HTTP.
6.4.1 OTTENERE
La stringa di query codificata viene aggiunta a URL.
OTTENERE
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Ciao+mondo%21
Autorizzazione: Base am9objpjaGFuZ2VtZSA=
6.4.2 POSTI
La stringa di query codificata viene inviata nel corpo del messaggio di richiesta HTTP. Content-Type è application/x-www-form-urlcodificato.
INVIARE https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Tipo di contenuto: application / x-www-form-urlcodificato
Autorizzazione: Base am9objpjaGFuZ2VtZSA=
Lunghezza del contenuto: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Data e ora
I parametri nell'API REST che rappresentano data e ora sono sempre nel fuso orario UTC (Coordinated Universal Time). Timestamps sono rappresentati come una stringa con questo formato esatto:
2017-04-25T23:20:50Z
Ciò rappresenta 20 minuti e 50 secondi dopo le 23 ore del 25 aprile 2017 in UTC.
7. Messaggio di risposta
Dopo aver ricevuto e interpretato un messaggio di richiesta, l'API risponde con un messaggio di risposta HTTP.
7.1 Codice di stato HTTP
L'API REST restituisce sempre il codice di stato HTTP 200 OK per le richieste elaborate. Il corpo del messaggio contiene un parametro responseCode che viene utilizzato per determinare il risultato esatto.
7.2 Corpo del messaggio
Il corpo del messaggio è costituito da JSON che descrive l'esito della richiesta.
http://json.org/
Link Mobility JSON è conforme alla Guida allo stile JSON di Google.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parametri di risposta
| Nome | Lunghezza massima | Descrizione |
| codice di risposta | 3 | 0 indica transazione riuscita. |
| messaggio di risposta | 255 | Descrizione testuale della risposta, ad esempio testo di errore. |
| tempiamp | 20 | Data e ora in cui LINK Mobility ha elaborato la richiesta. (Fare riferimento alla sezione sul formato data/ora). |
| tracciaID | 36 | Identificatore interno di Link Mobility. Utilizzato per supporto e risoluzione dei problemi. |
| messaggiID | 10x36 | Matrice di ID messaggio univoci di LINK Mobility per ogni messaggio riuscito (se il messaggio è concatenato, vengono restituiti più ID messaggio). Omesso in caso di fallimento. |
7.4 Esample risposte
Successo
HTTP/1.1 200 OK
Tipo di contenuto: applicazione/json
Lunghezza del contenuto: 144
Data: gio, 15 set 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Successo”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Ecco lo stesso JSON formattato per migliorarne la leggibilità:
{
“codice di risposta“:0,
“messaggio di risposta":"Successo",
“tempiamp“:”2016-0915T13:20:31Z”,
“tracciaID“:”f678d30879fd4adc25f2”,
“messaggiID“:[“1-4850879008”]}
Fallimento
HTTP/1.1 200 OK
Tipo di contenuto: applicazione/json
Lunghezza del contenuto: 148
Data: gio, 15 set 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Accesso non valido o utilizzo API non autorizzato”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Successo
HTTP/1.1 200 OK
Tipo di contenuto: applicazione/json
Lunghezza del contenuto: 144
Data: gio, 15 set 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Successo”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Ecco lo stesso JSON formattato per migliorarne la leggibilità:
{
“codice di risposta“:0,
“messaggio di risposta":"Successo",
“tempiamp“:”2016-0915T13:20:31Z”,
“tracciaID“:”f678d30879fd4adc25f2”,
“messaggiID“:[“1-4850879008”]}
Fallimento
HTTP/1.1 200 OK
Tipo di contenuto: applicazione/json
Lunghezza del contenuto: 148
Data: gio, 15 set 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Accesso non valido o utilizzo API non autorizzato”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Codici di risposta
Nella risposta di invio possono essere restituiti i seguenti codici di risposta:
| Codice | Testo | Descrizione |
| 0 | Successo | Eseguito con successo. |
| 1 | Accesso non valido o utilizzo API non autorizzato | Nome utente o password errati, altrimenti il fornitore del servizio verrà bloccato da LINK Mobility. |
| 2 | Il consumatore è bloccato da Link Mobility | Il consumatore è bloccato da LINK Mobility. |
| 3 | Il funzionamento non è fornito da LINK Mobility | L'operazione è bloccata per il fornitore del servizio. |
| 4 | Il consumatore è sconosciuto a LINK Mobility | Il consumatore è sconosciuto a LINK Mobility. Oppure se nella richiesta è stato utilizzato l'alias: alias non trovato. |
| 5 | Il consumatore ha bloccato questo servizio in LINK Mobility | Il consumatore ha bloccato questo servizio in LINK Mobility. |
| 6 | L'indirizzo di origine non è supportato | L'indirizzo di origine non è supportato. |
| 7 | Indirizzo di origine Alpha non supportato dall'account | L'indirizzo di origine alfa non è supportato dall'account. |
| 8 | Indirizzo di origine MSISDN non supportato | L'indirizzo di origine MSISDN non è supportato. |
| 9 | GSM esteso non supportato | GSM esteso non supportato. |
| 10 | Unicode non supportato | Unicode non supportato. |
| 11 | Rapporto sullo stato non supportato | Rapporto sullo stato non supportato. |
| 12 | Capacità richiesta non supportata | La capacità richiesta (diversa da quella sopra) per l'invio del messaggio non è supportata. |
| 13 | È stata superata la velocità massima di limitazione del fornitore di contenuti | Il fornitore del servizio invia i messaggi SMS a LINK Mobility troppo velocemente. |
| 14 | ID protocollo non supportato dall'account | ID protocollo non supportato. |
| 15 | Limite di concatenazione dei messaggi superato | Il numero di messaggi concatenati supera il numero massimo richiesto. |
| 16 | Impossibile instradare il messaggio. | LINK Mobility non è riuscito a instradare il messaggio. |
| 17 | Periodo di tempo proibito | Non è consentito inviare messaggi durante il periodo di tempo |
| 18 | Saldo troppo basso sul conto del fornitore di servizi | Il fornitore di servizi è bloccato a causa di un saldo troppo basso |
| 50 | Successo parziale | Riuscito parzialmente nell'invio di un messaggio SMS a più destinatari. |
| 99 | Errore interno del server | Altro errore di Link Mobility, contattare l'assistenza LINK Mobility per ulteriori informazioni. |
| 100 | Indirizzo di destinazione non valido | L'indirizzo di destinazione (MSISDN o alias) non è valido. |
| 102 | ID referenziato (collegato) non valido | L'ID di riferimento non è valido, potrebbe essere già utilizzato, troppo vecchio o sconosciuto. |
| 103 | Nome account non valido | Il nome dell'account non è valido. |
| 105 | Metadati del servizio non validi | I metadati del servizio non sono validi. |
| 106 | Indirizzo di origine non valido | L'indirizzo di origine non è valido. |
| 107 | Indirizzo di origine alfanumerico non valido | L'indirizzo alfanumerico di origine non è valido. |
| 108 | Tempo di validità non valido | Il tempo di validità non è valido. |
| 109 | Tempo di consegna non valido | Il tempo di consegna non è valido. |
| 110 | Contenuto del messaggio/dati utente non validi | I dati utente, ovvero il messaggio SMS, non sono validi. |
| 111 | Lunghezza del messaggio non valida | La lunghezza del messaggio SMS non è valida. |
| 112 | Intestazione dati utente non valida | L'intestazione dei dati utente non è valida. |
| 113 | Schema di codifica dei dati non valido | Il DCS non è valido. |
| 114 | ID protocollo non valido | Il PID non è valido. |
| 115 | Flag di segnalazione dello stato non validi | I flag del rapporto sullo stato non sono validi. |
| 116 | TON non valido | Il TON dell'originatore non è valido. |
| 117 | c non validoampallineare il nome | Il campIl nome dell'etichetta non è valido. |
| 120 | Limite non valido per il numero massimo di messaggi concatenati | Il numero massimo di messaggi concatenati non è valido. |
| 121 | Indirizzo di origine msisdn non valido | L'indirizzo di origine MSISDN non è valido. |
| 122 | ID di correlazione non valido | L'ID di correlazione non è valido. |
8. Caratteristiche opzionali
8.1 Correzione MSISDN
La correzione MSISDN è una funzionalità opzionale che può essere abilitata dal supporto LINK Mobility se richiesto.
Questa funzionalità correggerà gli indirizzi di destinazione e li allineerà al formato E.164 richiesto. Oltre alla correzione del formato, il sistema può anche eseguire funzionalità specifiche del mercato, come la traduzione di numeri francesi internazionali per correggere i numeri DOM-TOM (départements et territoires d'outre-mer), ove applicabile.
Di seguito sono riportati alcuni esempiampnumero di correzioni:
| Indirizzo di destinazione inviato | Indirizzo di destinazione corretto |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Numero francese tradotto in numero DOM-TOM) |
Inoltre, è possibile consentire numeri di telefono nazionali per un mercato selezionato. Quando questa funzione è abilitata, tutti i numeri internazionali per altri mercati devono essere inviati con un segno `+' iniziale per distinguerli dal mercato selezionato.
Di seguito sono riportati diversi esampNumero di correzioni apportate utilizzando la Svezia (prefisso nazionale 46) come mercato predefinito per i numeri nazionali.
| Indirizzo di destinazione inviato | Indirizzo di destinazione corretto |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Non valido perché manca il segno '+' |
Si noti che l'MSISDN corretto verrà utilizzato da LINK Mobility e verrà restituito nei report di consegna.
Per ulteriori informazioni, contattare l'assistenza LINK Mobility.
8.2 Sostituzione del personaggio
La sostituzione dei caratteri è una funzionalità opzionale che può essere abilitata dal supporto LINK Mobility se richiesto.
Questa funzione tradurrà i caratteri alfabetici non GSM nei dati utente (testo SMS) in caratteri alfabetici GSM equivalenti quando il DCS è impostato su "GSM" (17). Ad esempioample “Seqüência de teste em Português” verrà tradotto in “Seqüencia de teste em Portugues”.
9. Rapporti di consegna
Il Service Provider può, se previsto, richiedere report di recapito dei messaggi SMS o notifiche di recapito per i messaggi MT inviati. Questi report vengono attivati nell'Operator SMSC quando il messaggio MT viene recapitato al Consumer di destinazione o eliminato, ad esempio, scaduto o, per qualche motivo, non instradabile.
Al Service Provider viene segnalato solo lo stato finale del messaggio SMS, ovvero consegnato o eliminato. Viene generato un solo report per messaggio MT. Con lo stato eliminato, potrebbe essere applicato un codice motivo. Questo codice motivo specifica il motivo per cui il messaggio SMS non è stato consegnato.
I report vengono instradati tramite LINK Mobility e inviati al Service Provider tramite il protocollo HTTP.
Per ricevere i report, il fornitore del servizio deve implementare ad esempioample un Java Servlet o una pagina ASP.NET. Entrambi ricevono richieste HTTP GET o POST.
Parametri
La richiesta include i seguenti parametri:
| Parametro | Tipo | M/F/I* | Valore predefinito | Lunghezza massima | Descrizione |
| ID messaggio | corda | M | – | 22 | ID del messaggio MT a cui corrisponde questo report. |
| DestinazioneIndirizzo | corda | M | – | 40 | MSISDN del consumatore, ovvero l'indirizzo di destinazione del messaggio MT originale. |
| Codice di stato | intero | M | 1 | Il codice di stato indica lo stato del messaggio MT. I codici di stato applicabili sono: 0 – Consegnato 2 – Eliminato (si applica il codice motivo) |
|
| Ora Stamp | corda | M | – | 20 | Ora che indica il momento in cui LINK Mobility ha ricevuto il rapporto di consegna. Il fuso orario del timestamp è CET o CEST (con ora legale come definita per l'UE). Formato: aaaaMMgg HH:mm:ss. |
| Operatore | corda | M | – | 100 | Il nome dell'operatore utilizzato durante l'invio del messaggio SMS o il nome dell'account utilizzato durante l'invio del messaggio SMS. Un elenco degli operatori disponibili è fornito dal supporto LINK Mobility. |
| Codice Motivo | intero | O | – | 3 | Il codice motivo indica il motivo per cui il messaggio è finito nello stato "eliminato". I codici motivo applicabili sono: 100 – Scaduto 101 – Rifiutato 102 – Errore di formato 103 – Altro errore 110 – Abbonato sconosciuto 111 – Abbonato escluso 112 – Abbonato non fornito 113 – Abbonato non disponibile 120 – Errore SMSC 121 – Congestione SMSC 122 – Roaming SMSC 130 – Errore del ricevitore 131 – La memoria del portatile è stata superata Il comportamento può variare in base alle integrazioni dell'operatore. |
| OperatoreTimeStamp | corda | O | – | 20 | Ora che indica quando il report è stato attivato nell'SMSC dell'operatore (se fornito dall'operatore). Il fuso orario del timestamp è CET o CEST (con ora legale come definita per l'UE). Formato: aaaaMMgg HH:mm:ss. |
| StatoTesto | corda | O | – | 255 | Segnaposto per informazioni aggiuntive dall'operatore, ad esempio una descrizione chiara dello stato/motivo. Il comportamento può variare con le integrazioni dell'operatore. |
| CorrelazioneId | corda | O | – | 100 | ID di correlazione fornito in SendRequest o SendTextRequest. |
| OperatoreNetworkCode | intero | O | – | 6 | Il codice di rete mobile (MCC + MNC) dell'operatore. |
* M = Obbligatorio, O = Facoltativo, I = Ignorato.
Il fornitore del servizio deve fornire a LINK Mobility l'obiettivo URL per i report di consegna (inclusi facoltativamente le credenziali per l'autenticazione di base HTTP). Il fornitore di servizi può scegliere quale metodo HTTP preferito utilizzare:
HTTP POST (consigliato)
GET HTTP.
Example utilizzando HTTP GET (consegnato correttamente):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example utilizzando HTTP GET (non consegnato, l'operatore ha fornito timestamp per l'evento):
I parametri sono URL codificato.
Codifica dei caratteri:
Il fornitore del servizio può scegliere quale codifica dei caratteri preferisce utilizzare:
UTF-8 (consigliato)
Italiano:
9.1 Riconoscimento del fornitore del servizio
Il fornitore di servizi dovrebbe confermare ogni rapporto di consegna. La conferma può essere positiva, ovvero rapporto di consegna ricevuto con successo, o negativa, ovvero fallimento.
Nota: LINK Mobility ha un timeout di lettura per le conferme di 30 secondi per i report di consegna. Un timeout attiverà un nuovo tentativo di consegna (se il nuovo tentativo è abilitato) o un annullamento della consegna (se il nuovo tentativo è disabilitato). Ciò significa che l'applicazione del Service Provider deve garantire tempi di risposta rapidi, in particolare durante carichi elevati.
Si consiglia vivamente di confermare la ricezione del rapporto di consegna a LINK Mobility prima di elaborarlo.
La regola per il riconoscimento positivo e negativo è descritta come segue:
Riconoscimento positivo, ACK, rapporto di consegna consegnato:
Codice di risposta HTTP 200 in combinazione con il seguente contenuto formattato XML:
Riconoscimento negativo, NAK, rapporto di consegna non recapitato:
Qualsiasi risposta diversa dal riconoscimento positivo, ad esempioample, un riconoscimento negativo viene attivato da qualsiasi codice di errore HTTP o dal seguente contenuto XML:
Il contenuto XML può essere utilizzato per controllare il meccanismo di ripetizione di LINK Mobility. Un NAK causerà un nuovo tentativo, se abilitato. Per i Service Provider non configurati per il meccanismo di ripetizione, il contenuto XML è facoltativo.
Di seguito è riportata una richiesta HTTP POST e una risposta example di un rapporto di consegna consegnato a un fornitore di servizi:
Richiesta HTTP:
POST /contesto/app HTTP/1.1
Tipo di contenuto: application / x-www-form-urlcodificato; set di caratteri = utf-8
Host: server:porta
Lunghezza del contenuto: 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
Tipo di contenuto: testo/semplice
9.2 Riprova
Il sistema LINK Mobility può effettuare nuovi tentativi per consegne di report di consegna non riuscite, ovvero non riconosciute. Il Service Provider può scegliere il comportamento di nuovo tentativo preferito:
Nessun nuovo tentativo (predefinito) – il messaggio verrà ignorato se il tentativo di connessione fallisce, si verifica un timeout di lettura o per qualsiasi codice di errore HTTP.
Riprova – il messaggio verrà reinviato per ogni tipo di problema di connessione, timeout di lettura o conferma negativa.
Quando il retry per NAK è abilitato, è importante capire quali scenari genereranno un retry attempt da LINK Mobility e come funziona il retry. Ogni Service Provider ha la sua coda di retry, dove i messaggi sono ordinati in base al messaggio timestamp. Link Mobility cerca sempre di recapitare prima i messaggi più vecchi, anche se l'ordine individuale dei messaggi recapitati al Service Provider non è garantito. Il motivo principale per cui i messaggi vengono scartati dalla coda di ripetizione è uno dei due seguenti: o il TTL del messaggio scade o (teoricamente) la coda di ripetizione diventa piena. Il TTL dipende dall'operatore e dall'account, ovvero può variare a seconda dell'operatore e/o del tipo di messaggio, ad esempio SMS premium o SMS a tariffa standard.
I fornitori di servizi con la funzione di ripetizione abilitata devono controllare l'ID univoco del messaggio MT per assicurarsi che il messaggio non sia già stato ricevuto.
È importante che il fornitore del servizio rispetti queste semplici regole quando si verifica un errore durante l'elaborazione di un rapporto di consegna se il motivo dell'errore è: Temporaneo, ad esempio database non disponibile, dovrebbe essere restituito un NAK. LINK Mobility invierà nuovamente il messaggio.
È probabile che un tentativo permanente e uno di nuovo tentativo causino lo stesso tipo di problema, dovrebbe essere restituito un ACK. Ad esempioample, quando il messaggio non poteva essere analizzato correttamente o causava un errore di runtime imprevisto.
Agendo di conseguenza si garantirà che non si verifichino blocchi o riduzioni della produttività a causa del ripetuto invio di un rapporto di consegna.
10. Suggerimenti per l'implementazione
1. È possibile utilizzare il tuo web browser per inviare richieste all'API. Ciò rende molto facile esplorare e valutare i servizi senza alcuno strumento di sviluppo.
2. Si consiglia di usare Chrome o Firefox insieme a un'estensione come JSONView per visualizzare JSON con un formato gradevole.
3. Abbiamo utilizzato SoapUI per testare POST, l'autenticazione di base e per ispezionare i messaggi di richiesta e risposta HTTP non elaborati.
4. Il cURL strumento è utile per inviare richieste POST con autenticazione di base. Vedere exampqui sotto.
curl INVIARE \
-H “Tipo di contenuto: applicazione/x-www-form-urlcodificato” \
-H "Autorizzazione: Base am9objpjaGFuZ2VtZSA=" \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
Vedi anche:
Trasformare le comunicazioni personalizzate
Documenti / Risorse
 |
Guida all'implementazione della mobilità LINK REST API SMS [pdf] Guida utente Guida all'implementazione della mobilità REST API SMS, Mobilità, Guida all'implementazione REST API SMS, REST API SMS, API SMS, SMS |
