---
title: "Registrare un mittente SMS tramite API"
description: "Rivendica un mittente SMS, crea la sua registrazione per un paese, verifica prima il prezzo e i fondi del wallet e invia la documentazione della registrazione tramite API."
canonical: "https://bird.com/it-it/documentazione/guides/sms/sender-registration-api"
---

# 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](/docs/guides/authentication) 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](#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](/docs/api/regions) 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`](/docs/api/reference/get-billing-resolved-price) e [`GET /v1/organization/billing/wallets`](/docs/api/reference/list-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](/docs/ai/mcp-server#how-the-handshake-works). 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:

```bash
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`](/docs/api/reference/list-workspace-sms-senders) o [`GET /v1/sms/senders/{sender_id}`](/docs/api/reference/get-workspace-sms-sender). Se necessario, creane uno con [`POST /v1/sms/senders`](/docs/api/reference/create-workspace-sms-sender).
2. Leggi [`GET /v1/sms/senders/{sender_id}/requirements`](/docs/api/reference/list-workspace-sms-sender-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](#verificare-i-prezzi-di-registrazione-e-i-fondi-del-wallet), poi chiama [`POST /v1/sms/senders/{sender_id}/registrations`](/docs/api/reference/create-workspace-sms-sender-registration) 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`](/docs/api/reference/get-workspace-compliance-requirements), passando `sms_sender` come `subject_kind` e la registrazione come `subject_id`:

```bash
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](/docs/guides/numbers/ownership-paperwork#read-what-the-country-asks-for) li spiega uno per uno e [Carica ogni documento](/docs/guides/numbers/ownership-paperwork#upload-each-document) descrive i file richiesti da un campo `document`. Presenta tutte le risposte con [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), indicando la registrazione come soggetto:

```bash
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](/docs/guides/numbers/ownership-paperwork#submit-every-answer). 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}`](/docs/api/reference/get-workspace-compliance-submission), 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`](/docs/api/reference/update-workspace-compliance-submission), come mostra [Correggi una risposta rifiutata](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer).

## Passaggi successivi

- [Presentare la documentazione di titolarità di un numero](/docs/guides/numbers/ownership-paperwork)
- [ID mittente SMS](/docs/guides/sms/senders)

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer)
- [SMS](/sms-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms)