Enregistrer un expéditeur SMS via l’API

Certains pays ne distribuent les SMS que depuis un expéditeur enregistré pour eux. Via l’API, vous revendiquez l’expéditeur, créez son enregistrement pour le pays de destination et déposez les pièces demandées par cet enregistrement, soit les mêmes étapes que le tableau de bord. Un enregistrement peut facturer des frais de mise en place dès sa création : vérifiez donc d’abord le prix et votre portefeuille.

Avant de commencer

• Une clé API disposant de sms_management en écriture pour créer des expéditeurs et des enregistrements, et de compliance en écriture pour déposer leurs pièces.
• Pour vérifier d’abord les prix et les fonds du portefeuille, un jeton OAuth d’utilisateur délégué, décrit dans Vérifier les prix d’enregistrement et les fonds du portefeuille. Une clé API ne peut pas lire la facturation de l’organisation.

Les exemples lisent votre clé depuis BIRD_API_KEY, son hôte régional depuis BIRD_API_URL, le pays de destination depuis COUNTRY_CODE et, une fois que vous l’avez, l’identifiant scr_ de l’enregistrement depuis REGISTRATION_ID.

Vérifier les prix d’enregistrement et les fonds du portefeuille

Pour afficher les mêmes informations de prix et de portefeuille que le tableau de bord, utilisez GET /v1/organization/billing/prices/resolve et GET /v1/organization/billing/wallets. Ces lectures exigent un jeton OAuth d’utilisateur délégué avec org:billing:read. Les clés API d’espace de travail, les clés principales d’organisation et les jetons de compte de service ne peuvent pas accorder cette autorisation de facturation de l’organisation.

Utilisez la découverte de ressource protégée OAuth et les métadonnées du serveur d’autorisation pour obtenir issuer, registration_endpoint, authorization_endpoint et token_endpoint, comme décrit dans Découverte OAuth. Enregistrez votre propre client public OAuth auprès du registration_endpoint découvert, en fournissant client_name, redirect_uris et token_endpoint_auth_method: "none". Redirigez l’utilisateur vers le authorization_endpoint découvert avec ce client_id, response_type=code, votre redirect_uri enregistré, un state nouveau, scope=org:billing:read, un code_challenge dérivé de votre vérificateur, et code_challenge_method=S256. Sur l’écran de consentement, l’utilisateur sélectionne un espace de travail dans l’organisation visée et accorde org:billing:read si son rôle le permet. Validez state par rapport à la valeur envoyée et iss par rapport à l’émetteur issu de la découverte, puis échangez le code auprès du token_endpoint découvert avec grant_type=authorization_code, le code renvoyé, client_id, le même redirect_uri et le code_verifier d’origine. Utilisez le jeton d’accès obtenu comme BIRD_OAUTH_TOKEN. Respectez son expires_in ; stockez le jeton d’actualisation de façon sécurisée et remplacez-le après chaque actualisation réussie. Sérialisez les tentatives d’actualisation, car chaque jeton d’actualisation n’est utilisable qu’une fois. Demandez une nouvelle autorisation lorsque l’octroi d’actualisation expire ou est révoqué.

Le jeton est lié à l’espace de travail sélectionné et à son organisation ; les lectures de facturation s’appliquent à cette organisation. X-Organization-Id ne permet pas de le basculer vers une autre organisation : répétez l’autorisation pour celle-ci. Définissez explicitement l’hôte régional lorsque vous configurez un SDK avec ce jeton.

Pour un expéditeur SMS alphanumérique, déterminez le prix de mise en place de son enregistrement à partir du pays de destination :

curl --get "$BIRD_API_URL/v1/organization/billing/prices/resolve" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN" \
  --data-urlencode 'product_slug=sms_sender_registration' \
  --data-urlencode "dimensions[country_code]=$COUNTRY_CODE" \
  --data-urlencode 'dimensions[sender_type]=alphanumeric'

curl "$BIRD_API_URL/v1/organization/billing/wallets" \
  --header "Authorization: Bearer $BIRD_OAUTH_TOKEN"

