Criar um perfil de registo

Crie o perfil uma única vez

Este pedido cria um perfil de registo local juntamente com os registos de identidade e de morada no operador. Comece por consultar os países de registo, tipos de número e requisitos atuais. Os requisitos dependem do país e do tipo de número que pretende registar.

Uma resposta de criação bem-sucedida não constitui aprovação regulamentar nem ativação de número. Guarde separadamente o UUID do documento, o ID de identidade e o ID de morada: servem finalidades diferentes. Este pedido altera dados da conta e não é uma operação apenas de validação.

Pedido de criação

Autentique-se com a sua conta de API MultiTEL ativada e o respetivo endereço IP permitido. Os exemplos utilizam credenciais HTTP Basic guardadas em variáveis de ambiente. Verifique tanto a resposta HTTP como o campo JSON status.code; uma resposta HTTP 200 por si só não comprova o sucesso. Todos os valores de exemplo são fictícios.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --header 'Content-Type: application/json' \
  --data @registration-profile.json \
  https://api.multitel.net/v3/create_document

{
  "identity_type": "Personal",
  "first_name": "Example",
  "last_name": "Person",
  "phone_number": "12025550123",
  "email": "end-user@example.com",
  "city": "Example City",
  "postal_code": "00000",
  "country": "US",
  "address": "1 Example Street",
  "nationality": "US",
  "signature": "BASE64_PNG_OF_THE_AUTHORIZED_END_USER_SIGNATURE"
}

O JSON é um perfil Personal ilustrativo, não uma identidade real pronta a submeter. Substitua os respetivos dados e a assinatura pelas informações do utilizador final exigidas pelas regras de registo selecionadas. Também é aceite entrada codificada como formulário.

Campos do perfil de registo
Campo	Obrigatoriedade e formato
`identity_type`	Obrigatório. Utilize o valor exato Personal ou Business; a validação condicional depende das maiúsculas e minúsculas.
`first_name, last_name`	Obrigatórios, cada um com no máximo 64 caracteres. Para uma empresa, indique os dados do representante exigidos pelo país selecionado.
`phone_number`	Valor telefónico numérico obrigatório, com pelo menos oito caracteres. Um número internacional composto apenas por dígitos, incluindo o indicativo do país, é adequado para esta validação; trata-se de um número de contacto, não da compra de um número.
`city, postal_code, address`	Obrigatórios, cada um com no máximo 64 caracteres.
`country`	Código ISO obrigatório do país da morada, retirado do catálogo de registo. O serviço resolve-o para o registo de país do operador.
`signature`	Dados de assinatura obrigatórios. O portal atual fornece os bytes da imagem PNG em Base64 sem o prefixo data:image/png;base64,. Obtenha a assinatura do utilizador final através do seu fluxo de trabalho autorizado; um marcador de posição não vazio não constitui uma assinatura válida.
`nationality`	Obrigatório para Personal, como código ISO de país. Não o substitua por um UUID de país.
`company_name, incorporation_country`	Obrigatórios para Business. O nome da empresa tem no máximo 64 caracteres; incorporation_country é um código ISO de país.
`email`	E-mail de contacto opcional do utilizador final, com no máximo 254 caracteres. Um e-mail omitido ou vazio não herda o e-mail da conta base.
`company_reg_number, vat_id, id_number, personal_tax_id, birth_date, description`	Opcionais neste handler, mas o país/operador selecionado pode exigir alguns deles. Forneça os formatos exigidos para esse registo. As chamadas diretas à API não aplicam automaticamente todas as normalizações efetuadas pelo portal.

Este handler direto v3 exige os campos de morada e cria uma morada. Não presuma que a opção do portal para adiar a morada esteja disponível através dele.

Guarde os três identificadores

Segue-se uma seleção de campos da resposta; a resposta real contém também as informações do perfil submetidas e os dados da assinatura. Trate a resposta completa como privada.

{
  "status": {
    "code": 200,
    "msg": "Success Create Registration Detail."
  },
  "response": {
    "uuid": "11111111111111111111111111111111",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "country_iso": "US",
    "email": "end-user@example.com"
  }
}

response.uuid identifica o perfil local. Utilize-o com get_document. Nas respostas de documents e get_document, o mesmo identificador de perfil é designado id.
response.identity_id identifica a identidade para as posteriores provas de identidade e documentos de suporte.
response.address_id identifica a morada criada. Guarde-o separadamente; o UUID do perfil local não é um ID de morada. A compatibilidade da anexação posterior de provas de morada para perfis recém-criados continua em revisão.

Os dois endpoints de leitura do perfil não devolvem identity_id nem address_id, por isso guarde a resposta de criação bem-sucedida original. Se a tiver perdido, utilize a vista de documentos do portal ou contacte o suporte antes de criar um substituto.

Avançado: anexar provas pré-carregadas durante a criação

Pode fornecer identity_encryptfiles e address_encryptfiles como arrays de IDs devolvidos por create_encrypt_files. Carregue os ficheiros com um tipo de prova da categoria de entidade correspondente e submeta antes da expiração da referência de ficheiro, de cerca de 20 minutos. O handler de criação verifica a conta, a categoria e a expiração de cada referência fornecida.

Estes campos têm nomes diferentes do encrypted_file_ids do endpoint de anexação posterior. Durante a criação, cada ficheiro é enviado como um pedido de prova separado, mesmo quando vários ficheiros partilham o mesmo tipo de prova. Para uma prova de identidade que deva conter vários ficheiros em conjunto, utilize o pedido create_proof posterior com um único array. A criação bem-sucedida do perfil por si só não fornece resultados individuais de aprovação das provas.

Se uma prova de morada posterior for rejeitada para uma morada recém-criada, não substitua o UUID do perfil nem recrie a identidade repetidamente. Pare e verifique o perfil no portal ou junto do suporte. O caminho de leitura/consulta das provas de morada continua a ser uma limitação da revisão.

Falhas e criação parcial

O código 400 da API abrange a validação de campos, as falhas de criação no operador e as falhas de gravação local. Os erros de validação podem surgir como entradas indexadas por campo em response. O código 500 é utilizado para um país de registo indisponível ou inválido, e o código 404 para referências pré-carregadas em falta ou expiradas. Leia status.msg para além do código.

O perfil local e as operações a montante no operador não constituem uma única transação atómica. Um pedido falhado pode deixar estado a montante mesmo quando nenhum perfil local aparece na listagem. Não é exposta nenhuma chave de idempotência do cliente. Após um timeout ou uma falha incerta, inspecione os perfis existentes e contacte o suporte antes de repetir a criação; uma lista documents vazia não é prova de que nada foi criado a montante.