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 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. Uma chave API não consegue ler o faturamento da organização.

Os exemplos leem sua chave de BIRD_API_KEY, o host regional 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 e GET /v1/organization/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. 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:

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 ou GET /v1/sms/senders/{sender_id}. Se necessário, crie um com POST /v1/sms/senders.
2. Leia GET /v1/sms/senders/{sender_id}/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 e, em seguida, chame POST /v1/sms/senders/{sender_id}/registrations 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, usando sms_sender como subject_kind e o registro como 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"

Os campos são lidos da mesma forma que para um número. Leia o que o país solicita explica cada um deles, e Envie cada documento trata dos arquivos solicitados por um campo document. Envie todas as respostas com POST /v1/compliance/submissions, indicando o registro como sujeito:

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. 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}, 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, como mostra Corrija uma resposta rejeitada.

Próximos passos

• Envie a documentação de propriedade de um número
• IDs de remetente SMS