Envoi d'un mot de passe à usage unique (OTP)

URL de l'API

URL à laquelle envoyer les requêtes HTTP :

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 backup1.bulkgate.com.

Méthodes HTTP prises en charge

POST - application/json

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	Oui	-
application_token	Application token	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 disponibles	non	`null` - illimité
trials_available_verification	Limite des vérifications 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, Viber, RCS, WhatsApp ou 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	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)	non	`null`
domain	URL d'un site web qui utilise WebOTP 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	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.	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 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

{ "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 :

{ "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } }

En cas d'erreur :

{ "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null }

{ "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
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, 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.

Cette page vous a-t-elle été utile ?

Demander à l'IA Copié