LINK Mobilitetsimplementeringsveiledning REST API SMS
LINK Mobility tilbyr en tjeneste for meldingslevering, mikrobetalinger og stedsbaserte tjenester. Plattformen fungerer som en transparent innholdsinnhenter og transaksjonsruter mellom tjenesteleverandører og operatører.
LINK Mobility gir en RESTful API som kan brukes til å få tilgang til LINK Mobility-tjenester som å sende SMS. Denne API-en er designet for å være enkel å bruke og kompatibel med alle moderne språk og rammeverk. Ved å bruke språket du velger, kan applikasjonen bruke Link Mobility REST API for å implementere kraftige meldings- og betalingsfunksjoner
© LINK Mobility, 10. mars 2021
Juridisk informasjon
Informasjonen i dette dokumentet er den eneste eiendommen og opphavsretten til Netsize. Den er konfidensiell og ment for strengt informativ bruk. Den er ikke bindende og kan endres uten varsel. Enhver uautorisert avsløring eller bruk skal anses som ulovlig.
Netsize™ og linkmobility™ er beskyttet av fransk, EEC og internasjonale lover om immaterielle rettigheter.
Alle andre oppgitte varemerker tilhører deres respektive eiere.
Ingenting i dette dokumentet skal tolkes som å gi noen lisens eller rettighet under Netsize patent, opphavsrett eller varemerke.
NETTSTØRRELSE
Société anonyme au capital de 5 478 070 euro
Siège social :62, avenue Emile Zola92100 Boulogne – Frankrike
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Dokumentets omfang
Dette dokumentet beskriver hvordan tjenesteleverandøren bruker LINK Mobility REST API for SMS. Den er beregnet på tekniske arkitekter og designere som implementerer tjenestene til tjenesteleverandøren.
1. Grunnleggende bruk
Det er veldig enkelt å sende en SMS. Du sender en HTTP-forespørsel til LINK Mobility som kan oppnås ved å bruke bare en web nettleser.
2. Funksjonell Overview
LINK Mobility-systemet gir følgende grunnleggende funksjonalitet for SMS-meldinger:
Sende SMS-meldinger med mobilterminering (MT), som tekst- eller binære (f.eks. WAP Push) premium- og standardprismeldinger.
Motta leveringsrapporter for innsendte MT-meldinger.
Motta Mobile Origined (MO) SMS-meldinger, premium og standard rate.
SMS REST API er dedikert til å sende standard rate MT SMS-meldinger.
API-en sender alle SMS-meldinger asynkront, og muliggjør funksjoner som:
«Fire-and-forget» – Tjenesteleverandøren ønsker å ha mer forutsigbare responstider og ønsker ikke å vente på resultatet fra Operatøren.
Prøv funksjonalitet på nytt – LINK Mobility vil sende meldingen på nytt hvis operatøren har midlertidige problemer.
2.1 Sende en SMS-melding
Tjenesteleverandør Netsize Consumer
- Send MT-melding
- Returner meldings-ID
- Send inn SMS-melding
- Levere leveringsrapport
- Send leveringsrapport
Den grunnleggende flyten for å sende SMS-meldinger er beskrevet som følger:
Tjenesteleverandøren sender en forespørsel om å sende en SMS-melding til en mottaker via LINK Mobility-systemet.
En meldings-ID returneres til tjenesteleverandøren. Denne IDen kan brukes til f.eks å korrelere meldingen med riktig leveringsrapport.
LINK Mobility håndterer ruting og leverer SMS-meldingen til den adresserte forbrukeren.
En leveringsrapport utløses, f.eks. når SMS-meldingen leveres til Forbrukerens enhet.
Leveringsrapporten sendes til Tjenesteleverandøren. Rapporten inneholder samme meldings-ID som ble returnert i trinn 2.
Alternativ flyt: Ugyldig forespørsel
Hvis de oppgitte parameterne eller brukerlegitimasjonen i forespørselen er ugyldig, returneres en feil til tjenesteleverandøren. Feilen indikerer årsaken til avvisningen og flyten avsluttes. Ingen meldings-IDer returneres.
3. Endepunkt
SMS-ressursen er tilgjengelig ved å bruke banen:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
For tilkoblingssikkerhet er LINK Mobility REST API kun tilgjengelig over HTTPS.
Link Mobility-serversertifikatet er signert av Thawte Server CA.
4. Drift
SMS-tjenesten tilbyr følgende operasjoner:
| Navn | Sti |
| Sende | /restapi/v1/sms/send |
4.1 Send
Sendeoperasjonen brukes til å sende en SMS til en enkelt mottaker.
Denne operasjonen er beregnet på både grunnleggende og avanserte brukere. I det enkleste tilfellet er det kun destinasjonsadresse og meldingstekst som kreves for å levere en SMS. LINK Mobility vil oppdage datakodingsskjemaet og utføre automatisk sammenkobling av en melding i flere meldingsdeler om nødvendig.
For avansert bruk kan tjenesteleverandøren bruke valgfrie parametere for total kontroll over meldingsformateringen inkludert brukerdataoverskriften.
Tjenesteleverandøren kan sende sammenkoblede meldinger, men klargjøring av brukerdata og brukerdatahode må gjøres av Tjenesteleverandør og meldingen må sendes ved hjelp av flere sendeforespørsler mot LINK Mobility.
5. Autentisering
Brukernavn og passord sendes inn i hver forespørsel ved hjelp av HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Påloggingsinformasjon sendes i en autorisasjonsoverskrift i HTTP-forespørselen. Klienten konstruerer overskriftsfeltet som beskrevet her:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
For eksample, hvis brukernavnet er john og changeme er passordet, er den resulterende autorisasjonsoverskriften:
Autorisasjon: Grunnleggende am9objpjaGFuZ2VtZSA=
Som en reserve kan brukernavnet og passordet sendes inn som forespørselsparametere. Dette anbefales kun for klienter som ikke støtter Basic Auth.
6. Sende inn en forespørsel
6.1 Spørrestreng
Forespørselsparametere sendes inn som en spørringsstreng som inneholder navn/verdi-par. Spørrestrengen er kodet ved hjelp av prosentkoding (URL koding).
http://www.w3schools.com/tags/ref_urlencode.asp
For eksample, Hei verden! er kodet som Hello+World%21.
6.2 Obligatoriske forespørselsparametere
| Navn | Maks lengde | Beskrivelse |
| destinasjonsadresse | 40 | MSISDN som SMS-meldingen skal sendes til, starter med landskode. Eksample: 46123456789. For noen markeder (hvor forbruker-MSISDN må være obfuskert) kan denne verdien også være et alfanumerisk alias, prefikset med "#". |
| meldingTekst | 1600 | Innholdet i SMS-meldingen. |
6.3 Valgfrie forespørselsparametere (for avansert bruk)
| Navn | Maks lengde | Beskrivelse |
| opprinnelsesadresse | 16 | Opprinnelsesadressen for den utgående SMS-meldingen. Type opprinnelsesadresse er definert av originatorTON-parameteren. Kort nummer maks lengde er 16. Alfanumerisk avsender er begrenset til GSM standard alfabet med maks lengde 11 tegn. MSISDN-avsenderens maksimale lengde er 15 (bruker samme format som destinationAddress-elementet). Kan utelates når originatingAddress og originatingTON velges av systemet. Denne funksjonen er markeds- og konfigurasjonsavhengig. Atferd kan variere med operatørintegrasjoner. |
| opphavsmannTON | 1 | Opprinnelsesadressens type nummer (TON): 0 – Kort nummer 1 – Alfanumerisk (maks lengde 11) 2 – MSISDN Kan utelates når originatingAddress og originatingTON velges av systemet. Denne funksjonen er markeds- og konfigurasjonsavhengig. Atferd kan variere med operatørintegrasjoner. |
| userDataHeader | 280 | Brukerdatahode sammen med brukerdata kan inneholde opptil 140, dvs. 280 når hekskodede oktetter. Denne parameteren er alltid hekskodet. |
| DCS | 3 | Datakodeskjema. Atferd kan variere med operatørintegrasjoner. |
| PID | 3 | Protokoll-ID. Atferd kan variere med operatørintegrasjoner. |
| relative ValidityTime | 6 | Relativ gyldighetstid i sekunder (i forhold til tiden for innsending til LINK Mobility). Maks verdi er 604800 (7 dager) og standard er 48 timer. Atferd kan variere med operatørintegrasjoner. |
| leveringstid | 20 | Tidligstamp når SMS-melding skal leveres (forsinket leveringstid). Se avsnitt om dato og klokkeslettformat. |
| statusReportFlags | 1 | Lever rapportforespørsel: 0 – Ingen leveringsrapport (standard) 1 – Leveringsrapport forespurt 9 – Serverleveringsrapport forespurt (LINK Mobility videresender ikke rapporten til tjenesteleverandøren, men gjør den tilgjengelig i rapporter osv.) |
| campaignName | 50 | LINK Mobility-transaksjonene er tagged med dette navnet. Den brukes til å gruppere transaksjoner i Link Mobility-rapporter. |
| maxConcatenatedMessages | 1 | En verdi mellom 1 og 10 som definerer hvor mange sammenkoblede meldinger som er tillatt. Standard er 3. |
| korrelasjons-ID | 100 | ID gitt av tjenesteleverandøren som vil gjentas i leveringsrapporten. |
| brukernavn | 100 | Levert som et alternativ til HTTP Basic Authentication. |
| passord | 100 | Levert som et alternativ til HTTP Basic Authentication. |
6.4 HTTP-forespørselsmetoder
For maksimal interoperabilitet støtter API-en både HTTP GET- og POST-forespørselsmetoder. Ingen andre HTTP-metoder er tillatt.
6.4.1 FÅ
Den kodede spørringsstrengen er lagt til URL.
BLI
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hei+verden%21
Autorisasjon: Grunnleggende am9objpjaGFuZ2VtZSA=
6.4.2 POST
Den kodede spørringsstrengen sendes inn i meldingsteksten for HTTP-forespørselen. Content-Type er application/x-www-form-urlkodet.
STOLPE https://europe.ipx.com/restapi/v1/sms/send
Vert: europe.ipx.com
Innholdstype: applikasjon / x-www-form-urlkodet
Autorisasjon: Grunnleggende am9objpjaGFuZ2VtZSA=
Innhold-lengde: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Dato og klokkeslett
Parametere i REST API som representerer dato og klokkeslett er alltid i UTC-tidssonen (Coordinated Universal Time). Tidspunktamps er representert som en streng med dette nøyaktige formatet:
2017-04-25T23:20:50Z
Dette representerer 20 minutter og 50 sekunder etter den 23. timen 25. april 2017 i UTC.
7. Svarmelding
Etter å ha mottatt og tolket en forespørselsmelding, svarer APIen med en HTTP-svarmelding.
7.1 HTTP-statuskode
REST API returnerer alltid HTTP-statuskode 200 OK for behandlede forespørsler. Meldingsteksten inneholder en parameter responseCode som brukes til å bestemme det nøyaktige resultatet.
7.2 Meldingstekst
Meldingsteksten består av JSON som beskriver utfallet av forespørselen.
http://json.org/
Link Mobility JSON er i samsvar med Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Responsparametere
| Navn | Maks lengde | Beskrivelse |
| responskode | 3 | 0 indikerer vellykket transaksjon. |
| svarmelding | 255 | Svartekstbeskrivelse, f.eks. feiltekst. |
| tidestamp | 20 | Dato og klokkeslett da LINK Mobility behandlet forespørselen. (Se dato/klokkeslett format delen). |
| traceId | 36 | Link Mobility intern identifikator. Brukes til support og feilsøking. |
| meldings-IDer | 10 x 36 | En rekke LINK Mobility unike meldings-IDer for hver vellykket melding (flere meldings-IDer returneres hvis meldingen er sammenkoblet). Utelatt ved feil. |
7.4 Eksampsvarene
Suksess
HTTP/1.1 200 OK
Innholdstype: application/json
Innhold-lengde: 144
Dato: tor 15. september 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Suksess”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Her er den samme JSON-formatert for lesbarhet:
{
«responskode“:0,
«svarmelding":"Suksess",
«tidestamp“:”2016-0915T13:20:31Z”,
«traceId“:”f678d30879fd4adc25f2”,
«meldings-IDer“:[“1-4850879008”]
}
Feil
HTTP/1.1 200 OK
Innholdstype: application/json
Innhold-lengde: 148
Dato: tor 15. september 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Ugyldig pålogging eller uautorisert API-bruk”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Suksess
HTTP/1.1 200 OK
Innholdstype: application/json
Innhold-lengde: 144
Dato: tor 15. september 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Suksess”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Her er den samme JSON-formatert for lesbarhet:
{
«responskode“:0,
«svarmelding":"Suksess",
«tidestamp“:”2016-0915T13:20:31Z”,
«traceId“:”f678d30879fd4adc25f2”,
«meldings-IDer“:[“1-4850879008”]
}
Feil
HTTP/1.1 200 OK
Innholdstype: application/json
Innhold-lengde: 148
Dato: tor 15. september 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Ugyldig pålogging eller uautorisert API-bruk”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Svarkoder
Følgende svarkoder kan returneres i sendesvaret:
| Kode | Tekst | Beskrivelse |
| 0 | Suksess | Vellykket utført. |
| 1 | Ugyldig pålogging eller uautorisert API-bruk | Feil brukernavn eller passord eller tjenesteleverandør er sperret av LINK Mobility. |
| 2 | Forbrukeren er blokkert av Link Mobility | Forbrukeren er blokkert av LINK Mobility. |
| 3 | Driften leveres ikke av LINK Mobility | Operasjonen er blokkert for tjenesteleverandøren. |
| 4 | Forbrukeren er ukjent for LINK Mobility | Forbrukeren er ukjent for LINK Mobility. Eller hvis alias ble brukt i forespørselen; alias ikke funnet. |
| 5 | Forbrukeren har blokkert denne tjenesten i LINK Mobility | Forbrukeren har blokkert denne tjenesten i LINK Mobility. |
| 6 | Opprinnelsesadressen støttes ikke | Opprinnelsesadressen støttes ikke. |
| 7 | Alfa-opprinnelsesadresse støttes ikke av kontoen | Alfa-opprinnelsesadressen støttes ikke av kontoen. |
| 8 | MSISDN-opprinnelsesadresse støttes ikke | MSISDN-opprinnelsesadressen støttes ikke. |
| 9 | GSM utvidet støttes ikke | GSM utvidet støttes ikke. |
| 10 | Unicode støttes ikke | Unicode støttes ikke. |
| 11 | Statusrapport støttes ikke | Statusrapport støttes ikke. |
| 12 | Nødvendig funksjon støttes ikke | Den nødvendige evnen (annet enn de ovennevnte) for å sende meldingen støttes ikke. |
| 13 | Innholdsleverandørens maksimale strupehastighet er overskredet | Tjenesteleverandøren sender SMS-meldingene til LINK Mobility for raskt. |
| 14 | Protokoll-ID støttes ikke av kontoen | Protokoll-ID støttes ikke. |
| 15 | Meldingssammenkoblingsgrensen er overskredet | Antallet sammenkoblede meldinger overskrider det maksimale antallet forespurte. |
| 16 | Kan ikke rute melding. | LINK Mobility kunne ikke rute meldingen. |
| 17 | Forbudt tidsperiode | Ikke tillatt å sende melding i tidsperioden |
| 18 | For lav saldo på tjenesteleverandørens konto | Tjenesteleverandør er blokkert på grunn av for lav saldo |
| 50 | Delvis suksess | Delvis suksess når du sender en SMS-melding til flere mottakere. |
| 99 | Intern serverfeil | Annen Link Mobility-feil, kontakt LINK Mobility-støtte for mer informasjon. |
| 100 | Ugyldig destinasjonsadresse | Destinasjonsadressen (MSISDN eller alias) er ugyldig. |
| 102 | Ugyldig referert (lenket) ID | Referanse-ID-en er ugyldig, kanskje referanse-ID-en er allerede brukt, for gammel eller ukjent. |
| 103 | Ugyldig kontonavn | Kontonavnet er ugyldig. |
| 105 | Ugyldig tjenestemetadata | Tjenestens metadata er ugyldige. |
| 106 | Ugyldig opprinnelsesadresse | Opprinnelsesadressen er ugyldig. |
| 107 | Ugyldig alfanumerisk opprinnelsesadresse | Den alfanumeriske opprinnelsesadressen er ugyldig. |
| 108 | Ugyldig gyldighetstid | Gyldighetstiden er ugyldig. |
| 109 | Ugyldig leveringstid | Leveringstiden er ugyldig. |
| 110 | Ugyldig meldingsinnhold/brukerdata | Brukerdataene, dvs. SMS-meldingen, er ugyldige. |
| 111 | Ugyldig meldingslengde | Lengden på SMS-meldingen er ugyldig. |
| 112 | Ugyldig brukerdataoverskrift | Brukerdataoverskriften er ugyldig. |
| 113 | Ugyldig datakodeskjema | DCS-en er ugyldig. |
| 114 | Ugyldig protokoll-ID | PID-en er ugyldig. |
| 115 | Ugyldige statusrapportflagg | Statusrapportflaggene er ugyldige. |
| 116 | Ugyldig TON | Opphavsmannen TON er ugyldig. |
| 117 | Ugyldig campaign navn | campaignnavnet er ugyldig. |
| 120 | Ugyldig grense for maksimalt antall sammenkoblede meldinger | Det maksimale antallet sammenkoblede meldinger er ugyldig. |
| 121 | Ugyldig msisdn-opprinnelsesadresse | MSISDN-opprinnelsesadressen er ugyldig. |
| 122 | Ugyldig korrelasjons-ID | Korrelasjons-ID-en er ugyldig. |
8. Valgfrie funksjoner
8.1 MSISDN-korreksjon
MSISDN-korreksjon er en valgfri funksjon som kan aktiveres av LINK Mobility-støtte hvis du blir bedt om det.
Denne funksjonen vil korrigere destinasjonsadresser og justere dem til det nødvendige E.164-formatet. I tillegg til formatkorrigering kan systemet også utføre markedsspesifikk funksjonalitet som å oversette internasjonale franske tall for å korrigere DOM-TOM (départements et territoires d'outre-mer)-numre når det er aktuelt.
Nedenfor er en rekke eksamples av rettelser:
| Innsendt destinasjonsadresse | Korrigert destinasjonsadresse |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (fransk nummer oversatt til et DOM-TOM nummer) |
I tillegg er det mulig å tillate nasjonale telefonnumre for et valgt marked. Når denne funksjonen er aktivert, må alle internasjonale numre for andre markeder sendes med et første "+"-tegn for å skille dem fra det valgte markedet.
Nedenfor er flere eksamples av korrigeringer gjort ved bruk av Sverige (landskode 46) som standardmarked for nasjonale numre.
| Innsendt destinasjonsadresse | Korrigert destinasjonsadresse |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Ugyldig siden '+'-tegnet mangler |
Merk at det korrigerte MSISDN vil bli brukt av LINK Mobility og det vil bli returnert i leveringsrapportene.
Ta kontakt med LINK Mobility-støtte for mer informasjon.
8.2 Tegnskifte
Tegnerstatning er en valgfri funksjon som kan aktiveres av LINK Mobility-støtte hvis du blir bedt om det.
Denne funksjonen vil oversette ikke-GSM-alfabettegn i brukerdataene (SMS-tekst) til tilsvarende GSM-alfabettegn når DCS er satt til "GSM" (17). For eksample "Seqüência de teste em Português" vil bli oversatt til "Sequüencia de teste em Portugues".
9. Leveringsrapporter
Tjenesteleverandøren kan, hvis den er klargjort, be om leveringsrapporter for SMS-meldinger eller leveringsvarsler for MT-meldingene som sendes. Disse rapportene utløses i Operator SMSC når MT-meldingen enten leveres til den målrettede forbrukeren eller slettes, f.eks. utløpt eller, av en eller annen grunn, ikke kan rutes.
Kun endelig status for SMS-meldingen rapporteres til Tjenesteleverandøren, dvs. levert eller slettet. Kun én rapport per MT-melding genereres. Med slettet status kan en årsakskode gjelde. Denne årsakskoden spesifiserer årsaken til at SMS-meldingen ikke ble levert.
Rapportene rutes gjennom LINK Mobility og sendes til tjenesteleverandøren ved hjelp av HTTP-protokollen.
For å motta rapporter, må tjenesteleverandøren implementere f.eksample en Java Servlet eller en ASP.NET-side. Begge mottar HTTP GET eller POST-forespørsler.
Parametere
Forespørselen inneholder følgende parametere:
| Parameter | Type | M/O/I* | Standardverdi | Maks lengde | Beskrivelse |
| MessageId | streng | M | – | 22 | Meldings-IDen til MT-meldingen som denne rapporten tilsvarer. |
| Destinasjonsadresse | streng | M | – | 40 | Forbrukerens MSISDN, dvs. destinasjonsadressen til den opprinnelige MT-meldingen. |
| Statuskode | heltall | M | 1 | Statuskode indikerer statusen til MT-meldingen. Gjeldende statuskoder er: 0 – Levert 2 – Slettet (årsakskode gjelder) |
|
| TimeStamp | streng | M | – | 20 | Tidspunkt som indikerer når leveringsrapporten ble mottatt av LINK Mobility. Tidssonen for tideneamp er CET eller CEST (med sommertid som definert for EU). Format: ååååMMdd TT:mm:ss. |
| Operatør | streng | M | – | 100 | Navnet på operatøren som ble brukt ved sending av SMS-meldingen eller kontonavnet som ble brukt ved sending av SMS-meldingen. En liste over tilgjengelige operatører leveres av LINK Mobility-støtte. |
| Årsakskode | heltall | O | – | 3 | Årsakskode angir hvorfor meldingen havnet i statusen slettet. Gjeldende årsakskoder er: 100 – Utløpt 101 – Avvist 102 – Formatfeil 103 – Annen feil 110 – Abonnent ukjent 111 – Abonnent sperret 112 – Abonnent ikke klargjort 113 – Abonnent utilgjengelig 120 – SMSC-feil 121 – SMSC-overbelastning 122 – SMSC-roaming 130 – Håndsettfeil 131 – Håndsettminnet overskredet Atferd kan variere med operatørintegrasjoner. |
| OperatørtidStamp | streng | O | – | 20 | Tid som indikerer når rapporten ble utløst i SMSC til operatøren (hvis gitt av operatøren). Tidssonen for tideneamp er CET eller CEST (med sommertid som definert for EU). Format: ååååMMdd TT:mm:ss. |
| StatusTekst | streng | O | – | 255 | Plassholder for tilleggsinformasjon fra Operatøren, f.eks klartekstbeskrivelse av status/årsak. Atferd kan variere med operatørintegrasjoner. |
| Korrelasjons-ID | streng | O | – | 100 | Korrelasjons-IDen oppgitt i SendRequest eller SendTextRequest. |
| Operatørnettverkskode | heltall | O | – | 6 | Mobilnettverkskoden (MCC + MNC) til operatøren. |
* M = Obligatorisk, O = Valgfritt, I = Ignorert.
Tjenesteleverandøren må gi LINK Mobility med målet URL for leveringsrapporter (valgfritt inkludert legitimasjon for grunnleggende HTTP-autentisering). Tjenesteleverandøren kan velge hvilken foretrukket HTTP-metode som skal brukes:
HTTP POST (anbefalt)
HTTP GET.
Example ved hjelp av HTTP GET (levert):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example ved hjelp av HTTP GET (ikke levert, operatøren har oppgitt timetamp for arrangementet):
Parametrene er URL encodedi.
Tegnkoding:
Tjenesteleverandøren kan velge hvilken foretrukket tegnkoding som skal brukes:
UTF-8 (anbefalt)
ISO-8859-1.
9.1 Tjenesteleverandørens bekreftelse
Tjenesteleverandøren bør bekrefte hver leveringsrapport. Bekreftelsen kan være positiv, dvs. at leveringsrapporten er mottatt, eller negativ, dvs. mislykket.
Vennligst merk: LINK Mobility har en lesetid for kvitteringer på 30 sekunder for leveringsrapporter. Et tidsavbrudd vil utløse et nytt leveringsforsøk (hvis gjenforsøk aktivert) eller en kansellering av leveringen (hvis nytt forsøk er deaktivert). Dette betyr at tjenesteleverandørapplikasjonen må sørge for raske responstider, spesielt ved høy belastning.
Det anbefales sterkt å bekrefte leveringsrapporten til LINK Mobility før du behandler den.
Regelen for positiv og negativ anerkjennelse er beskrevet som følger:
Positiv bekreftelse, ACK, leveringsrapport levert:
HTTP 200-rekkesvarskode i kombinasjon med følgende XML-formaterte innhold:
Negativ bekreftelse, NAK, leveringsrapport ikke levert:
Ethvert svar annet enn positiv bekreftelse, f.eksample, utløses en negativ bekreftelse av en hvilken som helst HTTP-feilkode eller følgende XML-innhold:
XML-innholdet kan brukes til å kontrollere mekanismen for forsøk på LINK Mobility. En NAK vil forårsake et nytt forsøk, hvis aktivert. For tjenesteleverandører som ikke er konfigurert for prøvemekanismen på nytt, er XML-innholdet valgfritt.
Nedenfor er en HTTP POST-forespørsel og svar f.eksampdel av en leveringsrapport levert til en tjenesteleverandør:
HTTP-forespørsel:
POST /context/app HTTP/1.1
Innholdstype: applikasjon / x-www-form-urlkodet;charset=utf-8
Vert: server:port
Innhold-lengde: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-svar:
HTTP/1.1 200 OK
Innholdstype: tekst/vanlig
9.2 Prøv på nytt
LINK Mobility-systemet kan utføre gjenforsøk for mislykkede, dvs. ikke bekreftede, leveringsrapporter. Tjenesteleverandøren kan velge ønsket oppførsel på nytt:
Ingen forsøk på nytt (standard) – meldingen vil bli forkastet hvis tilkoblingsforsøk mislykkes, lesetidsavbrudd eller for en HTTP-feilkode.
Prøv på nytt – meldingen vil bli sendt på nytt for hver type tilkoblingsproblem, lesetidsavbrudd eller negativ bekreftelse.
Når nytt forsøk for NAK er aktivert, er det viktig å forstå hvilke scenarier som vil generere et nytt forsøk fra LINK Mobility og hvordan gjenforsøket fungerer. Hver tjenesteleverandør har sin egen prøvekø, hvor meldinger er sortert i henhold til meldingstidenamp. Link Mobility prøver alltid å levere eldre meldinger først, selv om den individuelle rekkefølgen av meldinger levert til tjenesteleverandøren ikke er garantert. Hovedårsaken til at meldinger blir forkastet fra prøvekøen er én av to årsaker: enten utløper meldingen TTL eller (teoretisk sett) blir prøvekøen full. TTL-en er operatør- og kontoavhengig, dvs. kan variere avhengig av operatør og/eller meldingstype, f.eks. premium SMS eller standardpris SMS-melding.
En tjenesteleverandør med aktivert forsøk på nytt må sjekke den unike ID-en til MT-meldingen for å sikre at meldingen ikke allerede er mottatt.
Det er viktig for Tjenesteyter å forholde seg til disse enkle reglene når det oppstår feil under behandling av en leveringsrapport dersom årsaken til feilen er: Midlertidig, f.eks database ikke tilgjengelig, en NAK skal returneres. LINK Mobility vil sende meldingen på nytt.
Permanent og et nytt forsøk vil sannsynligvis forårsake samme type problem, en ACK bør returneres. For eksample, når meldingen ikke kunne analyseres riktig eller forårsaket en uventet kjøretidsfeil.
Å handle deretter vil sikre at det ikke oppstår blokkering eller forringelse av gjennomstrømmingen på grunn av at en leveringsrapport sendes gjentatte ganger.
10. Implementeringstips
1. Det er mulig å bruke din web nettleser for å sende inn forespørsler til API. Dette gjør det veldig enkelt å utforske og evaluere tjenestene uten noen utviklingsverktøy.
2. Chrome eller Firefox anbefales sammen med en utvidelse som JSONView for å vise ganske formatert JSON.
3. Vi har brukt SoapUI for å teste POST, grunnleggende autentisering og for å inspisere rå HTTP-forespørsel og svarmeldinger.
4. cURL verktøyet er nyttig for å sende inn POST-forespørsler med grunnleggende autentisering. Se eksample nedenfor.
curl POST \
-H “Content-Type: application/x-www-form-urlkodet" \
-H “Autorisasjon: Grunnleggende am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
Forvandling av personlig kommunikasjon
Dokumenter / Ressurser
 | Mobilitetsimplementeringsveiledning REST API SMS |
Referanser
- Brukerhåndbokmanual.tools