## URL de l'API URL à laquelle envoyer les requêtes HTTP : ```url https://portal.bulkgate.com/api/1.0/otp/send ``` > [!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`. ## Méthodes HTTP prises en charge - `POST` - `application/json` ```http POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!IMPORTANT] > En plus de `request_quota_number`, l'endpoint applique une **limite de 60 requêtes par minute pour l'ensemble du compte**. En cas de dépassement, il renvoie `the_quota_of_send_per_minute_has_been_exceeded`. ## Tableau des paramètres | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:------------------------------|:-------|:------------|:------------------| | application_id | [Application ID](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/administration-api/) | **Oui** | - | | application_token | [Application token](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/tokens-d-api/) | **Oui** | - | | number | Numéro de téléphone auquel envoyer le code de vérification | **Oui** | - | | country | Code pays du numéro de téléphone | non | La valeur est reprise du profil. | | language | Langue du texte du message, l'un des 100 codes ISO pris en charge. Un code inconnu entraîne le rejet de la requête. S'il est absent, la langue est déterminée d'après le numéro de téléphone. | non | `null` | | code_type | Type de code. (`string`, `int` ou `combined`) | non | `int` | | code_length | Longueur du code de vérification (4-100). | non | 6 | | request_quota_number | Nombre de requêtes par minute pour `request_quota_identification` | non | 1 | | request_quota_identification | Identification de l'« utilisateur / demandeur OTP » auquel s'applique le quota de `request_quota_number` requêtes par minute. Nous recommandons d'utiliser une adresse IP pour cette identification. | **Oui** | - | | trials_available_resend | Limite des [renvois](https://www.bulkgate.com/fr/documentation/otp-api/renvoi-mot-de-passe-a-usage-unique/) disponibles | non | `null` - illimité | | trials_available_verification | Limite des [vérifications](https://www.bulkgate.com/fr/documentation/otp-api/verification-mot-de-passe-a-usage-unique/) disponibles | non | `null` - illimité | | daily_limit | Limite des requêtes disponibles par jour (glissante sur les dernières 24 heures) | non | `null` - illimité | | daily_limit_country | Limite quotidienne par pays sous forme de tableau associatif `{"cz": 100, "sk": 50}`. Une fois renseignée, **seuls** les pays listés sont autorisés — tout autre pays échoue avec `country_is_disabled`. | non | `null` - illimité | | expiration | Expiration de la requête OTP en secondes ; une fois ce délai écoulé, la requête n'est plus possible. Une valeur inférieure à `60` est ignorée et la valeur par défaut est utilisée. | non | `604800` - 7 jours | | channel | Canaux alternatifs. Les canaux sont classés en cascade : si nous ne parvenons pas à délivrer votre message par le canal de plus haute priorité, les canaux situés plus bas dans la cascade sont utilisés. Si aucun d'eux n'y parvient, le SMS est utilisé à la place. | non | [SMS](#objet-sms), [Viber](#objet-viber), [RCS](#objet-rcs), [WhatsApp](#objet-whatsapp) ou [Text2Voice](#objet-text2voice) | ## Canaux L'objet `channel` détermine par quels canaux le code est délivré et dans quel ordre. **L'ordre des clés dans la requête correspond à l'ordre de la cascade** — si le premier canal ne parvient pas à délivrer le code, le suivant est essayé. Si aucun n'y parvient, le SMS est utilisé. ### Objet SMS | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:-----------------|:-------|:------------|:------------------| | sender_id | Identifiant d'expéditeur, voir [type d'identifiant d'expéditeur](https://www.bulkgate.com/fr/documentation/simple-api/simple-transactional/) | 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` [(KEY)](https://www.bulkgate.com/fr/centre-d-aide/mobile-connect/installation-mobile-connect/) | non | `null` | | domain | URL d'un site web qui utilise [WebOTP](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API) pour la saisie automatique du code reçu. | non | `null` | ### Objet Viber | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:-----------------|:-------|:------------|:------------------| | sender | Nom de votre [expéditeur enregistré pour Viber](https://www.bulkgate.com/fr/centre-d-aide/viber/enregistrement-expediteur-viber/) | **Oui** | - | | expiration | Nombre de secondes d'attente avant d'essayer un autre canal | non | 60 | | code_type | Type de code exigé par Viber, indiqué dans le modèle OTP approuvé. | non | `null` | | code_reason | Motif de l'envoi du code, exigé par Viber. | non | `null` | | business_name | Nom de l'entreprise affiché dans le message. | non | `null` | ### Objet RCS | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:-----------------|:-------|:------------|:------------------| | sender | Expéditeur texte pour RCS. Il doit d'abord être enregistré — pour l'enregistrer, contactez [notre support](https://www.bulkgate.com/fr/nous-contacter/). | **Oui** | - | | expiration | Nombre de secondes d'attente avant d'essayer un autre canal | non | 60 | | use_card | Envoie le code sous forme de carte au lieu de texte brut. | non | `false` | ### Objet WhatsApp | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:-----------------|:-------|:------------|:------------------| | sender | Votre [expéditeur WhatsApp](https://www.bulkgate.com/fr/centre-d-aide/whatsapp/enregistrement-expediteur-whatsapp/) enregistré | **Oui** | - | | template | Nom du modèle WhatsApp approuvé utilisé pour délivrer le code. | Non | `verification_code` | | language | Langue du modèle. S'il est absent, le paramètre `language` de la requête est utilisé. | Non | `null` | | expiration | Nombre de secondes d'attente avant d'essayer un autre canal de la cascade. Minimum `60`. | Non | `180` | ### Objet Text2Voice Le code est lu à voix haute. Le message peut être répété pour que le destinataire puisse le noter. | NOM DU PARAMÈTRE | VALEUR | OBLIGATOIRE | VALEUR PAR DÉFAUT | |:-----------------|:-------|:------------|:------------------| | sender | Votre numéro d'appelant enregistré. | **Oui** | - | | language | Langue de la voix, l'un des 47 codes ISO pris en charge. S'il est absent, le paramètre `language` de la requête est utilisé. | Non | `null` | | prefer_gender | Voix préférée - `male` ou `female`. | Non | `male` | | safety_statement | Ajoute un avertissement de sécurité au début de l'appel. | Non | `true` | | repeat | Nombre de répétitions du code pendant l'appel. | Non | `1` | | expiration | Nombre de secondes d'attente avant d'essayer un autre canal de la cascade. Minimum `60`. | Non | `180` | ## Exemple de requête ```json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "420777777777", "country": "cz", "language": "fr", "code_type": "string", "code_length": 7, "request_quota_number": 1, "request_quota_identification": "127.0.0.1", "trials_available_resend": 2, "trials_available_verification": 5, "daily_limit": 100, "daily_limit_country": {"cz": 150, "sk": 50}, "expiration": 3600, "channel": { "rcs": { "sender": "Lt. Hagan", "expiration": 100 }, "viber": { "sender": "Lt. Hagan", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true } } } ``` ## Réponse **En cas de succès :** ```json { "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } } ``` **En cas d'erreur :** ```json { "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null } ``` ```json { "type": "invalid_input_parameters", "code": 400, "error": "Invalid input parameters", "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** représente l'erreur HTTP - **detail** contient des informations complémentaires sur l'erreur ### Types d'erreurs de l'API OTP En plus des [types communs](https://www.bulkgate.com/fr/documentation/administration-api-et-tokens/types-d-erreurs-api/), l'API OTP renvoie ses propres types : | TYPE | QUAND CELA SE PRODUIT | |:-------------------------------------------------------------|:----------------------------------------------------------------------| | `the_quota_of_send_per_minute_has_been_exceeded` | Le quota d'envois par minute est épuisé. | | `the_quota_of_one_additional_resend_per_minute_has_been_exceeded` | Un renvoi intervient moins de 60 s après le précédent. | | `the_quota_of_one_additional_resend_has_been_exceeded` | `trials_available_resend` est épuisé. | | `the_quota_of_one_additional_verification_has_been_exceeded` | `trials_available_verification` est épuisé. | | `daily_limit_reached` | `daily_limit` est épuisé. | | `country_is_disabled` | Le pays du numéro ne figure pas dans `daily_limit_country`. | | `country_daily_limit_exceeded` | La limite quotidienne pour ce pays est épuisée. | | `invalid_phone_number` | Le numéro n'a pas pu être reconnu. | | `invalid_code` | Le code vérifié ne correspond pas. | | `unknown_channel` | La cascade contient un canal que l'API OTP ne connaît pas. | | `request_can_not_be_created` | La requête n'a pas pu être créée. |