API de messagerie et de facturation des SMS

Introduction

Cette API décrit les appels de méthode pour l'ensemble des services de messagerie Fonix.

Toutes les API HTTP de Fonix sont organisées selon le modèle REST.

Connexion

Les appels vers Fonix doivent être effectués via HTTPS.

Les requêtes envoyées par Fonix à vos serveurs peuvent être effectuées via HTTPS ou HTTP. Lorsque vous utilisez HTTPS, le certificat de votre serveur doit être signé par une autorité de certification de confiance. Nous recommandons de chiffrer toutes les informations transmises sur le Web ; c'est pourquoi nous vous conseillons d'utiliser HTTPS.

Tous les appels vers et depuis Fonix s'effectuent via POST.

Authentification

L'authentification s'effectue en indiquant la clé API dans l'en-tête de votre requête. Le nom de l'en-tête est X-API-KEY. Notre équipe d'assistance vous fournira la clé dont vous aurez besoin.

Vous pouvez avoir plusieurs clés API actives simultanément pour différents services chez nous. Vos clés API donnent accès à de nombreux privilèges, veillez donc à les garder confidentielles !

Toutes les requêtes API doivent être effectuées via HTTPS. Les appels effectués via HTTP en clair échoueront. Vous devez vous authentifier pour chaque requête.

Toutes les requêtes HTTP à destination et en provenance de Fonix doivent être encodées selon le type de contenu par défaut : application/x-www-form-urlencoded.

Point de terminaison de l'API FONIX

#https://sonar.fonix.io/v2/
#NOTE: The underlying destination IP address for sonar.fonix.io changes over time.
#      Don't use fixed destination IPs with this domain.

#Example API Keys

# Test Key: test_BYZNk5YUBMLfowSOQTUuqq3t
# Live Key: live_WrxOqXQYwEPWVJDGgdfirZrk

#Example Request including the API key
curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333 
 -d BODY=Welcome%20Home

Référence au message

Nous prenons en charge les références fournies par le client pour les demandes qui nous sont adressées. Cela vous permet de nous transmettre jusqu’à 80 caractères de données dans un champ (REQUESTID), que nous vous renverrons dans le rapport de livraison correspondant. Vous trouverez plus de détails dans la section « Paramètres », sous « REQUESTID ».

Exemple incluant l'identifiant de requête (requestid)

curl -i https://sonar.fonix.io/v2/chargesms 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d ORIGINATOR=84988 
  -d NUMBERS=447111222333 
  -d BODY=This+MT+SMS+is+tagged 
  -d REQUESTID=F21B992Ex9257x936Ex3D2Fx7CDEB38F217C

Réussites et erreurs

Un appel d'API que vous nous envoyez dans cette version (V2) est réussi si et seulement si vous recevez un 200 OK Code de réponse HTTP renvoyé.

Toute autre valeur du code de réponse HTTP indique un échec et que la requête a été rejetée. Veuillez ne pas réessayer la même requête, car elle échouerait à nouveau si elle restait inchangée.

Si les paramètres de votre requête ne passent pas la validation, vous recevez un 400 Bad Request Erreur dans la réponse. Veuillez vérifier le code de résultat dans le JSON Répondez pour obtenir plus de détails sur la panne.

Si la clé utilisée dans votre requête est incorrecte ou non autorisée, vous recevrez un 401 Unauthorized erreur dans la réponse.

Si votre service dispose d'un quota maximal configuré pour les messages en masse, vous recevrez un failcode: MAX_QUOTA_REACHED une fois ce quota atteint.

Pour tous 400 BAD_REQUEST Les raisons de l'échec sont indiquées dans la réponse JSON :

RECHARGER PAR SMS

Demande

Cet appel de méthode envoie des SMS surtaxés vers un ou plusieurs numéros de téléphone, qui sont facturés sur le forfait mobile.

Les demandes de SMS payants ne peuvent en aucun cas être concaténées. Si le corps du message est trop long, nous rejetterons votre demande avec le message d'erreur suivant : "failcode": "TOO_MANY_CHARACTERS".

#CHARGE SMS request

curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d BODY=Welcome%20Home

Réponse

Les numéros de téléphone en double dans une même requête sont supprimés et, dans la réponse, nous vous indiquons le nombre de numéros de téléphone mobile uniques que nous avons trouvés ainsi que le codage utilisé (GSM/UCS-2). Nous vous communiquons désormais également le prix public du numéro court premium à partir duquel vous avez envoyé le message.

#CHARGE SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2",
        "encoding": "gsm",
        "price": 50
    }
}

#CHARGE SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "TOO_MANY_CHARACTERS"
    }
}

MO SMS

Demande

Les messages provenant d'un mobile (MO) sont envoyés à votre serveur web via une requête POST HTTPS. Si l'utilisateur a envoyé un message long qui arrive à notre passerelle sous la forme de plusieurs SMS MO, nous regroupons par défaut tous ces messages, puis nous vous envoyons l'intégralité du message long en une seule requête. Ce comportement peut être désactivé sur demande pour certains numéros courts dédiés.

# MO SMS HTTPS POST example (to your application)
#
# POST /path/mosms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BODY=This%20is%20a%20mobile%20originated%20test%20message&RECEIVETIME=20130202102030
# &GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&PRICE=15

Réponse

Le code de réponse HTTP que vous devez nous renvoyer devrait être : 200 OK

Si vous ne répondez pas avec un code 200, nous réessaierons d'envoyer le message MO à votre plateforme, ce qui pourrait vous amener à considérer ces nouvelles tentatives comme des doublons. Nous continuerons à essayer de vous envoyer le message pendant 24 heures au maximum.

MO BINAIRE

Demande

Pour les cas où les utilisateurs parviennent à envoyer des messages MO au format binaire, nous avons créé une requête MO BINARY dédiée. Son fonctionnement est similaire à celui de la requête MO SMS, mais pour vous faciliter la tâche, nous pouvons rediriger les requêtes MO BINARY vers un écouteur distinct de votre côté. Vous pourrez alors choisir de les décoder et de les traiter, ou simplement de les accepter et de les ignorer.

Les messages MO binaires sont souvent générés involontairement par des téléphones issus du marché parallèle, qui n'envoient pas les SMS selon la procédure standard.

