Pular para o conteúdo principal
POST
curl

Visão geral

Use este endpoint quando você importar usuários de outro provedor e já tiver uma imagem facial confiável de cada pessoa. O usuário continua identificado pelo seu vendor_data, mas este endpoint de anexo ao perfil usa didit_internal_id para que o usuário de destino seja inequívoco.
Isso é diferente de Enviar rosto para uma lista. O envio ao perfil anexa um rosto a um usuário para fins de evidência, detecção de duplicatas e busca facial. O envio à lista adiciona um rosto a uma lista de bloqueio de faces para que futuras sessões de correspondência 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

Crie ou localize o usuário

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

Armazene o didit_internal_id

A resposta do usuário inclui didit_internal_id. Continue usando vendor_data no seu banco de dados; use didit_internal_id apenas nos endpoints de associação de perfil.
3

Envie o rosto

Envie uma imagem em base64 puro no campo image. O backend valida a decodificação da imagem, o tamanho da imagem e a detecção de rosto antes de salvá-la.

Exemplo

Corpo da requisição

Resposta

Validação e limites

  • Máximo de 5 rostos enviados manualmente por usuário.
  • O tamanho máximo da imagem após decodificação é de 2 MB.
  • A imagem deve estar em base64 válido e ser decodificada como imagem.
  • A imagem deve conter um rosto detectável. Sempre que possível, use um recorte frontal e bem iluminado do rosto.
  • O rosto enviado é indexado para futuras detecções de duplicatas e buscas faciais.
  • O rosto enviado não é adicionado automaticamente a uma lista de bloqueio.

Listar ou excluir rostos enviados

Liste os rostos do perfil:
Exclua um rosto do perfil:

Permissões

Use uma chave de API da mesma aplicação. A chave deve pertencer a uma aplicação autorizada a gerenciar o perfil do usuário de destino.

Modos de falha

  • 400: base64 inválido, imagem inválida, nenhum rosto detectável, imagem acima de 2 MB ou o usuário já tem 5 rostos enviados.
  • 401: credenciais ausentes ou inválidas.
  • 403: a chave de API é válida, mas não tem permissão para gerenciar este perfil de usuário.
  • 404: não existe usuário com esse didit_internal_id na aplicação.
  • 429: limite de requisições atingido; aguarde antes de tentar novamente, conforme Retry-After.

Conteúdo relacionado

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, 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á errada, 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 a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Parâmetros de caminho

organization_id
string<uuid>
obrigatório

UUID da organização proprietária da aplicação.

application_id
string<uuid>
obrigatório

UUID da aplicação à qual o perfil do Usuário pertence.

didit_internal_id
string<uuid>
obrigatório

UUID interno do usuário na Didit, retornado 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 bruta em JPG ou PNG codificada em base64. Não inclua o prefixo data:image/...;base64,. Tamanho máximo decodificado: 2 MB.

comment
string
padrão:""

Nota opcional visível para o operador sobre o rosto enviado.

Resposta

Rosto enviado e vinculado ao perfil do usuário.

uuid
string<uuid>
obrigatório

UUID do registro facial de usuário enviado.

image_url
string<uri> | null
obrigatório

URL assinada da imagem de rosto enviada.

comment
string | null
obrigatório

Comentário fornecido quando o rosto foi enviado.

uploaded_by
string | null
obrigatório

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

created_at
string<date-time>
obrigatório

Data e hora do upload.

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