Registrare un mittente SMS tramite API

Alcuni paesi consegnano SMS solo da un mittente registrato per quel paese. Tramite API rivendichi il mittente, crei la sua registrazione per il paese di destinazione e invii la documentazione richiesta dalla registrazione, con gli stessi passaggi della dashboard. Una registrazione può addebitare una tariffa di attivazione appena viene creata, quindi verifica prima il prezzo e il tuo wallet.

Prima di iniziare

• Una chiave API con sms_management in scrittura per creare mittenti e registrazioni, e compliance in scrittura per inviarne la documentazione.
• Per verificare prima prezzi e fondi del wallet, un token OAuth di un utente delegato, descritto in Verificare i prezzi di registrazione e i fondi del wallet. Una chiave API non può leggere la fatturazione dell'organizzazione.

Gli esempi leggono la chiave da BIRD_API_KEY, il suo host regionale da BIRD_API_URL, il paese di destinazione da COUNTRY_CODE e l'identificatore scr_ della registrazione da REGISTRATION_ID, quando lo hai ottenuto.

Verificare i prezzi di registrazione e i fondi del wallet

Per mostrare le stesse informazioni su prezzi e wallet della dashboard, usa GET /v1/organization/billing/prices/resolve e GET /v1/organization/billing/wallets. Queste letture richiedono un token OAuth di un utente delegato con org:billing:read. Le chiavi API dello spazio di lavoro, le chiavi master dell'organizzazione e i token degli account di servizio non possono concedere questo permesso di fatturazione dell'organizzazione.

Usa il discovery delle risorse protette OAuth e i metadati del server di autorizzazione per ottenere issuer, registration_endpoint, authorization_endpoint e token_endpoint, come descritto in Discovery OAuth. Registra un tuo client OAuth pubblico presso l'registration_endpoint individuato, fornendo client_name, redirect_uris e token_endpoint_auth_method: "none". Invia l'utente all'authorization_endpoint individuato con quel client_id, response_type=code, il tuo redirect_uri registrato, un nuovo state, scope=org:billing:read, un code_challenge derivato dal tuo verifier e code_challenge_method=S256. Nella schermata di consenso, l'utente seleziona uno spazio di lavoro nell'organizzazione prevista e concede org:billing:read se il suo ruolo lo consente. Convalida state rispetto al valore che hai inviato e iss rispetto all'issuer ottenuto dal discovery, poi scambia il codice presso il token_endpoint individuato con grant_type=authorization_code, il code restituito, client_id, lo stesso redirect_uri e il code_verifier originale. Usa l'access token ottenuto come BIRD_OAUTH_TOKEN. Rispetta il suo expires_in; conserva il refresh token in modo sicuro e sostituiscilo dopo ogni refresh riuscito. Esegui i tentativi di refresh uno alla volta, perché ogni refresh token è monouso. Ripeti l'autorizzazione quando la concessione di refresh scade o viene revocata.

Il token è vincolato allo spazio di lavoro selezionato e alla sua organizzazione; le letture di fatturazione si applicano a quell'organizzazione. X-Organization-Id non può spostarlo su un'altra organizzazione: ripeti l'autorizzazione per quell'organizzazione. Imposta esplicitamente l'host regionale quando configuri un SDK con questo token.

Per un mittente SMS alfanumerico, ricava il prezzo di attivazione della sua registrazione in base al paese di destinazione:

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"

Ricava product_slug=sms_sender con le stesse dimensioni per ottenere il prezzo ricorrente. Per eseguire lo stesso controllo del saldo della dashboard, somma il gross_price.amount della risposta di attivazione al primo addebito ricorrente, cioè il gross_price.amount della risposta ricorrente moltiplicato per il suo intervals_per_charge. Confronta questo totale con balance del wallet in data il cui currency_code corrisponde al gross_price.currency_code di entrambi i prezzi. Usa l'aritmetica decimale senza arrotondare gli importi restituiti. Se il totale supera il saldo, la differenza è l'importo mancante: ricarica il wallet o verifica l'accordo di credito della tua organizzazione prima di creare la registrazione. Nel controllo finale di copertura il server considera anche un eventuale limite di credito. Queste letture mostrano prezzi e fondi attuali, ma non riservano fondi né approvano una registrazione.

Ottieni la registrazione per cui presentare la documentazione

1. Trova il mittente con GET /v1/sms/senders o GET /v1/sms/senders/{sender_id}. Se necessario, creane uno con POST /v1/sms/senders.
2. Leggi GET /v1/sms/senders/{sender_id}/requirements per la destinazione e segui i suoi passaggi next. Se ti chiede di creare una registrazione, controllane il prezzo come descritto in Controlla i prezzi delle registrazioni e i fondi del wallet, poi chiama POST /v1/sms/senders/{sender_id}/registrations con country_code.
3. Rileggi i requisiti del mittente e conserva il registration_id (scr_) della riga come REGISTRATION_ID e il suo program come PROGRAM. Presenta la documentazione solo quando il has_compliance_requirements della riga è true. Quando è false, la registrazione non richiede alcun invio oppure è gestita da un programma dedicato, quindi segui invece il next della riga. I programmi dedicati, come la verifica dei numeri toll-free e il 10DLC, hanno passaggi propri.

La lettura dei mittenti richiede sms_management:read, mentre la creazione di mittenti e registrazioni richiede sms_management:write. Per presentarne la documentazione serve anche compliance:write.

Presenta la documentazione della registrazione

Questa sezione riguarda le registrazioni il cui has_compliance_requirements è true.

Leggi cosa richiede la registrazione con GET /v1/compliance/requirements, passando sms_sender come subject_kind e la registrazione come 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"

I campi si leggono come per un numero: Leggi cosa richiede il paese li spiega uno per uno e Carica ogni documento descrive i file richiesti da un campo document. Presenta tutte le risposte con POST /v1/compliance/submissions, indicando la registrazione come soggetto:

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'esempio mostra una sola risposta. Invia una voce per ogni campo il cui required è true e per ogni campo facoltativo a cui puoi dare una risposta reale, come spiega Invia tutte le risposte. Una risposta 201 restituisce l'invio: conserva il suo csb_ id. Un mittente non ha un campo ownership, quindi segui la revisione leggendo l'invio con GET /v1/compliance/submissions/{submission_id}, le cui risposte riportano il proprio state e, in caso di rifiuto, un reason, oppure rileggendo i requisiti del mittente per conoscere lo stato della registrazione. Sostituisci le risposte rifiutate con POST /v1/compliance/submissions/{submission_id}/resupply, come mostra Correggi una risposta rifiutata.

Passaggi successivi

• Presentare la documentazione di titolarità di un numero
• ID mittente SMS