Saltar para o conteúdo principal
POST
curl

Visão geral

Utilize este endpoint quando importar utilizadores de outro fornecedor e já tiver uma imagem de rosto fiável para cada pessoa. O utilizador continua identificado pelo seu vendor_data, mas este endpoint para anexar o perfil usa didit_internal_id para que o utilizador de destino seja inequívoco.
Isto é diferente de Carregar rosto para a lista. O carregamento do perfil anexa um rosto a um utilizador para efeitos de prova, deteção de duplicados e pesquisa facial. O carregamento para lista acrescenta um rosto a uma lista de bloqueio de rostos, para que as sessões de correspondência futuras possam ser recusadas.

Endpoint

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

Fluxo de migração

1

Criar ou encontrar o utilizador

Chame POST /v3/users/create/ para um perfil novo, ou GET /v3/users/{vendor_data}/ para um perfil existente.
2

Guardar didit_internal_id

A resposta do utilizador inclui didit_internal_id. Continue a usar vendor_data na sua base de dados; use didit_internal_id apenas nos endpoints de anexação de perfil.
3

Carregar o rosto

Envie uma imagem em base64 sem prefixo no campo image. O back-end valida a descodificação da imagem, o tamanho da imagem e a deteção de rosto antes de a guardar.

Exemplo

Corpo do pedido

Resposta

Validação e limites

  • Máximo de 5 rostos carregados manualmente por utilizador.
  • O tamanho máximo da imagem após descodificação é de 2 MB.
  • A imagem tem de estar em base64 válido e ser descodificada como uma imagem.
  • A imagem tem de conter um rosto detetável. Sempre que possível, use um recorte frontal e bem iluminado do rosto.
  • O rosto carregado fica indexado para deteção futura de duplicados e pesquisa facial.
  • O rosto carregado não é adicionado automaticamente à lista de bloqueio.

Listar ou eliminar rostos carregados

Para listar os rostos do perfil:
Para eliminar um rosto do perfil:

Permissões

Utilize uma chave de API da mesma aplicação. A chave tem de pertencer a uma aplicação autorizada a gerir o perfil do utilizador de destino.

Modos de falha

  • 400: base64 inválido, imagem inválida, nenhum rosto detetável, imagem com mais de 2 MB ou o utilizador já tem 5 rostos carregados.
  • 401: credenciais em falta ou inválidas.
  • 403: a chave de API é válida, mas não tem permissão para gerir este perfil de utilizador.
  • 404: não existe nenhum utilizador com esse didit_internal_id na aplicação.
  • 429: limite de pedidos atingido; aguarde e tente novamente, usando Retry-After.

Relacionados

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Parâmetros de caminho

organization_id
string<uuid>
obrigatório

UUID da organização à qual pertence a aplicação.

application_id
string<uuid>
obrigatório

UUID da aplicação que detém o perfil de Utilizador.

didit_internal_id
string<uuid>
obrigatório

UUID interno de utilizador da Didit, devolvido como didit_internal_id por GET /v3/users/{vendor_data}/ e POST /v3/users/create/.

Corpo

application/json
image
string<byte>
obrigatório

Imagem facial em bruto codificada em base64 (JPG ou PNG). Não inclua o prefixo data:image/...;base64,. Tamanho máximo descodificado: 2 MB.

comment
string
padrão:""

Nota opcional, visível para o operador, sobre o rosto carregado.

Resposta

Rosto carregado e associado ao perfil do Utilizador.

uuid
string<uuid>
obrigatório

UUID do registo facial de utilizador carregado.

image_url
string<uri> | null
obrigatório

URL assinado para a imagem de rosto carregada.

comment
string | null
obrigatório

Comentário fornecido quando o rosto foi carregado.

uploaded_by
string | null
obrigatório

E-mail ou identificador do ator que fez o carregamento, quando disponível.

created_at
string<date-time>
obrigatório

Carimbo de data/hora do carregamento.

Última modificação em 7 de novembro de 2026