Saltar para o conteúdo principal
PATCH
curl

Suporte a KYC e KYB

Este endpoint funciona de forma idêntica para sessões de Verificação de utilizadores (KYC) e de Verificação de empresas (KYB). A Didit resolve o session_id nos dois tipos de sessão, e a validação das transições de estado é a mesma para ambos (o mesmo enum de estados se aplica a ambos). A resposta inclui apenas o session_id. Leia o session_kind a partir de Obter sessão quando a sua lógica a jusante precisar de distinguir o tipo.

Transições permitidas

Pode mover uma sessão para Approved, Declined ou Resubmitted. Qualquer outro new_status, incluindo In Review, devolve 400. O estado atual da sessão tem de ser Approved, Declined, In Review, Kyc Expired, Abandoned ou Resubmitted; caso contrário, a API devolve 400. Definir Approved ou Declined numa sessão que já tem esse estado é uma operação sem efeito: a API devolve 200, não altera nada, não dispara nenhum webhook e não envia nenhum e-mail. Definir Resubmitted numa sessão que já está Resubmitted devolve 400 (The new status is the same as the current status.). Um reenvio cujos nodes_to_resubmit contenham apenas funcionalidades exclusivas do backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) é executado automaticamente e devolve a sessão a um estado com decisão tomada, sem qualquer interação do utilizador. Repetir um reenvio desse tipo nos 30 segundos seguintes devolve 429 Too Many Requests com um cabeçalho Retry-After, uma vez que uma repetição imediata não pode produzir um resultado diferente. Não reenvie automaticamente a partir de um processador de webhook sempre que receber o estado In Review: primeiro analise o resultado ou altere os dados subjacentes.

Pré-visualizar o e-mail primeiro

Com send_email: true, Approved e Declined enviam à pessoa o e-mail de decisão, e Resubmitted envia-lhe uma nova ligação com os motivos. Pode ver esse e-mail antes de alterar qualquer coisa:
  1. Chame Pré-visualizar e-mail de decisão para Approved ou Declined, ou Pré-visualizar e-mail de reenvio para Resubmitted.
  2. Verifique o subject e o html renderizados, o recipient e o will_be_sent / not_sent_reason.
  3. Chame este endpoint com o mesmo new_status (e, no caso de um reenvio, os mesmos nodes_to_resubmit), send_email: true, email_address definido como recipient, o email_language que pré-visualizou e email_preview_token definido como preview_token.
Nenhuma das pré-visualizações altera a sessão nem envia qualquer coisa. A atualização envia então exatamente o e-mail que pré-visualizou. O recibo expira após 15 minutos. Se o destinatário, o idioma, o estado da sessão, o remetente ou o e-mail tiverem mudado desde a pré-visualização, a atualização devolve 409 antes de alterar seja o que for; pré-visualize de novo e confirme com o novo recibo. Enviar email_preview_token sem send_email: true devolve 400. O passo de pré-visualização é opcional: as integrações existentes podem continuar a chamar este endpoint sem ele.

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

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

sessionId
string<uuid>
obrigatório

UUID da sessão de verificação a atualizar. Aceita IDs de sessão de utilizador (KYC) e de empresa (KYB) — o serviço resolve o ID em ambos os tipos de sessão.

Exemplo:

"11111111-2222-3333-4444-555555555555"

Corpo

application/json
new_status
enum<string>
obrigatório

Estado de destino. Approved e Declined registam uma decisão manual final (cada uma também pode revogar a outra). Resubmitted limpa os passos selecionados e envia a sessão de volta ao utilizador. Qualquer outro valor devolve 400.

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

"Approved"

comment
string

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

Exemplo:

"All checks passed manual review"

nodes_to_resubmit
object[]

Passos do fluxo que o utilizador deve repetir. Apenas considerados quando new_status é Resubmitted. Para Approved/Declined, as entradas continuam a ser validadas pelo schema (um valor inválido de feature devolve 400), mas as entradas válidas no schema são semanticamente ignoradas. Se for omitido, o servidor seleciona automaticamente tentativas existentes de OCR, Prova de vida, Correspondência facial, Comprovativo de morada, Telefone, E-mail, AML, Validação de base de dados e Questionário cujo estado seja Declined, In Review, Not Finished ou Expired (tentativas de NFC, análise de IP, estimativa de idade, pesquisa facial e documentos KYB nunca são selecionadas automaticamente; tentativas faciais que não sejam de correspondência facial são selecionadas como LIVENESS) — funcionalidades que o utilizador nunca tentou (sem tentativa registada) NÃO são selecionadas, pelo que uma sessão com zero tentativas devolve 400 ("No features found that need resubmission"), mesmo que nada tenha sido aprovado; passe nodes_to_resubmit explicitamente nesse caso. Os passos são executados na ordem do grafo do fluxo, independentemente da ordem em que os envia. KYB_REGISTRY, KYB_KEY_PEOPLE e o alias KYB são rejeitados com 400 — essas verificações principais são recalculadas a partir das respetivas sessões KYC filhas.

send_email
boolean
padrão:false

Se deve ser enviado um e-mail ao utilizador sobre a alteração. Requer email_address. Para Approved/Declined, o utilizador recebe um aviso de estado; para Resubmitted, o e-mail inclui a ligação de verificação e os motivos de reenvio por passo.

Exemplo:

false

email_address
string<email>

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

Exemplo:

"user@example.com"

email_language
string
padrão:en

Idioma do e-mail de notificação. Aceita qualquer cadeia de caracteres ao nível do esquema; códigos não suportados revertem silenciosamente para inglês (en).

Exemplo:

"en"

email_preview_token
string
write-only

Recibo opcional de Pré-visualizar e-mail de decisão (para Approved e Declined) ou Pré-visualizar e-mail de nova submissão (para Resubmitted): o respetivo preview_token. Válido apenas com send_email: true; sem este, o pedido devolve 400. O destinatário, idioma, estado da sessão, remetente e e-mail (e, para uma nova submissão, os passos selecionados) têm de continuar a coincidir com a pré-visualização, e o recibo expira após 15 minutos. Caso contrário, o pedido devolve 409 antes de a sessão ser alterada ou de ser enviado um e-mail. As integrações existentes podem omitir este campo.

Required string length: 1 - 512

Resposta

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

session_id
string<uuid>

UUID da sessão atualizada.

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