#MO BINARY HTTPS POST example (to your application)
#
# POST /path/mobinary HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
# F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
# &BINHEADER=050415810000&RECEIVETIME=20130202102030&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Réponse

Le code de réponse HTTP que vous devez nous renvoyer devrait être : 200 OK

Si vous ne répondez pas avec un code 200 OK, nous réessaierons d'envoyer le message MO à votre plateforme, ce qui pourrait vous amener à considérer ces nouvelles tentatives comme des doublons. Nous continuerons à essayer de vous envoyer le message pendant 24 heures au maximum.

DR SMS

Demande

Les rapports de livraison (DR) relatifs aux messages MT précédemment envoyés sont transmis à votre serveur web via une requête POST HTTPS. Les DR indiquent soit que la livraison a abouti, soit qu'elle a échoué. En cas d'échec de la livraison, les détails concernant la raison de l'échec sont fournis dans les champs STATUSCODE et STATUSTEXT.

Les rapports de livraison permettent de vérifier si le destinataire d'un SMS CHARGE a bien été facturé. Remarque : tous les SMS CHARGE remis impliquent systématiquement que l'utilisateur a été facturé. Cependant, dans certains cas, les messages non remis sont tout de même facturés.

Nous incluons désormais également le PRICE paramètre contenant le prix public du shortcode premium à partir duquel vous avez envoyé le message MT.

Lorsque nous transmettons votre demande par SMS à l'opérateur mobile, il peut arriver, dans certains cas, que nous ne recevions pas d'accusé de réception de sa part. Notre politique est la suivante : pas de réessayer d'envoyer la demande dans ces cas-là, car il se peut que le message ait bien été transmis au téléphone du destinataire. À la place, nous vous envoyons un rapport d'échec de livraison indiquant que STATUSCODE=OPERATOR_TIMEOUT.

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=o2-uk&MONUMBER=447111222333&DESTINATION=84988
# &STATUSCODE=DELIVERED&STATUSTEXT=Delivered&STATUSTIME=20130202102030
# &PRICE=50&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Réponse

Le code de réponse HTTP que vous devez nous renvoyer devrait être : 200 OK

Si vous ne renvoyez pas un code d'état 200, nous continuerons à tenter de transmettre le DR à votre plateforme pendant 24 heures au maximum.

Paramètres

Les paramètres suivants sont utilisés dans l'ensemble de l'API :

• CORPS DU MESSAGE: Le corps du message. Il ne peut pas être vide pour les fonctions « ENVOYER UN SMS » et « FACTURER UN SMS ».
• CHIFFRES: Contient les numéros de téléphone mobile de destination auxquels le SMS MT sera envoyé. Le préfixe 00 (tel qu'utilisé dans la version 1) n'est plus obligatoire ; toutefois, tous les numéros doivent inclure l'indicatif du pays, par exemple : 44 pour le Royaume-Uni. Le code de l'opérateur mobile peut être précédé d'un préfixe, c'est-à-dire NUMBERS=eeora-uk.447123456789Pour envoyer le même SMS MT à plusieurs numéros, vous pouvez les séparer par des virgules : NUMBERS=447111122222,447333344444
  Le nombre maximal de numéros de téléphone mobile autorisé par lot est de 100.
• EXPÉDITEUR: Numéro ou chaîne de caractères de l'expéditeur du message. Veuillez noter que le service CHARGE SMS n'autorise l'envoi de messages qu'à partir d'expéditeurs numériques (codes courts) préalablement enregistrés auprès de nos services.
• TYPE_D'AUTEUR: Paramètre facultatif utilisé dans ENVOYER UN SMS pour préciser le type d'émetteur. Les valeurs autorisées sont les suivantes :
  • alpha (par défaut) jusqu'à 11 caractères alphanumériques
  • msisdn un numéro de téléphone mobile complet

#A sample message sent from 447987654321:
 curl -i https://sonar.fonix.io/v2/sendsms 
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
  -d ORIGINATOR=447987654321 
  -d ORIGINATOR_TYPE=msisdn  
  -d NUMBERS=447111222333 
  -d BODY=Welcome%20Home

• REQUESTID: champ facultatif vous permettant de stocker une chaîne unique de 80 caractères maximum (0-9, a-z, A-Z) associée à votre requête. Si vous utilisez ce champ, vous devez vous assurer que la valeur est unique en permanence pour votre service. Si vous nous envoyez une nouvelle requête avec un REQUESTID déjà utilisé au cours des sept derniers jours, nous ne la traiterons pas à nouveau, mais nous vous répondrons en réutilisant les informations fournies dans notre réponse précédente. Si vous nous envoyez une requête avec un REQUESTID déjà utilisé après sept jours, le message risque d’être renvoyé ; c’est pourquoi nous vous recommandons de ne pas réessayer d’envoyer des requêtes pendant plus de sept jours. Le REQUESTID vous sera également renvoyé dans le DR correspondant.
• PRIX: Prix public, en pence, d'un message « premium » de type MO ou MT.
• TIMETOLIVE: Permet de définir, si vous le souhaitez, la durée de validité du SMS MT en minutes. Si, au terme de cette période, le message n’a toujours pas pu être remis malgré les tentatives répétées, un code d’erreur « Delivery Failed DR » vous sera renvoyé. Valeur minimale : 10 minutes, valeur maximale : 4 340 minutes, valeur par défaut : 4 340 minutes.
• NORETRY: Facultatif, valeurs YES/NO, valeur par défaut NO. Notre passerelle gère la réémission des SMS premium dans les cas où le réseau mobile rejette le message en raison d'un solde insuffisant du destinataire. NORETRY=YES désactive la réémission ultérieure (jusqu'à la fin de la durée TIMETOLIVE).
• BINHEADER: À utiliser uniquement avec l'envoi de SMS binaires. N'incluez pas l'octet de longueur en début de message. Nous l'ajouterons automatiquement.
• BINBODY: Utilisé uniquement avec la commande « SEND BINARY SMS ».
• PUSHTITLE: Utilisé uniquement avec la commande SEND WAP PUSH. Texte affiché par le destinataire de la notification WAP.
• PUSHLINK: Utilisé uniquement avec la commande SEND WAP PUSH. URL de destination de la notification WAP.
• CODAGE: Facultatif, valeurs possibles : gsm/ucs2 ; la valeur par défaut dépend de BODY jeu de caractères.
  Vous permet de préciser l'encodage à utiliser lors de l'envoi du message. Si la valeur est définie sur gsm, les caractères non GSM seront remplacés par un point d'interrogation.
