> [!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 une notification groupée, veuillez contacter [notre support](https://www.bulkgate.com/fr/nous-contacter/). Nous pouvons autoriser cette option pour un motif légitime. ## URL de l'API URL utilisée pour envoyer les requêtes HTTP : ```url https://portal.bulkgate.com/api/2.0/advanced/transactional ``` > [!NOTE] > Si la requête n'atteint pas sa destination, répétez-la sur le [serveur de secours](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/serveur-de-secours/) `backup1.bulkgate.com`. ## Méthodes HTTP prises en charge - `POST` - `application/json` ```http POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tableau des paramètres | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:------------------|:-------|:-----------:|:-----------------:| | application_id | [Identifiant de l'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** | - | | number | Numéro du destinataire ou tableau de numéros de destinataires - [Valeur number](#valeur-number) | **Oui** ou `admin` | - | | admin | Numéro de l'administrateur BulkGate qui reçoit la notification. [Plus d'informations](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-transactional-notifications-aux-administrateurs/) | **Oui** ou `number` | - | | text | Texte du message SMS (max. 612 caractères, ou 268 caractères si Unicode est utilisé), encodage UTF-8. Il est possible d'ajouter au modèle des variables provenant du tableau `variables` (autre paramètre) `Hello ....` | **Oui** | - | | variables | Tableau associatif pour ajouter des variables au texte, par ex. : `{"first_name": "John", "last_name": "Doe"}` | Non | `[]` | | channel | Canaux alternatifs. Les canaux sont essayés en cascade, dans l'ordre dans lequel vous les indiquez dans l'objet : si nous ne parvenons pas à délivrer votre message par le premier canal, le suivant de la liste est utilisé. Le SMS n'est **pas** ajouté automatiquement ; si vous le souhaitez comme dernier recours, incluez l'objet `sms` dans la cascade. Si aucun canal n'est indiqué, le message est envoyé par SMS. | Non | [Objet SMS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-sms/) | | country | Indiquez les numéros des destinataires au format international (avec préfixe, par ex. `420`) ou ajoutez le [code pays au format ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`777777777` + `CZ` = `420777777777`). Voir l'exemple de requête avec le pays. Si la valeur est **`null`**, le fuseau horaire que vous avez défini est utilisé pour compléter l'information | Non | `null` | | schedule | Planifiez la date et l'heure d'envoi au format [timestamp Unix,](https://en.wikipedia.org/wiki/Unix_time) ou [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Non | Maintenant | | duplicates_check | Choisissez **`on`** pour éviter l'envoi de messages en double au même numéro de téléphone. Les messages au texte identique envoyés au même numéro dans un intervalle de moins de 5 minutes seront supprimés. Avec **`off`**, aucun doublon n'est supprimé. | Non | `off` | | tag | Libellé du message permettant à l'utilisateur de le retrouver ultérieurement. | Non | - | ### Valeur `number` La valeur number peut s'écrire comme suit : - Tableau de numéros de téléphone ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Canaux L'objet `channel` détermine par quels canaux et dans quel ordre le message est envoyé. **L'ordre des clés dans votre requête correspond à l'ordre de la cascade** et le SMS n'y est pas ajouté automatiquement - voir [Cascade de canaux](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-cascade/). | CLÉ | OBJET DU CANAL | |:-------------|:---------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-sms/) | | `viber` | [Viber – transactionnel](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-viber-transactionnel/) | | `rcs` | [RCS](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-whatsapp/) | ## Exemple de requête ```http-json POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "example text ", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } } ``` ## Réponse **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, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } } ``` Où : - **part_ID** est le tableau des ID des parties du message long d'origine, qui a été découpé parce qu'il dépassait la limite de 160 caractères d'un message unique. Plus d'informations [ici](https://www.bulkgate.com/fr/centre-d-aide/sms/concatenation-des-messages/). **En cas d'erreur :** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null } ``` Où : - **type** et **error** (description de l'erreur) figurent dans le [tableau des types d'erreurs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/) - **code** correspond au code d'erreur HTTP - **detail** contient des informations complémentaires sur l'erreur Consultez tous les types d'erreurs de la Simple API et de l'Advanced API [ici](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/).