LINK Mobiliteit Implementatiehandleiding REST API SMS
LINK Mobility biedt een service voor berichtlevering, microbetalingen en locatiegebaseerde services. Het platform fungeert als een transparante, white-label content acquirer en transactierouter tussen serviceproviders en operators.
LINK Mobility biedt een RESTful API die kan worden gebruikt om toegang te krijgen tot LINK Mobility-services zoals het verzenden van sms. Deze API is ontworpen om eenvoudig te gebruiken en compatibel te zijn met alle moderne talen en frameworks. Met de taal van uw keuze kan uw applicatie de Link Mobility REST API gebruiken om krachtige berichten- en betalingsmogelijkheden te implementeren
© LINK Mobility, 10 maart 2021
Juridische informatie
De informatie in dit document is het exclusieve eigendom en copyright van Netsize. Het is vertrouwelijk en bedoeld voor strikt informatief gebruik. Het is niet bindend en kan zonder kennisgeving worden gewijzigd. Elke ongeautoriseerde openbaarmaking of gebruik wordt beschouwd als onwettig.
Netsize™ en linkmobility™ worden beschermd door Franse, EEG- en internationale wetten op het gebied van intellectuele eigendom.
Alle overige genoemde handelsmerken zijn het exclusieve eigendom van hun respectievelijke eigenaren.
Niets in dit document mag worden opgevat als het verlenen van een licentie of recht onder het patent, auteursrecht of handelsmerk van Netsize.
NETGROOTTE
Anonieme vennootschap met kapitaal van 5 478 070 euro
Siège social:62, avenue Emile Zola92100 Boulogne – Frankrijk
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Reikwijdte van document
Dit document beschrijft hoe de Service Provider de LINK Mobility REST API voor SMS gebruikt. Het is bedoeld voor technische architecten en ontwerpers die de services van de Service Provider implementeren.
1. Basisgebruik
Het is heel eenvoudig om een SMS te sturen. U stuurt een HTTP-verzoek naar LINK Mobility, wat kan worden bereikt met slechts een web browser.
2. Functioneel Overview
Het LINK Mobility-systeem biedt de volgende basisfunctionaliteit voor SMS-berichten:
Het verzenden van MT-SMS-berichten (Mobile Terminated), zoals tekst- of binaire (bijv. WAP Push) premium- en standaardtariefberichten.
Ontvangst van leveringsrapporten voor verzonden MT-berichten.
Ontvangen van SMS-berichten afkomstig van mobiele telefoons (MO), tegen premium- en standaardtarief.
De SMS REST API is bedoeld voor het versturen van MT SMS-berichten tegen standaardtarief.
De API verstuurt alle sms-berichten asynchroon, waardoor functies zoals:
“Fire-and-forget” – de serviceprovider wil voorspelbaardere responstijden en wil niet wachten op het resultaat van de operator.
Opnieuw proberen-functionaliteit – LINK Mobility verstuurt het bericht opnieuw als de Operator tijdelijke problemen heeft.
2.1 Een SMS-bericht versturen
Dienstverlener Netsize Consumer
- Stuur MT-bericht
- Retourbericht-ID
- SMS-bericht verzenden
- Lever leveringsrapport
- Verzenden van leveringsrapport
De basisstroom voor het versturen van een SMS-bericht wordt als volgt beschreven:
De Dienstverlener doet een verzoek om een SMS-bericht te versturen naar een ontvanger via het LINK Mobility-systeem.
Een bericht-ID wordt teruggestuurd naar de Service Provider. Deze ID kan bijvoorbeeld worden gebruikt om het bericht te correleren met het juiste bezorgingsrapport.
LINK Mobility verzorgt de routering en bezorgt het SMS-bericht aan de geadresseerde Consument.
Er wordt een afleverrapport gegenereerd, bijvoorbeeld wanneer het sms-bericht op het apparaat van de consument is afgeleverd.
Het leveringsrapport wordt naar de serviceprovider verzonden. Het rapport bevat dezelfde bericht-ID als die in stap 2 is geretourneerd.
Alternatieve stroom: ongeldig verzoek
Als de opgegeven parameters of gebruikersreferenties in de aanvraag ongeldig zijn, wordt er een fout geretourneerd naar de serviceprovider. De fout geeft de reden voor de afwijzing aan en de flow eindigt. Er worden geen bericht-ID's geretourneerd.
3. Eindpunt
U krijgt toegang tot de SMS-bron via het pad:
/restaureren/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Voor de beveiliging van de verbinding is de LINK Mobility REST API alleen toegankelijk via HTTPS.
Het Link Mobility-servercertificaat is ondertekend door Thawte Server CA.
4. Operaties
De SMS-service biedt de volgende bewerkingen:
| Naam | Pad |
| Versturen | /restapi/v1/sms/verzenden |
4.1 Verzenden
Met de verzendbewerking kunt u een sms-bericht naar één ontvanger verzenden.
Deze bewerking is bedoeld voor zowel basis- als gevorderde gebruikers. In het eenvoudigste geval zijn alleen het bestemmingsadres en de berichttekst vereist om een sms te bezorgen. LINK Mobility detecteert het Data Coding Scheme en voert indien nodig automatische samenvoeging van een bericht in meerdere berichtdelen uit.
Voor geavanceerd gebruik kan de serviceprovider optionele parameters gebruiken voor volledige controle over de berichtopmaak, inclusief de gebruikersgegevensheader.
De Service Provider kan aaneengeschakelde berichten versturen, maar de voorbereiding van de gebruikersgegevens en de header van de gebruikersgegevens moet door de Service Provider worden gedaan en het bericht moet via meerdere verzendverzoeken naar LINK Mobility worden verzonden.
5. Authenticatie
Gebruikersnaam en wachtwoord worden bij elke aanvraag meegestuurd via het HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Credentials worden verzonden in een Authorization header in de HTTP-aanvraag. De client construeert het headerveld zoals hier beschreven:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Bijvoorbeeldample, als de gebruikersnaam john is en changeme het wachtwoord, dan is de resulterende Authorization header:
Autorisatie: Basis am9objpjaGFuZ2VtZSA=
Als fall-back kunnen de gebruikersnaam en het wachtwoord worden ingediend als aanvraagparameters. Dit wordt alleen aanbevolen voor clients die Basic Auth niet ondersteunen.
6. Een verzoek indienen
6.1 Zoekreeks
Aanvraagparameters worden ingediend als een queryreeks met naam/waardeparen. De queryreeks wordt gecodeerd met Percent Encoding (URL codering).
http://www.w3schools.com/tags/ref_urlencode.asp
Bijvoorbeeldample, Hallo Wereld! is gecodeerd als Hallo+Wereld%21.
6.2 Verplichte aanvraagparameters
| Naam | Maximale lengte | Beschrijving |
| bestemmingAdres | 40 | De MSISDN waarnaar het SMS-bericht moet worden verzonden, beginnend met de landcode. Bijv.ampadres: 46123456789. Voor sommige markten (waar de Consumer MSISDN moet worden verduisterd) kan deze waarde ook een alfanumerieke alias zijn, voorafgegaan door “#”. |
| berichtTekst | 1600 | De inhoud van het SMS-bericht. |
6.3 Optionele aanvraagparameters (voor geavanceerd gebruik)
| Naam | Maximale lengte | Beschrijving |
| oorspronkelijkAdres | 16 | Het oorspronkelijke adres voor het uitgaande SMS-bericht. Het type van het oorspronkelijke adres wordt gedefinieerd door de originatorTON-parameter. De maximale lengte van het korte nummer is 16. De alfanumerieke afzender is beperkt tot het standaard GSM-alfabet met een maximale lengte van 11 tekens. De maximale lengte van de MSISDN-verzender is 15 (met dezelfde indeling als het element destinationAddress). Kan worden weggelaten wanneer het systeem het oorspronkelijk adres en de oorspronkelijk ton selecteert. Deze functie is afhankelijk van de markt en de configuratie. Gedrag kan variëren afhankelijk van Operator-integraties. |
| originatorTON | 1 | Het type nummer van het oorspronkelijke adres (TON): 0 – Kort nummer 1 – Alfanumeriek (max. lengte 11) 2 – MSISDN Kan worden weggelaten wanneer het systeem het oorspronkelijk adres en de oorspronkelijk ton selecteert. Deze functie is afhankelijk van de markt en de configuratie. Gedrag kan variëren afhankelijk van Operator-integraties. |
| gebruikersDataHeader | 280 | User Data Header kan samen met de User Data maximaal 140, dwz 280 indien hex-gecodeerd, octetten bevatten. Deze parameter is altijd hex-gecodeerd. |
| DCS | 3 | Gegevenscoderingsschema. Gedrag kan variëren afhankelijk van Operator-integraties. |
| PID | 3 | Protocol-ID. Gedrag kan variëren afhankelijk van Operator-integraties. |
| relatieveValiditeitTijd | 6 | Relatieve geldigheidstijd in seconden (relatief ten opzichte van de tijd voor de indiening bij LINK Mobility). Maximale waarde is 604800 (7 dagen) en de standaardwaarde is 48 uur. Gedrag kan variëren afhankelijk van Operator-integraties. |
| levertijd | 20 | Tijdstipamp wanneer het SMS-bericht afgeleverd moet worden (vertraagde bezorgtijd). Zie het gedeelte over datum- en tijdnotatie. |
| statusRapportVlaggen | 1 | Rapportaanvraag indienen: 0 – Geen bezorgrapport (standaard) 1 – Leveringsrapport aangevraagd 9 – Serverleveringsrapport aangevraagd (LINK Mobility stuurt het rapport niet door naar de serviceprovider, maar maakt het beschikbaar in rapporten enz.) |
| campaignName | 50 | De LINK Mobility-transacties zijn tagged met deze naam. Het wordt gebruikt om transacties te groeperen in Link Mobility-rapporten. |
| maxGeconcateneerdeBerichten | 1 | Een waarde tussen 1 en 10 die definieert hoeveel geconcateneerde berichten zijn toegestaan. Standaard is 3. |
| correlatie-ID | 100 | De door de serviceprovider verstrekte ID wordt weergegeven in het leveringsrapport. |
| gebruikersnaam | 100 | Wordt aangeboden als alternatief voor HTTP Basic Authentication. |
| wachtwoord | 100 | Wordt aangeboden als alternatief voor HTTP Basic Authentication. |
6.4 HTTP-aanvraagmethoden
Voor maximale interoperabiliteit ondersteunt de API zowel HTTP GET als POST-aanvraagmethoden. Andere HTTP-methoden zijn niet toegestaan.
6.4.1 KRIJGEN
De gecodeerde queryreeks wordt toegevoegd aan de URL.
KRIJGEN
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hallo+Wereld%21
Autorisatie: Basis am9objpjaGFuZ2VtZSA=
6.4.2 POSTEN
De gecodeerde queryreeks wordt ingediend in de berichttekst van de HTTP-aanvraag. Het contenttype is application/x-www-form-urlgecodeerd.
NA https://europe.ipx.com/restapi/v1/sms/send
Gastheer: europe.ipx.com
Inhoudstype: application/x-www-form-urlgecodeerd
Autorisatie: Basis am9objpjaGFuZ2VtZSA=
Inhoud-lengte: 57
bestemmingsAdres=46123456789&berichttekst=Hallo+Wereld%21
6.5 Datum en tijd
Parameters in de REST API die datum en tijd weergeven, zijn altijd in de UTC-tijdzone (Coordinated Universal Time).amps worden weergegeven als een tekenreeks met dit exacte formaat:
2017-04-25T23:20:50Z
Dit komt overeen met 20 minuten en 50 seconden na het 23e uur van 25 april 2017 in UTC.
7. Reactiebericht
Nadat een aanvraagbericht is ontvangen en geïnterpreteerd, reageert de API met een HTTP-antwoordbericht.
7.1 HTTP-statuscode
De REST API retourneert altijd HTTP-statuscode 200 OK voor verwerkte verzoeken. De berichttekst bevat een parameter responseCode die wordt gebruikt om de exacte uitkomst te bepalen.
7.2 Berichttekst
De berichttekst bestaat uit JSON-gegevens die de uitkomst van het verzoek beschrijven.
http://json.org/
Link Mobility JSON voldoet aan de Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Responsparameters
| Naam | Maximale lengte | Beschrijving |
| antwoordcode | 3 | 0 geeft aan dat de transactie succesvol is. |
| antwoordBericht | 255 | Tekstuele beschrijving van het antwoord, bijvoorbeeld fouttekst. |
| tijdamp | 20 | Datum en tijd waarop LINK Mobility het verzoek heeft verwerkt. (Raadpleeg het gedeelte over datum-/tijdnotatie). |
| trace-ID | 36 | Link Mobility interne identificatie. Gebruikt voor ondersteuning en probleemoplossing. |
| bericht-ID's | 10x36 | Array met unieke LINK Mobility-bericht-ID's voor elk succesvol bericht (er worden meerdere bericht-ID's geretourneerd als het bericht wordt samengevoegd). Weggelaten indien mislukt. |
7.4 voorbeeldampde reacties
Succes
HTTP/1.1 200 OK
Inhoudstype: application/json
Inhoud-lengte: 144
Datum: Do, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Succes”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hier is dezelfde JSON, geformatteerd voor leesbaarheid:
{
“antwoordcode“:0,
“antwoordBericht":"Succes",
“tijdamp“:”2016-0915T13:20:31Z”,
“trace-ID“:”f678d30879fd4adc25f2”,
“bericht-ID's“:[“1-4850879008”]}
Mislukking
HTTP/1.1 200 OK
Inhoudstype: application/json
Inhoud-lengte: 148
Datum: Do, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Ongeldige login of ongeautoriseerd API-gebruik”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Succes
HTTP/1.1 200 OK
Inhoudstype: application/json
Inhoud-lengte: 144
Datum: Do, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Succes”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hier is dezelfde JSON, geformatteerd voor leesbaarheid:
{
“antwoordcode“:0,
“antwoordBericht":"Succes",
“tijdamp“:”2016-0915T13:20:31Z”,
“trace-ID“:”f678d30879fd4adc25f2”,
“bericht-ID's“:[“1-4850879008”]}
Mislukking
HTTP/1.1 200 OK
Inhoudstype: application/json
Inhoud-lengte: 148
Datum: Do, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Ongeldige login of ongeautoriseerd API-gebruik”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Antwoordcodes
De volgende antwoordcodes kunnen worden geretourneerd in het verzendantwoord:
| Code | Tekst | Beschrijving |
| 0 | Succes | Succesvol uitgevoerd. |
| 1 | Ongeldige login of ongeautoriseerd API-gebruik | Een onjuiste gebruikersnaam, wachtwoord of serviceprovider wordt door LINK Mobility geblokkeerd. |
| 2 | Consument wordt geblokkeerd door Link Mobility | De Consument wordt geblokkeerd door LINK Mobility. |
| 3 | De werking wordt niet verzorgd door LINK Mobility | De bewerking is geblokkeerd voor de serviceprovider. |
| 4 | De consument is onbekend bij LINK Mobility | De Consument is onbekend bij LINK Mobility. Of als er een alias is gebruikt in de aanvraag: alias niet gevonden. |
| 5 | Consument heeft deze service geblokkeerd in LINK Mobility | De Consument heeft deze dienst geblokkeerd in LINK Mobility. |
| 6 | Het oorspronkelijke adres wordt niet ondersteund | Het oorspronkelijke adres wordt niet ondersteund. |
| 7 | Alfa-oorsprongadres wordt niet ondersteund door account | Het alfa-oorspronkelijke adres wordt niet ondersteund door het account. |
| 8 | MSISDN-oorsprongsadres wordt niet ondersteund | Het MSISDN-oorsprongsadres wordt niet ondersteund. |
| 9 | GSM uitgebreid niet ondersteund | GSM uitgebreid wordt niet ondersteund. |
| 10 | Unicode wordt niet ondersteund | Unicode wordt niet ondersteund. |
| 11 | Statusrapport niet ondersteund | Statusrapport wordt niet ondersteund. |
| 12 | Vereiste capaciteit wordt niet ondersteund | De vereiste functionaliteit (behalve de bovenstaande) voor het verzenden van het bericht wordt niet ondersteund. |
| 13 | De maximale bandbreedtebeperking van de contentprovider is overschreden | De serviceprovider verstuurt de sms-berichten te snel naar LINK Mobility. |
| 14 | Protocol-ID wordt niet ondersteund door account | Protocol-ID wordt niet ondersteund. |
| 15 | Limiet voor berichtensamenvoeging overschreden | Het aantal aaneengeschakelde berichten overschrijdt het maximaal aangevraagde aantal. |
| 16 | Bericht kan niet worden gerouteerd. | LINK Mobility kon het bericht niet routeren. |
| 17 | Verboden tijdsperiode | Het is niet toegestaan om berichten te versturen tijdens de tijdsperiode |
| 18 | Te laag saldo op de rekening van de serviceprovider | Dienstverlener is geblokkeerd vanwege Te laag saldo |
| 50 | Gedeeltelijk succes | Gedeeltelijk succes bij het versturen van een SMS-bericht naar meerdere ontvangers. |
| 99 | Interne serverfout | Andere Link Mobility-fout. Neem contact op met de LINK Mobility-ondersteuning voor meer informatie. |
| 100 | Ongeldig bestemmingsadres | Het bestemmingsadres (MSISDN of alias) is ongeldig. |
| 102 | Ongeldige gerefereerde (gekoppelde) ID | De referentie-ID is ongeldig. Mogelijk wordt de referentie-ID al gebruikt, is deze te oud of onbekend. |
| 103 | Ongeldige accountnaam | De accountnaam is ongeldig. |
| 105 | Ongeldige servicemetagegevens | De servicemetagegevens zijn ongeldig. |
| 106 | Ongeldig herkomstadres | Het oorspronkelijke adres is ongeldig. |
| 107 | Ongeldig alfanumeriek herkomstadres | Het alfanumerieke herkomstadres is ongeldig. |
| 108 | Ongeldige geldigheidstijd | De geldigheidsduur is ongeldig. |
| 109 | Ongeldige levertijd | De levertijd is ongeldig. |
| 110 | Ongeldige berichtinhoud/gebruikersgegevens | De gebruikersgegevens, d.w.z. het sms-bericht, zijn ongeldig. |
| 111 | Ongeldige berichtlengte | De lengte van het SMS-bericht is ongeldig. |
| 112 | Ongeldige gebruikersgegevenskop | De header van de gebruikersgegevens is ongeldig. |
| 113 | Ongeldig gegevenscoderingsschema | De DCS is ongeldig. |
| 114 | Ongeldige protocol-ID | De PID is ongeldig. |
| 115 | Ongeldige statusrapportvlaggen | De statusrapportvlaggen zijn ongeldig. |
| 116 | Ongeldige TON | De originator TON is ongeldig. |
| 117 | Ongeldige campign naam | De campnaam is ongeldig. |
| 120 | Ongeldige limiet voor maximaal aantal aaneengeschakelde berichten | Het maximale aantal aaneengeschakelde berichten is ongeldig. |
| 121 | Ongeldig msisdn-oorsprongsadres | Het MSISDN-oorsprongsadres is ongeldig. |
| 122 | Ongeldige correlatie-ID | De correlatie-ID is ongeldig. |
8. Optionele functies
8.1 MSISDN-correctie
MSISDN-correctie is een optionele functie die indien gewenst kan worden ingeschakeld via LINK Mobility-ondersteuning.
Deze functie corrigeert bestemmingsadressen en stemt ze af op het vereiste E.164-formaat. Naast formaatcorrectie kan het systeem ook marktspecifieke functionaliteit uitvoeren, zoals het vertalen van internationale Franse nummers om DOM-TOM-nummers (départements et territoires d'outre-mer) te corrigeren, indien van toepassing.
Hieronder staan een aantal voorbeeldenampcorrecties:
| Ingediend bestemmingsadres | Gecorrigeerd bestemmingsadres |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Frans nummer vertaald naar een DOM-TOM nummer) |
Daarnaast is het mogelijk om nationale telefoonnummers toe te staan voor een geselecteerde markt. Wanneer deze functie is ingeschakeld, moeten alle internationale nummers voor andere markten worden verzonden met een beginteken `+' om ze te onderscheiden van de geselecteerde markt.
Hieronder staan een aantal exampEr zijn minder correcties uitgevoerd bij het gebruik van Zweden (landcode 46) als standaardmarkt voor nationale nummers.
| Ingediend bestemmingsadres | Gecorrigeerd bestemmingsadres |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Ongeldig omdat het '+' teken ontbreekt |
Houd er rekening mee dat de gecorrigeerde MSISDN door LINK Mobility wordt gebruikt en in de leveringsrapporten wordt weergegeven.
Neem contact op met LINK Mobility support voor meer informatie.
8.2 Karaktervervanging
Tekenvervanging is een optionele functie die indien gewenst kan worden ingeschakeld via LINK Mobility-ondersteuning.
Deze functie vertaalt niet-GSM-alfabettekens in de gebruikersgegevens (sms-tekst) naar equivalente GSM-alfabettekens wanneer de DCS is ingesteld op “GSM” (17). Bijvoorbeeldample “Seqüência de teste em Português” zal worden vertaald naar “Seqüencia de teste em Portugues”.
9. Leveringsrapporten
De Service Provider kan, indien ingericht, SMS-berichtleveringsrapporten of leveringsmeldingen voor de verzonden MT-berichten opvragen. Deze rapporten worden geactiveerd in de Operator SMSC wanneer het MT-bericht wordt afgeleverd bij de beoogde Consumer of wordt verwijderd, bijvoorbeeld verlopen of om een of andere reden niet routeerbaar is.
Alleen de definitieve status van het SMS-bericht wordt gerapporteerd aan de Service Provider, d.w.z. afgeleverd of verwijderd. Er wordt slechts één rapport per MT-bericht gegenereerd. Bij de verwijderde status kan een redencode van toepassing zijn. Deze redencode specificeert de reden waarom het SMS-bericht niet is afgeleverd.
De rapporten worden via LINK Mobility verzonden naar de serviceprovider via het HTTP-protocol.
Om rapporten te ontvangen, moet de serviceprovider bijvoorbeeld het volgende implementeren:ample een Java Servlet of een ASP.NET pagina. Beide ontvangen HTTP GET of POST verzoeken.
Parameters
Het verzoek bevat de volgende parameters:
| Parameter | Type | M/O/Ik* | Standaardwaarde | Maximale lengte | Beschrijving |
| Bericht-ID | snaar | M | – | 22 | De bericht-ID van het MT-bericht waarmee dit rapport overeenkomt. |
| Bestemmingsadres | snaar | M | – | 40 | Het MSISDN van de consument, d.w.z. het bestemmingsadres van het oorspronkelijke MT-bericht. |
| Statuscode | geheel getal | M | 1 | De statuscode geeft de status van het MT-bericht aan. Toepasselijke statuscodes zijn: 0 – Afgeleverd 2 – Verwijderd (redencode is van toepassing) |
|
| TijdStamp | snaar | M | – | 20 | Tijdstip waarop het leveringsrapport door LINK Mobility is ontvangen. De tijdzone van de timestamp is CET of CEST (met zomertijd zoals gedefinieerd voor de EU). Formaat: jjjjMMdd UU:mm:ss. |
| Bediende | snaar | M | – | 100 | De naam van de Operator die wordt gebruikt bij het verzenden van het SMS-bericht of de accountnaam die wordt gebruikt bij het verzenden van het SMS-bericht. Een lijst met beschikbare operators wordt verstrekt door LINK Mobility-ondersteuning. |
| Redencode | geheel getal | O | – | 3 | De redencode geeft aan waarom het bericht de status verwijderd heeft gekregen. Toepasselijke redencodes zijn: 100 – Verlopen 101 – Afgewezen 102 – Formaatfout 103 – Andere fout 110 – Abonnee onbekend 111 – Abonnee uitgesloten 112 – Abonnee niet voorzien 113 – Abonnee niet beschikbaar 120 – SMSC-storing 121 – SMSC-congestie 122 – SMSC-roaming 130 – Handsetfout 131 – Geheugen van handset overschreden Gedrag kan variëren afhankelijk van Operator-integraties. |
| OperatorTijdStamp | snaar | O | – | 20 | Tijd die aangeeft wanneer het rapport is geactiveerd in de SMSC van de Operator (indien opgegeven door de Operator). De tijdzone van de timestamp is CET of CEST (met zomertijd zoals gedefinieerd voor de EU). Formaat: jjjjMMdd UU:mm:ss. |
| StatusTekst | snaar | O | – | 255 | Plaatsaanduiding voor aanvullende informatie van de Operator, bijvoorbeeld duidelijke tekstbeschrijving van de status/reden. Gedrag kan variëren met Operator-integraties. |
| Correlatie-ID | snaar | O | – | 100 | De correlatie-ID die is opgegeven in het SendRequest of SendTextRequest. |
| OperatorNetwerkCode | geheel getal | O | – | 6 | De mobiele netwerkcode (MCC + MNC) van de operator. |
* M = Verplicht, O = Optioneel, I = Genegeerd.
De Dienstverlener moet LINK Mobility voorzien van de doelstelling URL voor leveringsrapporten (optioneel inclusief referenties voor HTTP-basisauthenticatie). De serviceprovider kan kiezen welke voorkeurs-HTTP-methode hij wil gebruiken:
HTTP POST (aanbevolen)
HTTP-OPHALEN.
Example met behulp van HTTP GET (succesvol afgeleverd):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example met behulp van HTTP GET (niet geleverd, de operator heeft timest geleverdamp voor het evenement):
De parameters zijn URL gecodeerd.
Tekencodering:
De serviceprovider kan kiezen welke tekencodering hij wil gebruiken:
UTF-8 (aanbevolen)
ISO-8859-1.
9.1 Erkenning door de serviceprovider
De Service Provider moet elk leveringsrapport bevestigen. De bevestiging kan positief zijn, d.w.z. leveringsrapport succesvol ontvangen, of negatief, d.w.z. mislukt.
Let op: LINK Mobility heeft een leestime-out voor bevestigingen van 30 seconden voor leveringsrapporten. Een time-out activeert een leveringsherhaling (als herhaling is ingeschakeld) of een annulering van de levering (als herhaling is uitgeschakeld). Dit betekent dat de Service Provider-applicatie snelle responstijden moet garanderen, vooral tijdens hoge belasting.
Het is ten zeerste aan te raden om het leveringsrapport aan LINK Mobility te bevestigen voordat u het verwerkt.
De regel voor positieve en negatieve erkenning wordt als volgt beschreven:
Positieve bevestiging, ACK, afleveringsrapport afgeleverd:
HTTP 200-bereikresponscode in combinatie met de volgende XML-geformatteerde inhoud:
Negatieve ontvangstbevestiging, NAK, afleverrapport niet afgeleverd:
Elk ander antwoord dan een positieve bevestiging, bijvoorbeeldampEen negatieve bevestiging wordt bijvoorbeeld geactiveerd door een HTTP-foutcode of de volgende XML-inhoud:
De XML-inhoud kan worden gebruikt voor het besturen van het LINK Mobility-herhalingsmechanisme. Een NAK veroorzaakt een herhalingspoging, indien ingeschakeld. Voor serviceproviders die niet zijn geconfigureerd voor het herhalingsmechanisme, is de XML-inhoud optioneel.
Hieronder staat een HTTP POST-verzoek en -antwoord, bijvoorbeeldampvan een leveringsrapport dat aan een serviceprovider is geleverd:
HTTP-verzoek:
POST /context/app HTTP/1.1
Inhoudstype: application/x-www-form-urlgecodeerd;charset=utf-8
Host: server:poort
Inhoud-lengte: xx
MessageId=213123213&BestemmingsAdres=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-reactie:
HTTP/1.1 200 OK
Inhoudstype: tekst/plat
9.2 Opnieuw proberen
Het LINK Mobility-systeem kan herkansingen uitvoeren voor mislukte, d.w.z. niet-bevestigde, leveringsrapportleveringen. De serviceprovider kan het gewenste herkansingsgedrag kiezen:
Geen nieuwe poging (standaard) – het bericht wordt verwijderd als de verbindingspoging mislukt, als er een time-out optreedt bij het lezen of als er een HTTP-foutcode is.
Opnieuw proberen – het bericht wordt opnieuw verzonden bij elk type verbindingsprobleem, leestime-out of negatieve bevestiging.
Wanneer opnieuw proberen voor NAK is ingeschakeld, is het belangrijk om te begrijpen welke scenario's een nieuwe poging van LINK Mobility genereren en hoe de nieuwe poging werkt. Elke serviceprovider heeft zijn eigen wachtrij voor opnieuw proberen, waarin berichten worden geordend op basis van de berichttijdamp. Link Mobility probeert altijd oudere berichten eerst te bezorgen, ook al is de individuele volgorde van berichten die aan de serviceprovider worden bezorgd niet gegarandeerd. De belangrijkste reden dat berichten uit de retry-wachtrij worden verwijderd, is een van twee redenen: ofwel verloopt de bericht-TTL of (theoretisch) raakt de retry-wachtrij vol. De TTL is afhankelijk van de operator en het account, d.w.z. kan variëren afhankelijk van de operator en/of het type bericht, bijvoorbeeld premium SMS of standaardtarief SMS-bericht.
Een serviceprovider die de optie voor opnieuw proberen heeft ingeschakeld, moet de unieke ID van het MT-bericht controleren om er zeker van te zijn dat het bericht niet al is ontvangen.
Het is belangrijk dat de serviceprovider zich aan deze eenvoudige regels houdt wanneer er een fout optreedt tijdens de verwerking van een leveringsrapport als de reden voor de fout: Tijdelijk is, bijvoorbeeld omdat de database niet beschikbaar is, moet er een NAK worden geretourneerd. LINK Mobility zal het bericht opnieuw verzenden.
Permanent en een nieuwe poging veroorzaken waarschijnlijk hetzelfde soort probleem, er moet een ACK worden geretourneerd. Bijvoorbeeldample, wanneer het bericht niet correct kon worden geparseerd of een onverwachte runtime-fout veroorzaakte.
Als u dienovereenkomstig handelt, voorkomt u dat er blokkeringen of een lagere doorvoersnelheid optreden doordat een bezorgingsrapport herhaaldelijk opnieuw wordt verzonden.
10. Implementatietips
1. Het is mogelijk om uw web browser om verzoeken in te dienen bij de API. Dit maakt het heel eenvoudig om de services te verkennen en evalueren zonder enige ontwikkeltools.
2. Chrome of Firefox worden aanbevolen samen met een extensie zoals JSONView om mooi geformatteerde JSON weer te geven.
3. We hebben SoapUI gebruikt voor het testen van POST, basisverificatie en voor het inspecteren van de onbewerkte HTTP-aanvraag- en antwoordberichten.
4. De cURL tool is handig voor het indienen van POST-verzoeken met basisverificatie. Zie examphieronder.
curl NA \
-H “Inhoudstype: toepassing/x-www-formulier-urlgecodeerd” \
-H “Autorisatie: Basis am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “bestemmingsadres=46123456789&berichttekst=Hallo+Wereld%21”
_______________
Transformeren van gepersonaliseerde communicatie
Documenten / Bronnen
 |
LINK Mobiliteit Implementatiehandleiding REST API SMS [pdf] Gebruikershandleiding Implementatiehandleiding voor mobiliteit REST API SMS, Mobiliteit, Implementatiehandleiding REST API SMS, REST API SMS, API SMS, SMS |