• DUMMY: Facultatif, valeurs YES/NO, valeur par défaut NO.
  Permet d'exécuter des tests d'intégration ou de vérifier le nombre d'éléments qui seraient générés à partir de votre requête. Pour plus d'informations sur la manière de forcer les paramètres DR pour les requêtes DUMMY, reportez-vous à l'ANNEXE A.

Paramètres entrants (MO et DR)

Les paramètres d'information suivants apparaissent uniquement dans les SMS MO, MO STOP et DR:

• IFVERSION: Version de l'API actuellement utilisée.
• DESTINATION: Le numéro court ou le numéro complet auquel le message a été envoyé.
• MONUMBER: Le numéro de portable de l'utilisateur qui vous a envoyé un message MO ou DR. Le format est le suivant : MONUMBER=447111122222.
• OPÉRATEUR: Code de l'opérateur mobile de l'utilisateur qui vous a envoyé un message MO ou DR.
• GUID: identifiant unique que nous avons attribué à ce message.
• RECEIVETIME: Date et heure (en UTC) auxquelles nous avons reçu le MO ou le DR de la part de l'opérateur mobile.
• DURÉE: Durée, exprimée en secondes, nécessaire à la remise du message ou durée nécessaire pour constater que la remise a définitivement échoué.
• NOMBRE DE TENTATIVES: Ce paramètre s'affiche lorsqu'une requête fait l'objet d'une nouvelle tentative d'envoi. Sa valeur augmente à chaque nouvelle tentative. Lors de la première tentative, sa valeur est RETRYCOUNT=0.
• CODE D'ÉTAT: Code utilisé dans le DR pour indiquer si la demande de transfert de message (MT) que vous avez envoyée a abouti ou a échoué .
• STATUSTEXT: Une description fournissant des informations complémentaires sur le code d'état.
• STATUSTIME: horodatage correspondant à la date de création du plan de reprise après sinistre (DR)

Tous les DR contiennent un code d'état. Les valeurs suivantes sont définies à cet effet :

• CHARGESTATUS: indicateur simple de type « vrai/faux » figurant dans les rapports de livraison (DR) des SMS payants, indiquant si le destinataire a bien été facturé ou non. Utile dans certaines circonstances : sur le réseau Three-UK, il peut arriver que la livraison du message ait échoué, mais que le consommateur ait néanmoins été facturé.
• REQUESTID: Si vous avez envoyé votre SMS MT avec un identifiant de demande unique, ce champ DR le contiendra en retour afin de vous aider à identifier le message remis.
• PARTIE: Pour le DR, cela permet d'identifier quelle partie de votre SMS MT concaténé (long) a été délivrée ou a échoué. Pour un MO concaténé (long) dont le comportement par défaut est désactivé, cela permet d'identifier de quelle partie du MO il s'agit.
• TOTAL_PARTS: Pour DR, ce paramètre indique le nombre de parties que vous avez initialement envoyées dans votre SMS MT concaténé (long). Pour un MO concaténé (long) dont le comportement par défaut est désactivé, ce paramètre indique le nombre total de parties.
• CSMS_REF: Pour un MO concaténé (long) dont le comportement par défaut est désactivé, cet indicateur fournit un identifiant court (valeur comprise entre 0 et 65 535) qui est identique pour toutes les parties. Associé à l’OADC, il sert d’indicateur de quasi-unicité entre plusieurs messages MO concaténés. Dans la version 2 de cette API, nous regrouperons toutes les parties et ne vous enverrons le message MO complet (long) qu'une fois que nous aurons reçu toutes les parties.
• AV: Vérification de l'âge adulte. Si vous recevez des messages MO sur des numéros courts réservés aux adultes (69xxx, 79xxx ou 89xxx), nous pouvons vous indiquer si l'utilisateur est autorisé ou non à recevoir des services pour adultes à l'aide des valeurs suivantes : AV=verified, AV=not_verified ou AV=unknown.Les services pour adultes ne doivent pas être fournis aux utilisateurs pour lesquels le paramètre est défini sur AV=not_verified, car dans ces cas-là, l'opérateur mobile nous a expressément informés que cet utilisateur n'est pas autorisé à recevoir de tels services.

Codes des opérateurs mobiles

La liste suivante des codes d'opérateurs mobiles est utilisée dans cette version de l'API (V2) ainsi que dans toutes les versions futures :

unknown Cela se produit lorsque le message MO nous a été transmis par un autre opérateur ou lorsqu'un message groupé a été envoyé à un utilisateur dont nous n'avons pas pu identifier le réseau.

Types de personnages

Les types de données suivants sont utilisés dans l'ensemble de l'API :

• Chiffres : caractères 0 à 9
• Alphanumérique : tout caractère UTF-8
• Hexadécimal : les caractères 0 à 9, a à f et A à F
• Numéro de portable : chiffres de 0 à 9, le premier caractère peut être « + »
• Heure : horodatage au format AAAAMMJJHHMMSS
• Version : Version MNNBBB
• GUID : caractères 0 à 9, a à f, A à F et « - »
• REQUIS : Caractères 0 à 9 et a à z et A à Z
• Les caractères d'échappement peuvent être envoyés à l'aide de UTF-8 notation en octets : ? = %3F Vous trouverez ci-dessous un tableau répertoriant certains des caractères les plus couramment échappés :

# Examples
#
# ORIGINATOR=84588
#
# BODY=Test+message
#
# BODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
#      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
#
# NUMBERS=447111222333
#
# RECEIVETIME=20130202102030
#
# IFVERSION=201001
#
# GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

VÉRIFICATION DE L'ÂGE

Introduction

Fonix permet aux clients de vérifier le statut de vérification de l'âge associé à un MSISDN. Cette requête sert à vérifier qu'un client est autorisé à accéder à des contenus soumis à une restriction d'âge.

Requête asynchrone

Nous accusons réception de votre demande, puis nous vous envoyons le résultat dans un RAPPORT ANTIVIRUS distinct.

