---
title: "Registre um remetente SMS pela API"
description: "Reivindique um remetente SMS, crie o registro dele para um país, verifique antes o preço e o saldo da carteira e envie a documentação do registro pela API."
canonical: "https://bird.com/pt-br/documentacao/guides/sms/sender-registration-api"
---

# Registre um remetente SMS pela API

Alguns países só entregam SMS de um remetente registrado para eles. Pela API, você reivindica o remetente, cria o registro dele para o país de destino e envia a documentação que esse registro exige, os mesmos passos que o dashboard executa. Um registro pode cobrar uma taxa de configuração assim que é criado, então verifique antes o preço e sua carteira.

## Antes de começar

- Uma [chave API](/docs/guides/authentication) com `sms_management` em nível de escrita para criar remetentes e registros, e `compliance` em nível de escrita para enviar a documentação deles.
- Para verificar antes os preços e o saldo da carteira, um token OAuth de usuário delegado, descrito em [Verifique os preços de registro e o saldo da carteira](#verifique-os-preços-de-registro-e-o-saldo-da-carteira). Uma chave API não consegue ler o faturamento da organização.

Os exemplos leem sua chave de `BIRD_API_KEY`, o [host regional](/docs/api/regions) dela de `BIRD_API_URL`, o país de destino de `COUNTRY_CODE` e o identificador `scr_` do registro de `REGISTRATION_ID` assim que você o tiver.

## Verifique os preços de registro e o saldo da carteira

Para exibir as mesmas informações de preço e carteira que o dashboard, use [`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). Essas leituras exigem um token OAuth de usuário delegado com `org:billing:read`. Chaves API do espaço de trabalho, chaves mestras da organização e tokens de conta de serviço não podem conceder essa permissão de faturamento da organização.

Use a descoberta de recursos protegidos OAuth e os metadados do servidor de autorização para obter `issuer`, `registration_endpoint`, `authorization_endpoint` e `token_endpoint`, conforme descrito em [Descoberta OAuth](/docs/ai/mcp-server#how-the-handshake-works). Registre seu próprio cliente público OAuth no `registration_endpoint` descoberto, informando `client_name`, `redirect_uris` e `token_endpoint_auth_method: "none"`. Envie o usuário ao `authorization_endpoint` descoberto com esse `client_id`, `response_type=code`, seu `redirect_uri` registrado, um `state` novo, `scope=org:billing:read`, um `code_challenge` derivado do seu verificador e `code_challenge_method=S256`. Na tela de consentimento, o usuário seleciona um espaço de trabalho na organização pretendida e concede `org:billing:read` quando a função dele permite. Valide `state` em relação ao valor que você enviou e `iss` em relação ao emissor obtido na descoberta. Depois, troque o código no `token_endpoint` descoberto com `grant_type=authorization_code`, o `code` retornado, `client_id`, o mesmo `redirect_uri` e o `code_verifier` original. Use o token de acesso resultante como `BIRD_OAUTH_TOKEN`. Respeite o `expires_in` dele; armazene o token de atualização com segurança e substitua-o após cada atualização bem-sucedida. Serialize as tentativas de atualização, porque cada token de atualização só pode ser usado uma vez. Autorize novamente quando a concessão de atualização expirar ou for revogada.

O token fica vinculado ao espaço de trabalho selecionado e à organização dele; as leituras de faturamento se aplicam a essa organização. `X-Organization-Id` não consegue mudá-lo para outra organização; repita a autorização para essa organização. Defina o host regional explicitamente ao configurar um SDK com esse token.

Para um remetente SMS alfanumérico, obtenha o preço de configuração do registro usando o país de destino:

```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"
```

Obtenha `product_slug=sms_sender` com as mesmas dimensões para o preço recorrente. Para fazer a mesma verificação de saldo que o dashboard, some o `gross_price.amount` da resposta de configuração à primeira cobrança recorrente, que é o `gross_price.amount` da resposta recorrente multiplicado pelo seu `intervals_per_charge`. Compare esse total com o `balance` da carteira em `data` cujo `currency_code` corresponde ao `gross_price.currency_code` dos dois preços. Use aritmética decimal sem arredondar os valores retornados. Se o total ultrapassar o saldo, a diferença é o valor que falta. Nesse caso, adicione saldo ou verifique o acordo de crédito da sua organização antes de criar o registro. O servidor também considera qualquer limite de crédito na verificação final de saldo. Essas leituras mostram os preços e fundos atuais, mas não reservam fundos nem aprovam um registro.

## Obtenha o registro para o qual enviar a documentação

1. Encontre o remetente com [`GET /v1/sms/senders`](/docs/api/reference/list-workspace-sms-senders) ou [`GET /v1/sms/senders/{sender_id}`](/docs/api/reference/get-workspace-sms-sender). Se necessário, crie um com [`POST /v1/sms/senders`](/docs/api/reference/create-workspace-sms-sender).
2. Leia [`GET /v1/sms/senders/{sender_id}/requirements`](/docs/api/reference/list-workspace-sms-sender-requirements) para o destino e siga as etapas de `next`. Se for solicitado que você crie um registro, verifique o preço como em [Verifique os preços de registro e os fundos da carteira](#verifique-os-preços-de-registro-e-o-saldo-da-carteira) e, em seguida, chame [`POST /v1/sms/senders/{sender_id}/registrations`](/docs/api/reference/create-workspace-sms-sender-registration) com `country_code`.
3. Leia os requisitos do remetente novamente e guarde o `registration_id` (`scr_`) da linha como `REGISTRATION_ID` e o `program` dela como `PROGRAM`. Envie a documentação somente quando o `has_compliance_requirements` da linha for `true`. Quando for `false`, o registro não precisa de envio ou é gerenciado por um programa dedicado, então siga o `next` da linha. Programas dedicados, como a verificação de números toll-free e o 10DLC, têm etapas próprias.

A leitura de remetentes requer `sms_management:read`, e a criação de remetentes e registros requer `sms_management:write`. O envio da documentação também requer `compliance:write`.

## Envie a documentação do registro

Esta seção se aplica a um registro cujo `has_compliance_requirements` é `true`.

Leia o que o registro solicita com [`GET /v1/compliance/requirements`](/docs/api/reference/get-workspace-compliance-requirements), usando `sms_sender` como `subject_kind` e o registro como `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"
```

Os campos são lidos da mesma forma que para um número. [Leia o que o país solicita](/docs/guides/numbers/ownership-paperwork#read-what-the-country-asks-for) explica cada um deles, e [Envie cada documento](/docs/guides/numbers/ownership-paperwork#upload-each-document) trata dos arquivos solicitados por um campo `document`. Envie todas as respostas com [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission), indicando o registro como sujeito:

```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" }]
  }'
```

O exemplo mostra uma resposta. Envie uma entrada para cada campo cujo `required` seja `true` e para cada campo opcional para o qual você tenha uma resposta real, como explica [Envie todas as respostas](/docs/guides/numbers/ownership-paperwork#submit-every-answer). Uma resposta `201` retorna o envio. Guarde o `csb_` `id` dele. Um remetente não tem o campo `ownership`, então acompanhe a análise lendo o envio com [`GET /v1/compliance/submissions/{submission_id}`](/docs/api/reference/get-workspace-compliance-submission), cujas respostas trazem o `state` e, quando rejeitadas, um `reason`, ou lendo novamente os requisitos do remetente para ver o status do registro. Substitua as respostas rejeitadas com [`POST /v1/compliance/submissions/{submission_id}/resupply`](/docs/api/reference/update-workspace-compliance-submission), como mostra [Corrija uma resposta rejeitada](/docs/guides/numbers/ownership-paperwork#correct-a-rejected-answer).

## Próximos passos

- [Envie a documentação de propriedade de um número](/docs/guides/numbers/ownership-paperwork)
- [IDs de remetente 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)