Envie os ficheiros antes de os anexar
Envie os ficheiros de uma única categoria de comprovativo ou documento complementar e depois anexe os ID de ficheiro devolvidos através de create_proof ou create_supporting_document. O envio, por si só, não cria uma identidade, uma morada ou um comprovativo, nem conclui o registo de um número. Comece pelos requisitos atuais e pelos ID do catálogo.
Forneça exatamente um seletor: proof_type_id para um comprovativo de identidade ou morada, ou supporting_template_id para um documento complementar. Não envie ambos. Utilize os ID devolvidos pelo catálogo MultiTEL correspondente; trate-os como identificadores opacos.
Pedido de envio
Utilize uma conta da API MultiTEL ativada e o respetivo endereço IP autorizado. Os exemplos utilizam credenciais de autenticação básica HTTP provenientes de variáveis de ambiente; siga as convenções de autenticação do seu tipo de conta. Envie os pedidos através de HTTPS. Verifique tanto a resposta HTTP como o campo JSON status.code; os erros da aplicação podem chegar com HTTP 200. Os exemplos abaixo são fictícios.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--form-string "proof_type_id=$PROOF_TYPE_ID" \
--form-string 'description=Identity proof' \
--form 'files[0]=@./identity-proof.pdf' \
https://api.multitel.net/v3/create_encrypt_files| Campo | Significado |
|---|---|
files[0] … files[4] | De um a cinco ficheiros enviados. Utilize dados de formulário multiparte e deixe que o curl gere o delimitador de Content-Type. Estes campos contêm os bytes dos ficheiros, não URL nem dados Base64 em JSON. |
proof_type_id | Obrigatório para o envio de um comprovativo; utilize um ID de tipo de comprovativo devolvido. Omita supporting_template_id. |
supporting_template_id | Obrigatório em vez de proof_type_id para ficheiros complementares; utilize um ID de modelo devolvido. |
description | Descrição opcional fornecida por quem faz a chamada, com um máximo de 100 caracteres. Um envio de documentação complementar pode utilizar o nome do modelo quando a descrição é omitida. |
Limites dos ficheiros
Este controlador aceita, no máximo, cinco ficheiros e 20,000,000 bytes no total. Trata-se de um limite de bytes decimal, não de 20 MiB. A infraestrutura ou a validação MIME podem impor limites adicionais.
A lista de extensões permitidas é pdf, png, jpg, jpeg, gif, tiff, bmp, doc, docx, xls, xlsx, txt, rtf e csv. Uma extensão permitida não comprova que um ficheiro cumpre o requisito de registo selecionado. Em particular, tif não consta desta lista de extensões permitidas.
Verifique cada ficheiro devolvido
{
"status": {
"code": 200,
"msg": "Encrypt file has been created successfully"
},
"response": {
"entity_type": "identities",
"document_category": "proof",
"proof_type": "11111111111111111111111111111111",
"ids": [
{
"id": "22222222222222222222222222222222",
"name": "identity-proof.pdf",
"expired_at": "2026-10-23 16:20:00"
}
]
}
}Guarde cada response.ids[].id para o pedido de anexação. name identifica o nome do ficheiro de origem devolvido. Utilize nomes de ficheiro distintos e compare os ficheiros devolvidos com o conjunto esperado: um código 200 pode representar um lote processado com sucesso parcial. Não anexe um conjunto ao qual faltem ficheiros obrigatórios.
entity_type é identities ou addresses para um comprovativo, e supporting_documents para um envio de documentação complementar. document_category é proof ou supporting. O campo de resposta com o nome genérico proof_type também contém uma referência a um modelo para envios de documentação complementar; guarde o seu supporting_template_id original para a anexação.
Anexe os ficheiros sem demora
O serviço define a expiração para aproximadamente 20 minutos após o armazenamento local dos ficheiros enviados. A anexação verifica se o ficheiro pertence à mesma conta, não está marcado como expirado, ainda está dentro do prazo de validade e tem a categoria de entidade correta. expired_at não inclui um desvio de fuso horário nesta resposta; não presuma que está em UTC. Anexe os ficheiros sem demora em vez de agendar a operação para o momento limite.
A expiração da referência de envio não garante que todas as cópias armazenadas dos documentos sejam eliminadas nesse momento. O serviço cifra os ficheiros para o envio ao operador e conserva os bytes de origem para o fluxo de gestão documental; não o considere uma cifragem exclusivamente do lado do cliente nem um serviço sem retenção de dados. Não inclua ID, nomes de ficheiro nem respostas em registos públicos.
Erros e novas tentativas
O controlador atual utiliza o código de API 404 quando não são fornecidos ficheiros de documentos, e o código 500 para a validação da descrição, seletores em falta ou em conflito, ID de comprovativo ou modelo inválidos, o limite de número de ficheiros ou de tamanho total, problemas de armazenamento ou um envio sem sucesso. Leia status.msg; os dados de entrada inválidos nem sempre são representados pelo código 400.
Não é disponibilizada aqui nenhuma chave de idempotência do cliente. Se a resposta se perder, verifique o fluxo de gestão documental antes de repetir um envio; outro pedido pode criar novas referências de ficheiro. Estes exemplos não foram executados com documentos de identidade de clientes.