--- title: "Envie a documentação de titularidade de um número" description: "Envie a documentação de titularidade que um país exige para um número de telefone, pelo painel ou com a API, acompanhe a análise e corrija as respostas rejeitadas." canonical: "https://bird.com/pt-br/documentacao/guides/numbers/ownership-paperwork" --- # 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](/docs/guides/authentication) 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`](/docs/api/reference/list-workspace-numbers). [Encontre um número na sua lista](/docs/guides/numbers/managing-numbers#find-a-number-in-your-list) mostra como consultá-lo. Os exemplos de API leem sua chave de `BIRD_API_KEY`, o [host regional](/docs/api/regions) 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}`](/docs/api/reference/get-workspace-number): ```bash 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: ```bash 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](/docs/guides/numbers/overview#the-status-of-an-allocated-number) 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**](https://bird.com/dashboard/w/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`](/docs/api/reference/get-workspace-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: ```bash 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`](/docs/api/errors/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`](/docs/api/reference/create-compliance-attachment), 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`: ```bash 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`](/docs/api/reference/list-compliance-attachments), ou baixe os bytes diretamente com [`GET /v1/compliance/attachments/{attachment_id}`](/docs/api/reference/get-compliance-attachment). ### Envie todas as respostas Envie as respostas com [`POST /v1/compliance/submissions`](/docs/api/reference/create-workspace-compliance-submission). 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 ``, ``, `` e ``. O exemplo mostra três das respostas que um formulário pede: ```json { "subject_kind": "number", "subject_id": "", "program": "", "country_code": "", "answers": [ { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" }, { "key": "business_registration_number", "value": "90012768" }, { "key": "business_registration_certificate", "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](/docs/guides/idempotency) explica o que é retido. ```bash 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`](/docs/api/errors/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`](/docs/api/reference/create-compliance-identity), 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`](/docs/api/reference/list-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`](/docs/api/errors/E19009): corrija-a em vez disso, como mostra [Corrigir uma resposta rejeitada](#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](#verifique-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}`](/docs/api/reference/get-workspace-compliance-submission) 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`](/docs/api/reference/update-workspace-compliance-submission). 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: ```bash 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`](/docs/api/errors/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`](/docs/api/reference/create-numbers-order), 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`](/docs/api/reference/list-available-numbers): ```bash 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](#envie-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](/docs/guides/numbers/buying-numbers) trata do pedido de compra em si. ## Reutilizar uma identidade de empresa Use [`GET /v1/compliance/identities/{identity_id}`](/docs/api/reference/get-compliance-identity) 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}`](/docs/api/reference/update-compliance-identity) ou remova-a com [`DELETE /v1/compliance/identities/{identity_id}`](/docs/api/reference/delete-compliance-identity). 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](/docs/guides/sms/sender-registration-api) explica como obter esse registro e consultar o preço antes. ## Quando uma solicitação é recusada | Resposta | O que significa | O que fazer | | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `403` com `E02035` | Em uma gravação de conformidade independente, a chave não tem o escopo `compliance` ou o tem apenas no nível de leitura. | Use uma chave com `compliance` no nível de gravação. | | `422` com `E19001` | Ainda não temos um formulário de titularidade para o país do número. | Entre em contato com o suporte para solicitar esse país. | | `422` com `E19013` | A leitura de requisitos não tinha `subject_id` nem `program`. | Envie o identificador `nda_` do número, ou `program` quando você ler antes de comprar. | | `422` com `E01001` | O envio omite um campo obrigatório ou contém uma resposta inválida. | Corrija cada campo indicado em `details` e envie o envio completo novamente com uma nova chave de idempotência. | | `409` com `E19009` | O número já tem um envio para o formulário atual. | Substitua as respostas necessárias com a solicitação de reenvio. | | `409` com `E01009` | A solicitação de reenvio se refere a um envio encerrado. | Entre em contato com o suporte. Se reabrirmos o envio, registre o que `ownership.next` indicar. | | `422` com `E19003` | Uma substituição se refere a uma resposta que está em análise ou que foi aceita fora de uma correção solicitada por nós. | Substitua apenas as respostas cujo `state` seja `rejected`, `expired` ou `not_supplied`. | | `404` com `E01008` | O número não está neste espaço de trabalho, ou `country_code` não é o país do número. | Envie o `country_code` informado por `GET /v1/numbers/{number_id}`. | [Erros](/docs/guides/errors) explica o corpo da resposta de erro e seu `remediation`. ## Próximos passos - [Visão geral dos números](/docs/guides/numbers/overview) - [Comprar e liberar um número](/docs/guides/numbers/buying-numbers) - [Gerenciar seus números de telefone](/docs/guides/numbers/managing-numbers) - [Migrar da Telserv para Bird](/docs/guides/numbers/migrate/telserv) ## Related resources - [What is a virtual phone number (VMN)?](/explained/numbers/what-is-a-virtual-phone-number) (answer) - [SMS numbers](/sms-api/features/numbers) (product) - [Number types](/docs/guides/numbers/number-types) (docs) [Get an implementation brief](/learn/workspace?topic=phone-numbers)