Déterminez product_slug=sms_sender avec les mêmes dimensions pour obtenir le prix récurrent. Pour effectuer la même vérification de solde que le tableau de bord, ajoutez le gross_price.amount de la réponse de mise en place au premier prélèvement récurrent, c'est-à-dire le gross_price.amount de la réponse récurrente multiplié par son intervals_per_charge. Comparez ce total au balance du portefeuille de data dont le currency_code correspond au gross_price.currency_code des deux prix. Calculez en décimal sans arrondir les montants renvoyés. Si le total dépasse le solde, la différence correspond au montant manquant : rechargez votre portefeuille ou vérifiez l'accord de crédit de votre organisation avant de créer l'enregistrement. Le serveur tient aussi compte d'une éventuelle limite de crédit lors de sa vérification finale de solvabilité. Ces lectures indiquent les prix et les fonds au moment de la requête ; elles ne réservent pas de fonds et n'approuvent aucun enregistrement.

Obtenir l'enregistrement pour lequel déposer le dossier

1. Trouvez l'expéditeur avec GET /v1/sms/senders ou GET /v1/sms/senders/{sender_id}. Si nécessaire, créez-en un avec POST /v1/sms/senders.
2. Lisez GET /v1/sms/senders/{sender_id}/requirements pour la destination, puis suivez ses étapes next. S'il vous demande de créer un enregistrement, vérifiez d'abord son prix comme dans Vérifier les prix d'enregistrement et les fonds du portefeuille, puis appelez POST /v1/sms/senders/{sender_id}/registrations avec country_code.
3. Relisez les exigences de l'expéditeur et conservez le registration_id (scr_) de la ligne comme REGISTRATION_ID et son program comme PROGRAM. Déposez le dossier uniquement lorsque le has_compliance_requirements de la ligne vaut true. Lorsqu'il vaut false, l'enregistrement ne nécessite aucune soumission ou relève d'un programme dédié : suivez alors le next de la ligne. Les programmes dédiés, comme la vérification des numéros gratuits et le 10DLC, ont leurs propres étapes.

La lecture des expéditeurs nécessite sms_management:read, et la création d'expéditeurs et d'enregistrements nécessite sms_management:write. Le dépôt de leur dossier nécessite en plus compliance:write.

Déposer le dossier de l'enregistrement

Cette section concerne un enregistrement dont le has_compliance_requirements vaut true.

Lisez ce que demande l'enregistrement avec GET /v1/compliance/requirements, en indiquant sms_sender comme subject_kind et l'enregistrement comme subject_id :

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=sms_sender&subject_id=$REGISTRATION_ID&country_code=$COUNTRY_CODE&program=$PROGRAM" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Les champs se lisent comme pour un numéro : Lire ce que demande le pays explique chacun d'eux, et Téléverser chaque document décrit les fichiers que demande un champ document. Déposez chaque réponse avec POST /v1/compliance/submissions, en désignant l'enregistrement comme sujet :

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: sender-$REGISTRATION_ID" \
  --data '{
    "subject_kind": "sms_sender",
    "subject_id": "'"$REGISTRATION_ID"'",
    "program": "'"$PROGRAM"'",
    "country_code": "'"$COUNTRY_CODE"'",
    "answers": [{ "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }]
  }'

L'exemple montre une seule réponse. Envoyez une entrée pour chaque champ dont le required vaut true, ainsi que pour chaque champ facultatif auquel vous avez une vraie réponse, comme l'explique Soumettre chaque réponse. Une réponse 201 renvoie la soumission ; conservez son csb_ id. Un expéditeur n'a pas de champ ownership. Pour suivre l'examen, lisez donc la soumission avec GET /v1/compliance/submissions/{submission_id}, dont les réponses indiquent leur state et, en cas de rejet, un reason, ou relisez les exigences de l'expéditeur pour connaître le statut de l'enregistrement. Remplacez les réponses rejetées avec POST /v1/compliance/submissions/{submission_id}/resupply, comme le montre Corriger une réponse rejetée.

Étapes suivantes

• Déposer les documents de propriété d’un numéro
• Identifiants d’expéditeur SMS