Utilisation de l'API OxiSMS

1. Envoyer des SMS
2. Accéder aux informations du compte utilisateur

1. Envoyer des SMS

URL à appeler : https://www.oxisms.com/api/1.0/send.php

Couverture et contraintes de délivrabilité des SMS : Couverture-internationale

a. Liste des paramètres

Les paramètres sont à envoyer à l'API avec une requête HTTP de type GET ou POST.

Nom du paramètre	Requis ?	Description	Remarque
api_key	Requis	Identifiant de l’API
api_password	Requis	Mot de passe d’accès à l’API
message	Requis	Le message à envoyer par SMS	Le message doit être encodé au format UTF-8.
recipients	Requis	Tableau de numéros de téléphones des destinataires séparés par le caractère virgule « , ».	Il ne peut pas y avoir plus de 250 destinataires par appel d’API.
encoding	Facultatif	Valeur : « unicode » ou « gsm ». GSM Alphabet GSM 7-bits. 160 caractères autorisés par SMS, 153 caractères lors d’une concaténation. Unicode Permet l’envoi de caractères hors norme GSM. 70 caractères autorisés par SMS, 67 caractères lors d’une concaténation.
sender	Facultatif	Le nom ou le numéro de l’émetteur du SMS.	Suivre les contraintes détaillées sur la page de couverture.
type	Facultatif	Valeur : « notification » ou « commercial ». Type de message	Valeur par défaut : « commercial ». Conformément à la législation les envois en stratégie commerciale ne sont pas possibles le soir après 21h00, le matin avant 8h00 ainsi que le dimanche et les jours fériés. Ils sont automatiquement reportés au prochain créneau disponible.
credit_max	Facultatif	Le crédit maximum que l’on souhaite dépenser pour faire l’envoi. Si le crédit qui serait dépensé est supérieur à la valeur indiquée, l’envoi est refusé.	Utile pour être certain que le coût de l’envoi est correctement calculé.
test	Facultatif	Bloque l’envoi réel des SMS mais simule l’envoi et retourne des informations détaillées pour chaque SMS.	Permet d’essayer l’API sans utiliser de crédit.

b. Retour de l'API

L’API OxiSMS retourne des données au format JSON :

Paramètre	Type	Description
success	Booléen	Vrai si des SMS ont tenté d’être envoyés. Faux si une erreur a empêché la tentative d’envoi.
message	Chaîne de caractères	Description de l’erreur
details	Tableau	Tableau d’information pour chaque SMS.

Description d’un SMS présent dans le tableau « details » :

Paramètre	Type	Description
id	Chaîne de caractères	Identifiant du SMS pour OxiSMS.
original_recipient	Chaîne de caractères	Numéro indiqué dans le paramètre « recipients ».
recipient	Chaîne de caractères	Numéro formaté utilisé réellement pour l’envoi.
sent	Booléen	Vrai si le SMS a été envoyé. Faux si un problème a empêché l’envoi.
return_code	Chaîne de caractères	Code décrivant l’erreur d’envoi.
description	Chaîne de caractères	Description de l’erreur d’envoi.

c. Exemple d’appel de l’API avec la méthode HTTP GET

Exemple d'URL : https://www.oxisms.com/api/1.0/send.php?api_key=IdentifiantAPI&api_password=MotDePasseAPI&message=Message&recipients=0033601234567

Le message « Message » sera envoyé au numéro « 0033601234567 » si les identifiants d’accès à l’API sont corrects.

{
  "success": true,
  "message": "success",
  "details": [
    {
      "id": "5e8404c725276d07f3f4fe246f2acc",
      "original_recipient": "0606060606",
      "recipient": "0606060606",
      "sent": true,
      "return_code": "NOT_REALLY_SENT",
      "description": "Le SMS n'a pas été réellement envoyé car le paramètre 'test' était présent"
    },
    {
      "id": null,
      "original_recipient": "pas_un_numero",
      "recipient": null,
      "sent": false,
      "return_code": "INVALID_RECIPIENT",
      "description": "Invalid recipient value: 'pas_un_numero'"
    }
  ]
}

2. Accéder aux informations du compte utilisateur

URL à appeler : https://www.oxisms.com/api/1.0/account.php

a. Liste des paramètres

Les paramètres sont à envoyer à l’API avec une requête HTTP de type GET ou POST.

Nom du paramètre	Requis ?	Description	Remarque
api_key	Requis	Identifiant de l’API
api_password	Requis	Mot de passe d’accès à l’API

b. Retour de l’API

L’API OxiSMS retourne des données au format JSON :

Paramètre	Type	Description
success	Booléen	Vrai si aucune erreur. Faux si une erreur est survenue.
message	Chaîne de caractères	Description de l’erreur.
details	Tableau	Tableau avec les informations du compte client.

Description des paramètres présents dans le tableau « details » :

Paramètre	Type	Description
customer_name	Chaîne de caractères	Nom et raison sociale associés au compte.
expiration_date	Chaîne de caractères	Date d’expiration des crédits au format YY-mm-dd.
expiration_date_unix	Entier	Date d’expiration des crédits au format timestamp UNIX
credit	Entier	Crédit restant.

c. Exemple d’appel de l’API avec la méthode HTTP GET

Exemple d'URL : https://www.oxisms.com/api/1.0/account.php?api_key=IdentifiantAPI&api_password=MotDePasseAPI

Les informations du compte seront indiquées si les identifiants d’accès à l’API sont corrects.

{
  "success": true,
  "message": "success",
  "details": {
    "customer_name": "M. Jean DUPONT",
    "expiration_date": "2020-07-20",
    "expiration_date_unix": 1595196000,
    "credit": 123.45
  }
}