## URL de l'API URL utilisée pour l'envoi des requêtes HTTP : ```url https://portal.bulkgate.com/api/1.0/integration/transactional-bulk ``` > [!NOTE] > Si la requête n'atteint pas sa destination, renvoyez-la sur le [serveur de secours](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/serveur-de-secours/) `backup1.bulkgate.com`. ```http POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > Il est **strictement interdit** d'utiliser les [SMS transactionnels](https://www.bulkgate.com/fr/centre-d-aide/informations-generales/difference-messages-promotionnels-transactionnels/) à des fins promotionnelles ou marketing. Ils doivent servir uniquement à des fins de notification - en tant que notification SMS. > [!NOTE] > Si vous souhaitez utiliser une route transactionnelle pour envoyer des notifications en masse, veuillez contacter [notre assistance](https://www.bulkgate.com/fr/nous-contacter/). Nous pouvons autoriser cette option pour un motif légitime. > [!WARNING] > Les destinataires qui se sont désinscrits recevront le message (la désinscription ne concerne que les messages promotionnels). ### Tableau des paramètres | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:------------------|:--------------------------------------------------------|:---------:|:---------------------------------:| | application_id | [ID d'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | **Oui** | - | | application_token | [Jeton d'authentification de l'application](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/) | **Oui** | - | | tag | Étiquette d'identification personnelle | Non | - | | messages | Tableau de messages | **Oui** | [Objet Message](#objet-message) | ### Objet Message | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:---------------------------------------:| | primary_channel | Canal principal utilisé en premier dans la cascade | Non | `sms` | | phone_number | Numéro de téléphone du destinataire | **Oui** | - | | country | Indiquez les numéros des destinataires au format international (avec l'indicatif, p. ex. `420`) ou ajoutez le [code pays](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Voir l'exemple de requête avec pays. Si la valeur est **`null`**, le fuseau horaire que vous avez défini sert à compléter l'information | Non | `null` | | schedule | Planification de la date et de l'heure d'envoi au format [timestamp Unix.](https://en.wikipedia.org/wiki/Unix_time) Voir les exemples ci-dessous. | Non | `null` | | channels | Tableau associatif des objets de canal | **Oui** | [Objet de canal](#objet-du-canal-viber) | ### Objet du canal Viber | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender | Nom de l'expéditeur | Non | - | | expiration | Délai après lequel le message expire | Non | `3600` | | text | Texte du message. Vous pouvez insérer dans le modèle des variables issues du tableau `variables` (autre paramètre) `Bonjour ....` | **Oui** | - | | variables | Tableau associatif permettant d'ajouter des variables au texte, p. ex. `{"first_name": "John", "last_name": "Doe"}` | Non | `[]` | ### Objet du canal SMS | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:| | sender_id | Identifiant d'expéditeur, voir [Type d'expéditeur](#type-d-expediteur-sender-id) | Non | `gSystem` | | sender_id_value | Valeur de l'expéditeur - `gOwn` (p. ex. « 420 777 777 777 »), `gText` (p. ex. « BulkGate »), `gProfile` (p. ex. « 423 »), `gMobile` ou `gPush` [(CLÉ)](https://www.bulkgate.com/fr/centre-d-aide/mobile-connect/installation-mobile-connect/) | Non | `''` | | unicode | `Yes`/`true`/`1` pour un SMS Unicode, `no`/`false`/`0` pour un SMS 7 bits | Non | `false` | | text | Texte du SMS (612 caractères max., ou 268 caractères si l'Unicode est activé), encodage UTF-8. Vous pouvez insérer dans le modèle des variables issues du tableau `variables` (paramètre supplémentaire) `Bonjour ....` | **Oui** | - | | variables | Tableau associatif permettant d'ajouter des variables au texte, p. ex. : `{"first_name": "John", "last_name": "Doe"}` | Non | `[]` | #### Type d'expéditeur `sender_id` | VALEUR | DESCRIPTION | |:-----------|:----------------------------------------------------------------------| | `gSystem` | Numéro système | | `gShort` | Short code | | `gText` | Expéditeur texte | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/fr/centre-d-aide/mobile-connect/installation-mobile-connect/) | | `gPush` | Mobile Connect push - Envoie une notification dans votre application Mobile Connect | | `gOwn` | Numéro personnel (nécessite la vérification du numéro) | | `gProfile` | [ID du profil d'expéditeur](https://www.bulkgate.com/fr/centre-d-aide/sms/profil-d-expediteur/) | | `` | ID du profil d'expéditeur | **Exemple de requête complète :** ```http-json POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## La réponse à cette commande peut être : **En cas de succès** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **En cas d'erreur :** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null } ``` Où : - **type** et **error** (description de l'erreur) sont décrits dans le [tableau des types d'erreurs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/) - **code** représente le code d'erreur HTTP - **detail** contient des informations complémentaires sur l'erreur Tous les types d'erreurs de la Simple API et de l'Advanced API sont disponibles [ici](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/).