• Le code de l'opérateur mobile doit être indiqué en préfixe du MSISDN.
• Le paramètre NETWORKRETRY est obligatoire. Dans la plupart des cas, veuillez le définir comme suit : NETWORKRETRY=NO
• Le paramètre NUMBERS ne peut contenir qu'un seul MSISDN.

curl -i  https://sonar.fonix.io/v2/adultverify 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.447932111222 
-d NETWORKRETRY=NO

Réponse asynchrone

Dans notre réponse, nous confirmons (ACK) ou refusons (NACK) votre demande de vérification de l'âge (Adult Verify).
Les paramètres suivants sont renvoyés :

Remarque :

• txguid : le GUID de la requête d'origine
• nombre : le nombre de chiffres transmis dans la requête d'origine

Nack :

• paramètre : quel paramètre n'a pas passé la validation
• failcode : pourquoi la validation a échoué

# ACK:
 {
   "success": {
       "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
       "numbers": "1"
   }
 }

# NACK:
 {
   "failure": {
       "parameter": "parameter name",
       "failcode": "FAILCODE"
   }
 }

Demande synchrone

La réponse à votre requête inclura l'état de l'AV.
Si, au bout de 30 secondes, nous n'avons pas reçu de réponse de l'opérateur, nous envoyons une réponse « en attente » à votre appel.
Si vous souhaitez récupérer les états de l'AV dans ces cas-là, nous pouvons configurer votre service de manière à ce que, pour chaque requête, nous envoyions à la fois une réponse synchrone et une réponse asynchrone.

• Le code de l'opérateur mobile doit être indiqué en préfixe du MSISDN.
• Le paramètre NETWORKRETRY est obligatoire. Dans la plupart des cas, veuillez le définir comme suit : NETWORKRETRY=NO
• Le paramètre NUMBERS ne peut contenir qu'un seul MSISDN.

curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.447932111222 
-d NETWORKRETRY=NO

Réponse synchrone

Dans notre réponse, nous confirmons (ACK) ou refusons (NACK) votre demande de vérification de l'âge (Adult Verify).
Les paramètres suivants sont renvoyés :

Ack (peut être « vérifié », « non vérifié », « inconnu » ou « en attente ») :

• ifversion : version de l'API
• opérateur : code de l'opérateur mobile auprès duquel nous avons reçu les informations d'état
• guid : le GUID de la requête d'origine

Nack :

• paramètre : quel paramètre n'a pas passé la validation
• failcode : pourquoi la validation a échoué

# ACK:
 {"verified":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"not_verified":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"unknown":{
       "ifversion":"201001",
       "operator":"o2-uk",
      "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

 {"pending":{
       "ifversion":"201001",
       "operator":"o2-uk",
       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
   }
 }

# NACK:
 {
   "failure": {
       "parameter": "parameter name",
       "failcode": "FAILCODE"
   }
 }

RAPPORT AUDIOVISUEL

Demande

Les rapports AV relatifs aux demandes « Adult Verify » précédemment soumises sont envoyés via une requête POST HTTPS à votre serveur web. Ils indiquent si les numéros que vous avez fournis ont été enregistrés auprès de l'opérateur mobile comme ayant fait l'objet d'une vérification d'âge ou non.

# AV REPORT HTTPS POST example (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# eetmo-uk.447932111222
#
# IFVERSION=201001&OPERATOR=eetmo-uk&MONUMBER=447932111222&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&AV=VERIFIED

Réponse

Le code de réponse HTTP que vous devez nous renvoyer devrait être : 200 OK

Si vous ne répondez pas par un code 200 OK, nous réessaierons d'envoyer le rapport de transaction à votre plateforme pendant une période pouvant aller jusqu'à 24 heures.

SENDSMS

Demande

Cet appel de méthode permet d'envoyer des SMS à un ou plusieurs numéros de téléphone sans débiter le crédit du forfait mobile.

En règle générale, le corps d'un message peut contenir jusqu'à 160 caractères. Si votre message est plus long, nous le diviserons et l'enverrons en plusieurs SMS sous forme de message concaténé.

Certains caractères spéciaux occupent en effet deux fois plus d'espace que d'autres (voir GSM (pour plus d’informations). Si le corps de votre message contient des caractères non GSM, nous encoderons l’intégralité du message en UCS-2 avant de le transmettre à l’opérateur, à moins que vous n’imposiez l’utilisation de l’encodage dans le CODAGE paramètre. Si vous souhaitez vérifier si le corps de votre message tient dans un seul SMS, vous pouvez envoyer une DUMMY Envoyez d'abord la requête, puis guettez la réponse contenant le smsparts paramètre.

curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:live_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333 
 -d BODY=Welcome%20Home
 -d DUMMY=yes

Réponse

Le corps de la réponse est structuré selon le format JSON.

Si votre demande a été acceptée, vous recevrez prochainement une réponse de confirmation de notre part, qui contiendra notre référence GUID. "txguid" Conformément à votre demande, combien de numéros de téléphone portable distincts "numbers" nous avons constaté (les numéros de téléphone en double dans une même demande sont supprimés), combien "smsparts" votre message a été divisé en plusieurs parties et laquelle "encoding" nous avons utilisé (GSM/UCS2).

Si votre requête a échoué en raison d'un paramètre manquant ou incorrect, nous vous indiquons lequel "parameter" j'ai rencontré ce problème et le "failcode" de l'erreur.
Pour plus d'informations sur les erreurs éventuelles, veuillez consulter le Section « Erreurs ».

#SEND SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1",
        "smsparts": "1",
        "encoding": "gsm"
    }
}

#SEND SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

ENVOYER UN SMS BINAIRE

Demande

Pour envoyer un message binaire, qu'il soit en une ou plusieurs parties, vers un téléphone portable, celui-ci doit être encodé d'une manière spécifique. C'est ce que nous faisons pour vous grâce à cet appel. En fonction de la longueur des données, le message binaire sera fractionné et transmis via plusieurs SMS. Les SMS binaires ne sont pas facturés sur le forfait mobile.

#SEND BINARY SMS request

curl -i https://sonar.fonix.io/v2/sendbinsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204 
      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B615905E1 
      95B081180800991C6106DA62042028C26C49B6186289B0E195B0811808009928C26C4910A2 
 -d BINHEADER=050415810000

Réponse

Les numéros de téléphone en double dans une même requête sont éliminés, et dans la réponse, nous vous indiquons le nombre de numéros de téléphone mobile uniques que nous avons trouvés.

Nous vous indiquons également en combien de SMS votre message a été divisé.

#SEND BINARY SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2",
        "smsparts" "2"
    }
}

