Enviar um perfil de registro para um número

Prepare o perfil salvo e o número

Use este fluxo de trabalho para associar um perfil de registro salvo a um número comprado e, para os números compatíveis que dependem de uma operadora, solicitar a análise do registro. Esta não é uma API de ativação geral para todos os provedores de números. Uma solicitação bem-sucedida não comprova que os documentos foram aprovados nem que o número está ativo.

Use uma conta habilitada da API MultiTEL por HTTPS, com suas credenciais e restrições de IP configuradas. Tanto o perfil não excluído quanto o número comprado e não anulado devem pertencer à sua conta.

Crie um perfil de registro ou selecione um existente. Guarde o uuid do perfil local obtido de create_document; get_document retorna a mesma referência local como id.
Para o envio à operadora, o perfil precisa das referências de identidade e endereço salvas. Anexe os comprovantes e os documentos de apoio exigidos por meio dos respectivos fluxos de trabalho antes do envio.
Verifique se o número e o perfil atendem aos requisitos aplicáveis ao país e ao número. Não presuma que um perfil salvo esteja aprovado para todos os números.

Envie a associação

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

O caminho contém o número de telefone comprado, não seu UUID, um ramal de PBX ou um identificador de identidade. O manipulador remove do número os caracteres que não são dígitos. Use o número internacional completo com o código do país. O exemplo é fictício e deve ser substituído pelo seu próprio número e pela referência do seu perfil local salvo.

Campos do envio de registro
Campo	Obrigatório	Significado
`document_uuid`	Sim	O uuid exato do perfil local salvo. Não use em seu lugar os identificadores remotos mascarados identity_id ou address_id, o identificador de um envio de arquivo ou um valor retornado de registration_details_id.
`service_description`	Não	Uma descrição do serviço pretendido, encaminhada para verificação pela operadora. Os espaços no início e no fim são removidos.
`onetime_files`	Depende do fluxo de trabalho	Uma matriz aceita para documentos de uso único da operadora. O manipulador atual remove os espaços no início e no fim de suas cadeias de caracteres e as encaminha sem resolver as referências locais dos envios de arquivos. A compatibilidade com os identificadores mascarados retornados por create_encrypt_files não foi estabelecida; consulte a limitação dos documentos de uso único abaixo antes de usar este campo.

Para solicitações multiparte, uma matriz usa campos onetime_files[] repetidos. Também é aceita uma solicitação JSON com Content-Type: application/json; suas propriedades são combinadas com os dados do formulário. Um campo number pode ser fornecido no corpo da solicitação quando o número é omitido do caminho. Prefira o caminho explícito mostrado acima para evitar ambiguidades.

Diferencie associação de aprovação

Leia tanto o resultado HTTP quanto o campo JSON status.code. Erros JSON podem chegar com HTTP 200. Um resultado bem-sucedido do envio à operadora retorna a mensagem Address verification task created; awaiting carrier review. Este exemplo usa referências fictícias.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

Os identificadores relacionados ao provedor são referências mascaradas, não identificadores intercambiáveis de perfis locais. document_uuid continua sendo a referência do perfil local que você enviou. No fluxo deste manipulador que recorre à operadora, registration_details_id é um hash adicional dessa referência local; não substitua document_uuid por ele em solicitações posteriores de perfil ou de envio.

Alguns números alocados usam a associação local de identidade em vez de criar uma verificação da operadora. Seu resultado bem-sucedido é Identity associated. com uma matriz response vazia. Isso não cria uma tarefa de análise da operadora nem comprova a aprovação. O portal tem um fluxo de associação mais recente cujo tratamento de provedores e cujas verificações de envios repetidos diferem dos deste ponto de acesso.

Trate os erros sem criar tarefas duplicadas

O código 400 da API indica a ausência do número ou da referência do perfil. O código 404 indica um perfil ou número indisponível para a conta ou um número ausente do inventário da operadora. O código 422 pode indicar referências de identidade ou endereço ausentes, requisitos do vendedor ou rejeição na validação da operadora. A ausência da configuração da chamada de retorno pode gerar o código 503, e uma falha de transporte durante a criação pode gerar o código 502. Leia a mensagem e qualquer requirement_diagnostics em vez de tratar todas as falhas da mesma forma.

O fluxo que recorre à operadora pode atualizar os indicadores locais de registro pendente antes que a validação de requisitos, as verificações da configuração da chamada de retorno ou a criação da tarefa terminem. Portanto, um erro não implica que o estado local permaneça inalterado, e um indicador de pendência por si só não comprova que uma tarefa existe. Não use esses indicadores como confirmação de aprovação ou de entrega da solicitação.

O provedor pode aceitar uma tarefa mesmo que uma operação posterior no banco de dados local falhe, e esta função auxiliar não verifica o resultado de todas as gravações locais antes de informar sucesso. Este manipulador não tem um parâmetro de idempotência do cliente nem proteção contra envios duplicados. Após o esgotamento do tempo de espera, um erro ou um resultado incerto, consulte o histórico de registro do número no portal ou entre em contato com o suporte antes de enviar novamente. A ausência de um registro local não comprova, por si só, que o provedor não recebeu nada.

Limitação dos documentos de uso único

O manipulador aceita onetime_files e encaminha cada cadeia de caracteres não vazia para o relacionamento de arquivos criptografados da operadora. Ele não consulta os registros de envios de arquivos da conta proprietária nem converte os identificadores externos mascarados desses envios em identificadores de arquivos do provedor. A auditoria sem conexão verificou o comportamento de encaminhamento, não se os arquivos foram anexados com sucesso na operadora.

Não presuma que um identificador de arquivo de create_encrypt_files possa ser copiado para este campo para concluir um fluxo de acordo de uso único. Use o portal ou confirme com a MultiTEL o fluxo de identificadores compatível quando um número exigir esses documentos. Este aspecto continua sem resolução na análise da API; não constitui um exemplo verificado de ponta a ponta.

Proteja as informações de registro

Envie apenas informações e documentos que você esteja autorizado a usar para o número. Mantenha as referências de perfil e verificação associadas à conta correta e evite gravar nos registros o conteúdo completo das solicitações de registro. Esta solicitação não exclui nem substitui todos os comprovantes ou verificações anteriores. A análise da operadora, a ativação e a retenção são processos separados.