Pular para o conteúdo principal
PATCH
curl

Suporte a KYC e KYB

Este endpoint funciona da mesma forma para sessões de Verificação de Usuário (KYC) e de Verificação de Empresas (KYB). A Didit localiza o session_id em ambos os tipos de sessão; a validação das transições de status é a mesma para ambos (o mesmo enum de status vale para os dois). A resposta traz apenas o session_id. Leia session_kind em Recuperar sessão quando sua lógica subsequente precisar considerar o tipo.

Transições permitidas

Você pode mover uma sessão para Approved, Declined ou Resubmitted. Qualquer outro new_status, incluindo In Review, retorna 400. O status atual da sessão precisa ser Approved, Declined, In Review, Kyc Expired, Abandoned ou Resubmitted; caso contrário, a API retorna 400. Definir Approved ou Declined em uma sessão que já tem esse status não tem efeito: a API retorna 200 e não altera nada, não dispara nenhum webhook e não envia nenhum e-mail. Definir Resubmitted em uma sessão que já está como Resubmitted retorna 400 (The new status is the same as the current status.). Um reenvio cujo nodes_to_resubmit contém apenas recursos exclusivos do backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) é executado automaticamente e devolve a sessão a um status que já recebeu uma decisão, sem nenhuma interação do usuário. Repetir um reenvio desse tipo em até 30 segundos retorna 429 Too Many Requests com um cabeçalho Retry-After, já que uma repetição imediata não pode produzir um resultado diferente. Não faça reenvios automáticos a partir de um handler de webhook sempre que receber um status In Review: primeiro analise o achado ou altere os dados subjacentes.

Visualize o e-mail antes

Com send_email: true, Approved e Declined enviam à pessoa o e-mail com a decisão, e Resubmitted envia a ela um novo link com os motivos. Você pode ver esse e-mail antes de alterar qualquer coisa:
  1. Chame Visualizar e-mail de decisão para Approved ou Declined, ou Visualizar e-mail de reenvio para Resubmitted.
  2. Confira o subject e o html renderizados, o recipient e will_be_sent / not_sent_reason.
  3. Chame este endpoint com o mesmo new_status (e, no caso de um reenvio, o mesmo nodes_to_resubmit), send_email: true, email_address definido como recipient, o email_language que você visualizou e email_preview_token definido como preview_token.
Nenhuma das visualizações altera a sessão ou envia algo. A atualização então envia exatamente o e-mail que você visualizou. O recibo expira após 15 minutos. Se o destinatário, o idioma, o status da sessão, o remetente ou o e-mail tiverem mudado desde a visualização, a atualização retorna 409 antes de qualquer alteração; visualize novamente e confirme com o novo comprovante. Enviar email_preview_token sem send_email: true retorna 400. A etapa de visualização é opcional: integrações existentes podem continuar chamando este endpoint sem ela.

Exemplos

Permissão

Requer o privilégio write:sessions. O mesmo privilégio abrange os dois tipos.

Relacionados

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

sessionId
string<uuid>
obrigatório

UUID da sessão de verificação a ser atualizada. Aceita IDs de sessão tanto de usuário (KYC) quanto de empresa (KYB): o serviço resolve o ID entre os dois tipos de sessão.

Exemplo:

"11111111-2222-3333-4444-555555555555"

Corpo

application/json
new_status
enum<string>
obrigatório

Status de destino. Approved e Declined registram uma decisão manual final (cada um também pode reverter o outro). Resubmitted limpa as etapas selecionadas e devolve a sessão ao usuário. Qualquer outro valor retorna 400.

Opções disponíveis:
Approved,
Declined,
Resubmitted
Exemplo:

"Approved"

comment
string

Motivo da alteração em texto livre, armazenado no histórico de revisão da sessão e retornado no array reviews de Get Decision. Por exemplo, Duplicated user.

Exemplo:

"All checks passed manual review"

nodes_to_resubmit
object[]

Etapas do fluxo que o usuário precisa refazer. Só é considerado quando new_status é Resubmitted. Para Approved/Declined, as entradas continuam sendo validadas pelo schema (um valor de feature inválido retorna 400), mas as entradas válidas no schema são ignoradas semanticamente. Se omitido, o servidor seleciona automaticamente as tentativas existentes de OCR, prova de vida, correspondência facial, comprovante de endereço, telefone, e-mail, AML, validação de banco de dados e questionário cujo status seja Declined, In Review, Not Finished ou Expired (tentativas de NFC, análise de IP, estimativa de idade, busca facial e documentos KYB nunca são selecionadas automaticamente; tentativas faciais que não sejam de correspondência facial são selecionadas como LIVENESS). Recursos que o usuário nunca tentou (sem tentativa registrada) NÃO são selecionados, portanto uma sessão sem nenhuma tentativa retorna 400 ("No features found that need resubmission") mesmo que nada tenha sido aprovado; nesse caso, envie nodes_to_resubmit explicitamente. As etapas são executadas na ordem do grafo do fluxo, independentemente da ordem em que você as enviar. KYB_REGISTRY, KYB_KEY_PEOPLE e o alias KYB são rejeitados com 400: essas verificações-pai são recalculadas a partir das sessões KYC filhas.

send_email
boolean
padrão:false

Se o usuário deve receber um e-mail sobre a alteração. Requer email_address. Para Approved/Declined, o usuário recebe uma notificação de status; para Resubmitted, o e-mail inclui o link de verificação e os motivos de reenvio de cada etapa.

Exemplo:

false

email_address
string<email>

Destinatário do e-mail de notificação. Obrigatório quando send_email é true — omiti-lo retorna 400.

Exemplo:

"user@example.com"

email_language
string
padrão:en

Idioma do e-mail de notificação. Aceita qualquer string no nível do schema; códigos não suportados passam a usar inglês (en) sem aviso.

Exemplo:

"en"

email_preview_token
string
write-only

Recibo opcional de Preview Decision Email (para Approved e Declined) ou de Preview Resubmission Email (para Resubmitted): seu preview_token. Válido apenas com send_email: true; sem isso, a requisição retorna 400. O destinatário, o idioma, o status da sessão, o remetente e o e-mail (e, no caso de um reenvio, as etapas selecionadas) ainda devem corresponder à pré-visualização, e o recibo expira após 15 minutos. Caso contrário, a requisição retorna 409 antes que a sessão seja alterada ou que um e-mail seja enviado. Integrações existentes podem omitir este campo.

Required string length: 1 - 512

Resposta

Status atualizado. A resposta contém apenas o session_id; obtenha a sessão atualizada via Get Decision. O webhook status.updated é disparado assim que a alteração é confirmada. Repetir Approved ou Declined retorna o mesmo corpo e não altera nada.

session_id
string<uuid>

UUID da sessão atualizada.

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