#SEND BINARY SMS response (failure)
{
    "failure": {
        "parameter": "originator",
        "failcode": "INVALID_CHARACTERS"
    }
}

ENVOYER UNE NOTIFICATION WAP PUSH

Demande

Pour envoyer un message WAP Push vers un téléphone portable, celui-ci doit être encodé d'une manière spécifique. C'est ce que nous faisons pour vous grâce à cet appel. En fonction de la longueur des informations contenues dans le lien, le message WAP Push sera fractionné et transmis via plusieurs SMS. Les messages WAP Push ne sont pas facturés sur le forfait mobile.

#SEND WAP PUSH request

curl -i https://sonar.fonix.io/v2/sendwappush 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=447111222333,447111222444 
 -d PUSHTITLE=Welcome%20Home 
 -d PUSHLINK=http://www.google.com

Réponse

Les numéros de téléphone en double dans une même requête sont éliminés, et dans la réponse, nous vous indiquons le nombre de numéros de téléphone mobile uniques que nous avons trouvés.

Nous vous indiquons également en combien de SMS votre message a été divisé.

#SEND WAP PUSH response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1",
        "smsparts" "1"
    }
}

#SEND WAP PUSH response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

Exemples de messages

Exemple de facture MT

Un SMS facturé envoyé à deux numéros O2, le 447111222333 et le 447111222444, dont le corps du message était « Welcome Home » et qui provenait du numéro 84988.

curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d NUMBERS=447111222333,447111222444 
 -d BODY=Welcome%20Home 
 -d ORIGINATOR=84988

Exemple de MT binaire

Un SMS gratuit envoyé au 447111222333, contenant du contenu binaire et provenant de HELLO.

curl -i https://sonar.fonix.io/v2/binarysms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d REQUESTTYPE=5 
 -d NUMBERS=447111222333 
 -d BINHEADER=050415810000 
 -d BINBODY=024A3A5905E195[...]361B6182000 
 -d ORIGINATOR=HELLO

Exemple de traduction automatique concaténée

Envoyez gratuitement un SMS au 447111222333 contenant un poème de 242 caractères provenant de POETRY. Le message sera transmis sous la forme de deux SMS MT distincts, puis réassemblé sur le téléphone.

curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d REQUESTTYPE=19 
 -d NUMBERS=447111222333 
 -d BODY=Why+were+you+born+when+the+snow+was+falling%3F+ 
 You+should+have+come+to+the+cuckoo%27s+calling+Or+when+ 
 grapes+are+green+in+the+cluster%2C+Or%2C+at+least%2C+ 
 when+lithe+swallows+muster+For+their+far+off+flying+ 
 From+summer+dying.+%28Christina+Rossetti%2C+1865%29 
 -d ORIGINATOR=POETRY

RECHERCHE D'OPÉRATEUR

Demande

L'appel de recherche HLR/opérateur fournit le réseau et le pays correspondant à un MSISDN donné. Cet appel dispose d'une couverture internationale et prend en charge les MSISDN de tous les principaux réseaux mobiles dans tous les pays.

Lorsque vous saisissez un MSISDN, cette fonction renvoie le pays et l'opérateur associés au MSISDN indiqué.

L'appel de méthode est synchrone, c'est-à-dire que nous vous renvoyons directement les informations demandées dans la réponse HTTP.

# Example API Request including the API key
  curl -i  http://sonar.fonix.io/v2/operator_lookup?NUMBER=447932111222 
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

Réponse

La réponse HTTP fournit les informations suivantes à l'utilisateur :

• mcc : indicatif national de téléphonie mobile
• mnc : code de réseau mobile
• opérateur : L'opérateur de téléphonie mobile

   {
   "success":
       {"mcc":"234",
         "mnc":"15",
         "operator":"voda-uk"}
   }

Paramètres

Les paramètres suivants sont utilisés dans l'ensemble de l'API :

• CHIFFRES: Contient un seul et unique numéro de téléphone mobile pour lequel les informations sont demandées. Le code de l'opérateur mobile doit être ajouté en préfixe au VÉRIFICATION DE L'ÂGE appel, c'est-à-dire NUMBERS=eeora-uk.447123456789
• NUMÉRO CHIFFRE: Contient un seul et unique numéro de téléphone mobile chiffré. Il s'agit d'une longue valeur de hachage que nous pouvons vous transmettre via Fpay, lorsque le numéro de téléphone mobile doit rester anonyme mais que vous avez tout de même besoin d'informations concernant le statut de vérification de la majorité. Remarque : Il faut utiliser la valeur de hachage dans son intégralité, y compris %2F et %3D les caractères contenus dans la chaîne.
• IFVERSION: Version de l'API actuellement utilisée.
• AV: Statut de vérification de la majorité. Il peut s'agir de « VERIFIED », « NOT_VERIFIED » ou « UNKNOWN ».
• GUID: identifiant unique que nous avons attribué à cette requête.
• NETWORKRETRY: ce paramètre contrôle le comportement de la vérification de basculement. S'il est défini sur YES, nous vérifions l'état antivirus non seulement sur le réseau spécifié, mais également sur d'autres réseaux. Cela peut entraîner des résultats inattendus, car Vodafone pourrait marquer comme « VERIFIED » un numéro de mobile transféré vers un autre réseau, alors qu'en réalité il n'est pas vérifié. Par conséquent, veuillez spécifier NETWORKRETRY=NO pour toutes les requêtes.

# Example ENCRYPTEDMSISDN:
#   pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

API KYC

Introduction

L'API KYC de Fonix permet aux commerçants de vérifier les données personnelles du client associées à un MSISDN.

# REQUEST:
curl -i https://kycsolo.fonix.io/v2/kyc 
-H X-API-KEY:SERVICE_API_KEY  
-d NUMBER=447400000000 
-d NAME=TestName 
-d SURNAME=TestSurname 
-d HOUSE_NUMBER=1 
-d POSTCODE=TESTPOSTCODE 
-d DOB=13-01-1900
-d REQUESTID=requestid1 
-d DUMMY=YES

