Envie a documentação de titularidade de um número

Alguns países exigem saber quem é o titular de um número antes que ele possa transportar tráfego. Até que essa documentação seja aceita e o registro do número seja concluído, o número fica alocado a você e é cobrado, mas seu status é pending_ownership_registration: ele não faz nem recebe chamadas de voz e não envia SMS. O número passa a transportar tráfego quando seu status é active e seu ownership.blocked_at é null. Você envia a documentação pelo painel ou com a API, e os dois caminhos usam os mesmos requisitos, as mesmas regras de análise e o mesmo processo de registro. O ownership.next do número indica cada etapa, inclusive quando enviar uma nova submissão.

As respostas que você envia são uma declaração legal feita em nome da sua empresa. Depois de aceitas, elas são repassadas à operadora ou ao órgão regulador daquele país sob o nome da empresa que descrevem. Por isso, confirme-as com o responsável por elas antes de enviar e não deixe que um processo automatizado envie respostas que ninguém verificou.

Antes de começar

• Para enviar pelo painel, sua função no espaço de trabalho precisa permitir a edição dos dados de conformidade. Sem essa permissão, o número mostra o status de titularidade, mas não exibe o botão de envio.
• Para enviar pelos endpoints de conformidade independentes, use uma chave de API com o escopo compliance no nível de escrita. Uma chave com nível de leitura pode consultar os requisitos e acompanhar a análise, mas não pode enviar. Para ler o número, também é preciso o escopo numbers no nível de leitura. No seletor de chaves do painel, compliance fica em Compliance.
• O identificador nda_ do número, obtido em GET /v1/numbers. Encontre um número na sua lista mostra como consultá-lo.

Os exemplos de API leem sua chave de BIRD_API_KEY, o host regional dela de BIRD_API_URL e o identificador do número de NUMBER_ID. Cada etapa seguinte indica a variável que define. Os comandos jq extraem um campo de uma resposta; se você não usa jq, leia o campo manualmente.

Verifique se um número precisa de documentação

Leia o número com GET /v1/numbers/{number_id}:

curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Guarde o country_code do número como COUNTRY_CODE; tanto a leitura de requisitos quanto o envio usam esse valor:

COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

ownership é null quando o país do número não exige documentação. Também é null quando não conseguimos ler o andamento da documentação e não há bloqueio registrado no número; nesse caso, leia o número novamente. Caso contrário, ele contém:

• status: needs_input significa que há respostas faltando ou que precisam de correção, under_review significa que suas respostas estão em análise, approval_pending significa que a documentação foi aceita e o registro ainda está pendente; chamadas e SMS de saída continuam bloqueados enquanto blocked_at estiver definido. approved significa que o registro foi aprovado, mas chamadas e SMS de saída continuam bloqueados enquanto blocked_at estiver definido. not_required significa que nada mais é exigido. rejected significa que o envio foi encerrado ou que um prazo de correção expirou, e ele não aceita mais correções. Entre em contato com o suporte para reabri-lo. unknown significa que não foi possível ler o status; leia o número novamente.
• next: as etapas que fazem a documentação avançar, em ordem. Uma etapa wait significa que nada é exigido de você no momento. Leia novamente após cada alteração.
• submission_id: o envio mais recente do número, quando houver um.
• blocked_at: quando o bloqueio por titularidade começou, ou null depois que ele é removido. O bloqueio impede chamadas de voz recebidas e efetuadas e SMS de saída.

O status de um número alocado explica como ownership se relaciona com o status do próprio número.

Enviar pelo painel

1. Abra o número na página Numbers. A linha Ownership mostra o status da documentação e as próximas etapas.
2. Quando o status for Details needed, selecione Update ownership details. O formulário Prove ownership of this number será aberto.
3. Escolha a empresa titular do número ou descreva uma nova, depois responda a cada item e envie os documentos solicitados. Os itens que oferecem um formulário em branco incluem um link para você baixá-lo, preenchê-lo e enviá-lo de volta.
4. Selecione Submit answers.

A linha Ownership passa para Under review. Se um revisor rejeitar uma resposta, a linha volta para Details needed: selecione Update ownership details novamente, corrija as respostas que o formulário indicar e selecione Update ownership details no final do formulário para enviá-las.

Se ainda não houver formulário para o país do número, a página do formulário exibe Ownership form unavailable. Entre em contato com o suporte para solicitá-lo para esse país.

Envie pela API

Para enviar pela API, leia o que o país exige, faça o upload de cada documento, envie todas as respostas de uma vez e depois leia o número para acompanhar a análise.

Leia o que o país exige