# RESPONSE
{
   "completed":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully checked",
       "guid":"r-1-requestid1",
       "requestid":"requestid1",
       "status_time":"20210608140636",
       "first_name_match":true,
       "last_name_match":true,
       "full_name_match":true,
       "postcode_match":true,
       "house_match":true,
       "full_address_match":true,
       "birthday_match":true,
       "is_stolen":false,
       "contract_type":"PAYG"
   }
 }

Détails de l'appel

Paramètres de requête

Tous les paramètres marqués d'un * sont obligatoires.

• REQUESTID *: chaîne de caractères ne dépassant pas 50 caractères (0-9, a-z, A-Z) utilisée pour identifier une requête ; elle doit être unique en permanence pour votre service. Pendant 7 jours, toute requête ultérieure comportant le même REQUESTID et les mêmes informations client ne sera pas transmise aux réseaux ; à la place, une réponse contenant le résultat de la première requête sera renvoyée.

• NUMÉRO *: Le numéro de portable du client au format international, c'est-à-dire : NUMBER=447400000000 pour le Royaume-Uni.
• NOM *: Prénom (varchar 255).
• NOM DE FAMILLE *: Nom de famille (varchar 255).
• CODE POSTAL *: Code postal de l'adresse de facturation du client (varchar 255).
• Date de naissance *: Date de naissance au format JJ-MM-AAAA.
• HOUSE_NUMBER: Numéro de maison (varchar 255).
• HOUSE_NAME: Nom de la maison (varchar 255).
• DUMMY: Facultatif, valeurs YES/NO, valeur par défaut NO.

Réponse

La réponse KYC est au format JSON.
Si l'un des paramètres ne passe pas la validation, une réponse d'échec indiquant le paramètre concerné et un code d'erreur est renvoyée.
c'est-à-dire {"failure":{"parameter":"DOB","failcode":"INVALID"}}

Si le nombre de requêtes envoyées simultanément dépasse la valeur MAX CONCURRENT REQUESTS, une réponse d'échec avec le code d'état WINDOW_EXCEEDED est renvoyée.
c'est-à-dire {"failure":{"ifversion":"201001","statuscode":"WINDOW_EXCEEDED","statustext":"Too many requests made to the server in parallel"}}

Si le traitement de la requête prend plus de 70 secondes, une réponse en attente est renvoyée.
c'est-à-dire {"pending":{"ifversion":"201001","statuscode":"PENDING","statustext":"The request is still processing","guid":"r-1-test","requestid":"test"}}

Pour pouvoir accéder à l'API, chaque demande doit être approuvée par les opérateurs de téléphonie mobile.
L'API ne sera accessible qu'aux services approuvés. Chaque service doit être autorisé à accéder à l'API ; si l'accès à l'API n'a pas été configuré pour ce service, vous obtiendrez la réponse suivante :
{"failure":{"parameter":"METHOD","failcode":"NOT_AUTHORIZED"}}
Veuillez nous contacter pour demander l'accès à l'API KYC.

Chaque fois qu'une requête est traitée et qu'un statut définitif est attribué, une réponse indiquant que l'opération est terminée est renvoyée (code d'état HTTP 200).

# COMPLETED RESPONSE EXAMPLE

 {
   "completed":{
       "ifversion":"201001",
       "statuscode":"OK",
       "statustext":"Successfully checked",
       "guid":"r-1-requestid",
       "requestid":"requestid",
       "status_time":"202106081801213",
       "first_name_match":true,
       "last_name_match":false,
       "full_name_match":false,
       "postcode_match":true,
       "house_match":"unknown",
       "full_address_match":"unknown",
       "birthday_match":true,
       "is_stolen":false,
       "contract_type":"PAYM"
   }
 }

Paramètres de réponse

Tous les champs se terminant par _match et is_stolen peuvent prendre trois valeurs possibles : true, false ou « unknown ».
Ils seront définis sur « unknown » si l’opérateur de réseau mobile (MNO) ne dispose pas des informations nécessaires pour effectuer la vérification, sur true ou false si les informations détenues par l’opérateur correspondent ou non à celles transmises dans la requête.

• ifversion: version de l'API Fonix.
• code d'état: code utilisé pour indiquer l'état de la requête.
• statustext: Une brève description associée au code d'état.
• guid: identifiant unique attribué par Fonix à partir du REQUESTID
• requestid: L'identifiant REQUESTID envoyé dans la requête
• status_time: Date et heure auxquelles la requête a atteint son statut définitif (AAAAMMJJHHMMSS).
• first_name_match: Valeurs possibles (true|false|« inconnu »).
• last_name_match: Valeurs possibles (true|false|« unknown »).
• full_name_match: Valeurs possibles (true|false|« unknown »).
• postcode_match: Valeurs possibles (true|false|« inconnu »).
• house_match: Valeurs possibles (true|false|« unknown »).
• full_address_match: Valeurs possibles (true|false|« inconnu »).
• birthday_match: Valeurs possibles (true|false|« unknown »).
• is_stolen: Valeurs possibles (true|false|« unknown »).
• type_de_contrat: Valeurs possibles (« PAYG » | « PAYM » | « Business » | « inconnu »).

Erreurs de validation des paramètres

Lorsqu'un ou plusieurs paramètres ne satisfont pas aux critères de validation, l'API KYC de Fonix renvoie une réponse d'échec au format {"failure":{"parameter":"DOB","failcode":"INVALID"}}.
Le parameter Ce champ indiquera le nom du paramètre transmis qui n'a pas passé la validation.
Le failcode Ce champ sera renseigné avec l'un des codes suivants :

Codes d'état

API SMPP

Introduction

L'API SMPP de Fonix est étroitement conforme à la spécification du protocole SMPP (Short Message Peer to Peer Protocol) version 3.4. Nous n'y avons apporté que quelques modifications afin d'enrichir les informations que nous échangeons avec votre plateforme.

Connexion

Dans le protocole SMPP, les connexions sont établies par votre client vers notre serveur, tant pour l'envoi de messages MT que pour la réception de messages MO et DR.

Le protocole SMPP est acheminé via TCP et Fonix utilise les ports suivants pour se connecter :

• 5443 pour les connexions cryptées SSL. Nous fournissons un certificat dûment signé sur cette connexion afin d'authentifier l'identité de notre serveur SMPP. Nous recommandons vivement à tous nos clients SMPP d'utiliser des connexions SSL pour sécuriser vos SMS pendant leur transmission.
• 5 000 pour les connexions non chiffrées