Leia os requisitos do número com GET /v1/compliance/requirements. Defina subject_kind como number, subject_id como o identificador nda_ do número e country_code como o COUNTRY_CODE do próprio número:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

A resposta informa o program sob o qual o número é registrado, que depende do tipo de número; guarde-o como PROGRAM. Ela lista em fields cada item a responder, na ordem em que devem ser apresentados. Para cada campo:

• key é a chave com que você envia a resposta.
• data_type indica como responder. Um campo document recebe um arquivo enviado por upload; todos os outros tipos recebem uma string, então um número é enviado como "1500" e um sim ou não como "true". Um campo enum aceita um dos seus options.
• required indica se a aprovação depende dele, e help_text descreve como é uma resposta válida.
• max_items é definido em um campo que aceita mais de uma resposta.
• template_url traz o link de um formulário em branco para baixar, preencher e enviar de volta por upload, quando o campo tiver um.
• state indica a situação do item: not_supplied antes de você responder e, depois, supplied, in_review, approved ou rejected, com o reason do revisor em um item rejeitado. Uma resposta aceita pode passar a indicar expired e precisar ser enviada novamente, e not_applicable marca um item que não se aplica a você.

submission_id é null até você enviar a documentação. needs_input é true enquanto algum item depender de você.

Um 422 com E19001 significa que ainda não temos formulário de titularidade para esse país. Entre em contato com o suporte para solicitá-lo.

Envie cada documento

Envie cada arquivo solicitado por um campo document com POST /v1/compliance/attachments, como um corpo multipart/form-data com os bytes em uma parte file. Guarde o id da resposta, o identificador tca_ do anexo, como ATTACHMENT_ID:

curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --form "file=@registration-certificate.pdf"

São aceitos arquivos PNG, JPEG e PDF de até 10 MB, e o tipo é identificado pelo conteúdo do arquivo. Uma resposta 201 retorna o novo anexo. Enviar o mesmo arquivo novamente retorna o primeiro anexo com 200, então tentar novamente um envio não cria um duplicado. Um anexo que nenhuma submissão cita expira após sete dias.

O download_url do anexo é um link assinado válido por 24 horas a partir do momento em que você obteve o anexo. Para obter um novo, liste seus anexos com GET /v1/compliance/attachments, ou baixe os bytes diretamente com GET /v1/compliance/attachments/{attachment_id}.

Envie todas as respostas

Envie as respostas com POST /v1/compliance/submissions. Inclua subject_kind e subject_id, o program informado na leitura de requisitos e o country_code do número. Em answers, envie uma entrada para cada campo cujo required é true e uma para cada campo opcional para o qual você tem uma resposta real; omita um campo opcional em vez de inventar um valor para ele. Um campo tipado recebe value, um campo de documento recebe attachment_id e um campo com max_items recebe values ou attachment_ids. Salve o corpo como submission.json, com seus valores no lugar de <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> e <ATTACHMENT_ID>. O exemplo mostra três das respostas que um formulário pede:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<ATTACHMENT_ID>" }
  ]
}

Envie-o com um Idempotency-Key. Reutilize a chave apenas para tentar novamente o mesmo corpo: uma rejeição pode ser retida e reproduzida, então, após um 422, corrija o corpo e envie-o com uma nova chave. Idempotência explica o que é retido.

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-$NUMBER_ID" \
  --data-binary @submission.json

Não há rascunhos: esta solicitação envia as respostas para revisão, então precisa conter todas as respostas obrigatórias. Se você omitir um campo obrigatório ou o formulário recusar uma resposta, a solicitação volta como 422 com E01001 e uma entrada em details por campo, identificado em param, e nada é enviado. Uma resposta 201 retorna a submissão com todas as respostas. Guarde o id, o identificador csb_ da submissão, como SUBMISSION_ID.

Uma empresa descrita pelo seu espaço de trabalho é uma identidade. Crie uma no Identity Center do painel ou com POST /v1/compliance/identities, enviando o name de exibição. Uma submissão de número também pode incluir um identity embutido em vez de um identity_id. O identity_id da resposta da submissão identifica a nova identidade, que POST /v1/compliance/identities retorna como id; reutilize-a para os próximos números em vez de criar outra. Para enviar a documentação em nome de uma identidade, adicione o identity_id dela, e as respostas que ela guarda preenchem as que você omitir. GET /v1/compliance/identities lista as identidades de empresa. As respostas de valor único que você envia são gravadas na identidade seja qual for a decisão da revisão, então a próxima submissão que a citar parte delas; documentos e respostas de vários valores são solicitados novamente a cada vez. Use uma identidade por empresa: se você envia documentação para vários clientes finais, dê a cada um sua própria identidade, caso contrário as respostas aprovadas de um cliente preenchem as de outro.