Nous prenons en charge les liaisons de type ÉMETTEUR, RÉCEPTEUR et ÉMETTEUR-RÉCEPTEUR. Nous pouvons vous proposer plusieurs sessions (liaisons) pour votre connexion.

Authentification

Authentication in SMPP is made through custom credentials which we provide to you separately.

Gestion des versions

We only support SMPP V3.4 (Document Version:- 12-Oct-1999 Issue 1.2)

Flow Control

The SMPP protocol is very efficient in data transport and also supports asynchronous transport where multiple requests can be issued without waiting. Requests are acknowledged in a skew order by the other end. The number of unacknowledged requests is called a window and the maximum size set by the sending party is called window size.

We support a receiving window size for MT messages of 100. Any unacknowledged requests above this level will be rejected with the RTHROTTLED error code.

Our default sending window size for MO and DR messages is 30, but can be configured to suit your needs.

Custom TLV parameters

To transport additional information not covered in the standard scope of SMPP we utilise custom defined Tag Length Value (TLV) parameters. Currently the following parameters are defined

NOTE: The message GUID assigned by Fonix is transported in different tags to you for different message types:

• sonar_guid (TLV 0x1620) for MO messages sent to you
• message_id (defined in SMPP V3.4) for ACKs to your MT requests
• receipted_message_id (defined in (SMPP V3.4) for DR messages sent to you

NOTE: The TLV paramters should be formated as c-var-octet strings and be null terminated. For example the TLV to tell us that your MT message should go to Vodafone would be 16000008766f64612d756b00.

NOTE: Please don’t send the sonar_guid, av ou price tags to us in your MT request. We just ignore those values in message processing.

# Example c-var-octet strings for the operator TLV field:
#   1600000974687265652d756b00   = three-uk
#   160000096565746d6f2d756b00   = eetmo-uk
#   1600000965656f72612d756b00   = eeora-uk
#   16000008766f64612d756b00     = voda-uk 
#   160000066f322d756b00         = o2-uk 
#   1600000a76697267696e2d756b00 = virgin-uk

Sending Premium and Bulk SMS

Our API accepts both bulk and premium SMS through the same connection. MT Premium and MT Bulk are distinguished through the TON and NPI properties of the originator. Setting the right TON and NPI is very important to avoid unintentionally billing or not billing a user.

Here are the settings to use:

To send a premium message, the originator can only ever be a shortcode. To send a bulk message, the originator can be any string of alphanumeric characters or a fully formatted phone number.

# Extract for premium SMS:
#   {source_addr,"84988"}
#   {source_addr_ton,3},
#   {source_addr_npi,9},

# Extract for bulk SMS:
#   {source_addr,"Fonix"}
#   {source_addr_ton,5},
#   {source_addr_npi,0},

# Extract for bulk SMS from MSISDN:
#   {source_addr,"447987654321"}
#   {source_addr_ton,1},
#   {source_addr_npi,1},

Sending parameters (MT)

Here is some guidance on the specific use of SMPP parameters to compose your MT messages:

• destination_addr: Contains the MSISDN destination mobile number to which the MT SMS will be sent in the format 447111222333.
• source_addr: Contains the originator from which the MT SMS will appear.
• short_message: The body text of the message must be encoded in either UTF-8, UTF-16 or Binary depending on the value specified in data_coding.
• data_coding: The type of character encoding used in short_message:
  • {data_coding,0}: UTF-8
  • {data_coding,8}: UTF-16
  • {data_coding,4}: Binary
• validity_period: Optionally sets the validity period of the MT SMS message in minutes. Once the message can no longer be delivered through retries inside this period, then a ‘Delivery Failed DR’ will be returned to you. Minimum value: 10 minutes, Maximum value: 4320 minutes, Default value: 4320 minutes.
• esm_class: The esm_class is typically 0, but can be set to 0x40 to indicate a user data header in the message
• sm_default_msg_id: should be set to 0
• replace_if_present_flag: should be set to 0
• registered_delivery: should be set to 1
• priority_flag: should be set to 0
• protocol_id: should be set to 0
• dest_addr_npi: should be set to 1
• dest_addr_ton: should be set to 1
• schedule_delivery_time: should be empty
• service_type: should be empty

#SUBMIT_SM MT message example:
#  [{short_message,"hello world"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,1},
#  {validity_period,""},
#  {schedule_delivery_time,""},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"447111222333"},
#  {dest_addr_npi,1},
#  {dest_addr_ton,1},
#  {source_addr,"12345"},
#  {source_addr_npi,0},
#  {source_addr_ton,5},
#  {service_type,""}]

Paramètres entrants (MO et DR)

The short_message parameter of MO messages is encoded in UTF-8 or (very rarely) in UTF-16 depending on how we receive the message from the handset. MO messages with Binary encoding are discarded.

Concatenated (long) MO messages can be assembled by Fonix and then transmitted as one long message using the message_payload parameter (you need to let us know to enable this). If the message_payload parameter is used, then the short_message parameter will be empty (sm_length=0).

Please also note the custom TLV parameters included in MO messages.

If you receive MO messages on adult shortcodes (69xxx, 79xxx or 89xxx) then we may tell you whether the user is allowed to receive adult services or not with these values: {av,"verified"} ou {av,"not_verified"} ou {av,"unknown"}.

#DELIVER_SM MO message example:
#  [{short_message,"Hello"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"e9e26d88-029d-4464-a5fa-b221e71a7159"},
#  {connection,"o2-uk"}]

#DELIVER_SM Concatenated (long) MO message example (if enabled):
#  [{short_message,[]},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"0e1d4e59-7915-4ebf-852c-12d1b71db974"},
#  {connection,"o2-uk"},
#  {message_payload,"Why were you born when the snow was falling? 
#  You should have come to the cuckoo's calling, 
#  Or when grapes are green in the cluster, 
#  Or, at least, when lithe swallows muster 
#  For their far off flying From summer dying."}]

The short_message parameter of DR messages is always encoded in UTF-8 and contains the following structure:

id:GUID sub:001 dlvrd:001 submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:STATUS err:ERR text:TEXT

• stat contains the delivery status of the corresponding MT message. Allowed values are:
  • stat:DELIVRD
  • stat:UNDELIV
  • stat:DELETED
  • stat:EXPIRED
  • stat:UNKNOWN

  The corresponding MT message is successfully delivered only if stat:DELIVRD

• err can be a positive or negative number or an alphanumeric string. It will not contain spaces.
• text contains the first twenty characters of the corresponding mt message (Empty if the MT message was a binary).

#DELIVER_SM DR message example:
#  [{short_message,"id:5822fcc6-6da6-4107-90da-33f00cefa12d sub:001
#  dlvrd:001 submit date: 1403181055 done date:1403181055 stat:DELIVRD
#  err:000 text:hello world"},
#  {data_coding,0},
#  {esm_class,4},
#  {source_addr_ton,1},
#  {source_addr_npi,1},
#  {source_addr,"447111222333"},
#  {destination_addr,"12345"},
#  {dest_addr_npi,0},
#  {dest_addr_ton,5},
#  {protocol_id,0},
#  {service_type,""},
#  {priority_flag,0},
#  {schedule_delivery_time,""},
#  {replace_if_present,0},
#  {sm_default_message_id,0},
#  {validity_period,""},
#  {receipted_message_id,"5822fcc6-6da6-4107-90da-33f00cefa12d"},
#  {connection,"o2-uk"}]

Increasingly consumers send MO messages longer then 160 chracters, which are then concatenated by the handset and sent in message parts to our gateway. At Fonix, we have developed a mechanism to aggregate all message parts and send them to you in one long MO message we originate

We concatenate a maximum of 20 message parts into one long MO message.

Codes des opérateurs mobiles

The following list of values are used in the connection parameter:

APPENDIX A

Every requests supports a DUMMY parameter that allows you to send test requests to our system.
If you send requests with a TEST API Key (i.e. an API key starting with test_) then you can omit the DUMMY parameter but your requests will still be handled as DUMMY.

DUMMY requests are not forwarded to the Mobile Operators.

DUMMY requests allow you to test our interface. We advise to do full end to end tests before creating a new live service.

The response sent to a DUMMY request depends on the MSISDN you submit in the request. Below you can find more details for each type of request together with related examples.

In each type of request OPERATOR sera défini en fonction des 4 premiers chiffres du MSISDN, conformément au tableau suivant:

Pour tout autre préfixe msisdn, celui-ci sera défini en fonction d'une recherche dans les plages de numéros.

DUMMY SMS Requests & WAP PUSH

# SEND SMS request
curl -i https://sonar.fonix.io/v2/sendsms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=440200000001 
 -d BODY=Welcome%20Home

# SEND SMS response
# {"success":{"txguid":"0ec3c023-21fb-4d2c-a942-18e1ab17815a",
#  "numbers":"1","smsparts":"1","encoding":"gsm"}}

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000001
# &DESTINATION=84988&STATUSTIME=20160301114836&STATUSTEXT=OK
# &STATUSCODE=DELIVERED&CHARGESTATUS=false
# &GUID=0ec3c023-21fb-4d2c-a942-18e1ab17815a&PRICE=10&DURATION=0

# CHARGE SMS request
curl -i https://sonar.fonix.io/v2/chargesms 
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t 
 -d ORIGINATOR=84988 
 -d NUMBERS=440200000004 
 -d BODY=Welcome%20Home

# CHARGE SMS response
# {"success":{"txguid":"680f3176-cd7e-484d-aef9-7c46e95187ef",
#  "numbers":"1","smsparts":"1","encoding":"gsm","price":10}}

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000004
# &DESTINATION=84988&STATUSTIME=20160301110820
# &STATUSTEXT=Operator+System+Error&STATUSCODE=SMSC_ERROR
# &CHARGESTATUS=false&GUID=680f3176-cd7e-484d-aef9-7c46e95187ef
# &PRICE=10&DURATION=0

When submitting a valid DUMMY SMS or WAP request the system generates a response and a DR without submitting the request to network operators. You will get an error in the response if one ore more parameters are not valid.

We don’t perform duplicate checks on DUMMY requests and we try to deliver DRs only once.

You can force the OPERATOR, CHARGESTATUS (only for RECHARGER PAR SMS requests), STATUSCODE et STATUSTEXT of the DR that we’ll send back to you through the NUMBERS parameter that you pass in the request to us.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

CHARGESTATUS, STATUSCODE et STATUSTEXT can be controlled using the last 8 digit of the MSISDN:

DUMMY ADULT VERIFY

# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.440000000001 
-d NETWORKRETRY=YES

# Sync Response
# {"verified":{"ifversion":"201001","operator":"o2-uk",
#  "guid":"5917d9ad-8c13-42a2-8a42-fd1d65cf2728"}}

# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=eetmo-uk.440000000001 
-d NETWORKRETRY=NO

# Sync Response
# {"unknown":{"ifversion":"201001","operator":"eetmo-uk",
#  "guid":"938323a6-5147-43e7-b552-247ca9e62108"}}

# Async Request
curl -i  https://sonar.fonix.io/v2/adultverify 
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t 
-d NUMBERS=three-uk.440100000002 
-d NETWORKRETRY=YES

# Async Response
# {"success":{"txguid":"3f8b527c-e27a-4a56-9cab-b3bb3ff7b885",
#  "numbers":"1"}}

# AV REPORT HTTPS POST (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=voda-uk&GUID=3f8b527c-e27a-4a56-9cab-b3bb3ff7b885&AV=NOT_VERIFIED

DUMMY requests can be sent to both synchronous and asynchronous APIs.

The synchronous response and the AV report depend on the MSISDN submitted.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

The AV status is fixed based on the last 8 digit of the MSISDN submitted according to the following table.

Si NETWORKRETRY=NO and the operator submitted doesn’t match the one set by the first 4 digit of the submitted MSISDN then the AV status will always be unknown.

DUMMY OPERATOR LOOKUP

# Request
  curl -i http://sonar.fonix.io/v2/operator_lookup?NUMBER=440500000002 
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

# Response
{
   "success":
       {"mcc":"234",
         "mnc":"20",
         "operator":"three-uk"}
   }

DUMMY requests receive responses depending on the MSISDN submitted. OPERATOR is set based on the first 4 digit of the MSISDN according to the above table.

Version du document

v2.9