Acompanhe ownership.next em vez de enviar novamente. Um número tem uma submissão por versão do formulário do seu país, então enviar de novo enquanto essa submissão está aberta retorna 409 com E19009: corrija-a em vez disso, como mostra Corrigir uma resposta rejeitada. Quando reabrimos uma submissão encerrada após uma mudança no formulário, next solicita uma nova submissão para POST /v1/compliance/submissions.

Acompanhe a análise

Cada resposta é analisada individualmente. Leia o número novamente e verifique ownership.status e ownership.next, como em Verificar se um número precisa de documentação. Para ver como cada resposta foi avaliada, leia a submissão com GET /v1/compliance/submissions/{submission_id} ou leia os requisitos novamente: cada campo traz seu state e, quando rejeitado, seu reason.

Quando uma análise termina, enviamos o resultado por e-mail aos proprietários da sua organização e à última pessoa registrada que enviou ou corrigiu a submissão, quando houver. Um primeiro envio feito por chave API vai para os proprietários. Uma correção posterior feita por chave API mantém a pessoa registrada anteriormente como destinatária. Sua integração obtém o resultado lendo ownership.status.

Corrigir uma resposta rejeitada

Envie as respostas substitutas para POST /v1/compliance/submissions/{submission_id}/resupply. Inclua apenas as respostas que você está substituindo; as demais permanecem como estão. Obtenha o submission_id do ownership do número ou da leitura de requisitos:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-fix-1-$NUMBER_ID" \
  --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Uma resposta 200 retorna a submissão com suas substituições, que voltam para análise. Quando nenhuma resposta obrigatória estiver rejeitada, expirada ou ausente, o ownership.status do número volta a under_review. Substitua respostas cujo state seja rejected, expired ou not_supplied. Quando solicitamos uma correção depois de aceitar suas respostas, uma resposta cujo editable_for_verifier_repair seja true também pode ser substituída até essa correção ser encerrada. Uma resposta em qualquer outro estado, como uma ainda em análise ou aceita fora de uma correção que solicitamos, retorna 422 com E19003. Um documento substituto é um novo upload: faça o upload primeiro e envie o attachment_id dele.

Envie a documentação junto com o pedido de compra

Se você já sabe as respostas ao comprar o número, envie-as no bloco compliance do pedido de compra em POST /v1/numbers/orders, no mesmo formato de answers que a submissão usa. Para ler o que o país exige antes de ter o número, chame a leitura de requisitos sem subject_id, com COUNTRY_CODE e NUMBER_TYPE definidos como o country_code e o number_type do número em GET /v1/numbers/available:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Um pedido de compra com bloco compliance usa o escopo numbers já exigido pelo pedido, em nível de escrita.

Depois que o pedido de compra é aceito, ele é concluído de qualquer forma: se o envio no bloco compliance for recusado, o número continua sendo seu, e você envia a documentação com POST /v1/compliance/submissions como em Enviar todas as respostas. Quando as respostas são enviadas, o novo número mostra under_review com seu submission_id. Comprar e liberar um número trata do pedido de compra em si.

Reutilizar uma identidade de empresa

Use GET /v1/compliance/identities/{identity_id} para ler a empresa e as respostas salvas dela. As respostas salvas podem incluir um state de revisão, reason e decided_at; um valor sem decisão de revisão pode omitir o estado. Renomeie a empresa com PATCH /v1/compliance/identities/{identity_id} ou remova-a com DELETE /v1/compliance/identities/{identity_id}. As leituras exigem compliance:read; a criação, a renomeação e a exclusão exigem compliance:write.

Para verificar a própria empresa, crie primeiro a identidade. Leia os requisitos com subject_kind=identity, o identificador cid_ dela como subject_id, program=business e country_code=ZZ. Envie a documentação para essa mesma identidade. Uma identidade inline em um envio de número não substitui esse fluxo de verificação de identidade.

A revisão usa os dados da empresa, os contatos declarados e as evidências de verificação que você enviou. Enviar por uma chave API ou pelo dashboard não estabelece uma relação comercial diferente. Mantenha os dados de contato corretos e forneça as evidências solicitadas pelo formulário.

Enviar a documentação de um remetente SMS

A documentação de um remetente SMS usa as mesmas solicitações de requisitos, anexos, envio e correção, tendo o registro do remetente como objeto. Registrar um remetente SMS pela API explica como obter esse registro e consultar o preço antes.

Quando uma solicitação é recusada

Erros explica o corpo da resposta de erro e seu remediation.

Próximos passos

• Visão geral dos números
• Comprar e liberar um número
• Gerenciar seus números de telefone
• Migrar da Telserv para Bird