Pular para o conteúdo principal
PATCH
curl

O que isto faz

Uma sessão de verificação é composta por recursos individuais (etapas): ID/OCR, Prova de vida, Correspondência facial, AML, Comprovante de endereço, Telefone e assim por diante. Este endpoint permite definir o status de uma dessas etapas como Approved, Declined ou In Review. Use update-status quando quiser aprovar, recusar ou reabrir a sessão inteira. Use este endpoint quando quiser registrar uma decisão em apenas uma etapa, por exemplo para marcar a etapa de Correspondência facial como Declined no seu próprio fluxo de revisão. Uma sessão que já tem uma decisão a mantém: apenas a etapa muda. Se a sessão ainda não tem decisão e o fluxo de verificação (workflow) está aguardando exatamente esta etapa, aplicar a substituição conclui a etapa, como ocorreria se ela fosse concluída normalmente. O fluxo avança, as etapas seguintes são executadas, e um nó de status pode definir a decisão da sessão e disparar um webhook status.updated.

Como direcionar uma etapa com node_id

Em fluxos baseados em grafo, cada etapa tem um node_id (por exemplo feature_ocr_1, feature_liveness_1, feature_aml_1). Você encontra esses valores na decisão da sessão: cada recurso em uma decisão V3 traz o seu node_id. Em fluxos sem grafo (de etapa única), o recurso subjacente não tem ID de nó. Passe o valor literal default como nodeId para direcioná-lo. Como nenhuma etapa desse tipo de fluxo tem ID de nó, passe também feature_type (por exemplo LIVENESS, AML ou FACE_MATCH) para indicar a etapa desejada. Um feature_type desconhecido retorna 400.

Aguardar até que a pessoa conclua o fluxo

Por padrão, a sobreposição é aplicada imediatamente. Se a pessoa ainda estiver percorrendo o fluxo, isso altera uma etapa de um fluxo que ainda está em execução; nesse caso, a sobreposição é registrada com forced: true. Defina defer_until_flow_finishes: true para aguardar. Enquanto a sessão estiver Not Started, In Progress ou Resubmitted e a pessoa não tiver concluído, a sobreposição fica armazenada como pending_until_flow_finishes. Ela é aplicada quando a pessoa conclui o fluxo, depois que o fluxo chega à sua própria decisão. Em uma sessão cujo fluxo já terminou, ela é aplicada imediatamente em qualquer caso. Uma sobreposição em espera é cancelada em vez de aplicada quando:
  • a pessoa refaz a etapa antes de concluir (check_changed),
  • uma sobreposição mais recente na mesma etapa a substitui (replaced),
  • a sessão é encerrada sem que o fluxo seja concluído: abandonada, expirada ou decidida no meio do fluxo (session_closed),
  • você a cancela com Cancel Feature Override (cancelled_by_reviewer).
O override da resposta informa o que aconteceu: state é applied ou pending_until_flow_finishes, e applied_at é preenchido assim que a sobreposição é aplicada. O new_status de nível superior é o status armazenado da etapa, por isso permanece inalterado enquanto a sobreposição aguarda. Use List Feature Overrides para ver todas as sobreposições de uma sessão e se a pessoa ainda está no fluxo.

Suporte a KYC e KYB

Funciona da mesma forma para sessões de Verificação de Usuário (KYC) e Verificação de Empresas (KYB): a Didit localiza o sessionId nos dois tipos. Os tipos de etapa compatíveis incluem ID/OCR, Prova de vida, Correspondência facial, NFC, AML, Comprovante de endereço, Telefone, E-mail, Validação de banco de dados, Questionário e as verificações de registro, documentos e pessoas-chave do KYB.
Sessões de API independentes (criadas pelas APIs de verificação independentes, session_type = API) não permitem alterar o status de recursos individuais: o endpoint retorna 400.

Exemplos

O que acontece após uma atualização

  • Webhook: um evento data.updated é disparado quando a sobreposição é aplicada, imediatamente ou quando o fluxo termina. Nada é enviado enquanto ela aguarda nem quando é cancelada.
  • Atividade: toda sobreposição é registrada na atividade da sessão como FEATURE_OVERRIDE_PENDING, FEATURE_OVERRIDE_APPLIED ou FEATURE_OVERRIDE_CANCELLED, com o autor (chave de API, usuário ou o sistema, quando uma sobreposição em espera é aplicada). A entrada da requisição traz o seu comment como motivo. No array reviews da decisão da sessão, essas entradas aparecem com new_status: null, e a entrada da requisição tem o seu motivo em comment.
  • Decisão da sessão: uma sessão que já tem uma decisão a mantém. Para alterar a decisão final, chame update-status separadamente.

Permissão

Exige o privilégio write:sessions, usando uma chave de API de cliente (x-api-key) ou um cabeçalho de autorização de usuário. Uma chave de API com escopo precisa de acesso de escrita a decisões.

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. 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"

nodeId
string
obrigatório

ID do nó do grafo do fluxo do recurso a ser atualizado (por exemplo, feature_ocr_1). Use o valor literal default para fluxos sem grafo (de etapa única), nos quais o recurso não tem ID de nó.

Exemplo:

"feature_ocr_1"

Corpo

application/json
new_status
enum<string>
obrigatório

Status de destino para este recurso. Deve ser diferente do valor atual.

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

"Approved"

comment
string

Nota opcional em texto livre registrada no histórico de revisão da sessão para esta alteração de recurso.

Exemplo:

"Document manually verified by compliance."

feature_type
enum<string>

Qual tipo de etapa visar. Necessário em fluxos que não são de grafo (nodeId = default), em que as etapas não têm nó próprio; opcional nos demais casos. Um valor desconhecido retorna 400.

Opções disponíveis:
ID_VERIFICATION,
OCR,
OCR_BACK,
NFC,
LIVENESS,
FACE,
AGE_ESTIMATION,
AGE_VERIFICATION,
FACE_SEARCH,
FACE_MATCH,
IP_ANALYSIS,
AML,
PHONE,
PHONE_VERIFICATION,
EMAIL,
EMAIL_VERIFICATION,
POA,
PROOF_OF_ADDRESS,
DATABASE_VALIDATION,
DATA_VALIDATION,
QUESTIONNAIRE,
DOCUMENT_AI,
KYB_REGISTRY,
KYB_DOCUMENTS,
KYB_KEY_PEOPLE,
BANK_VERIFICATION,
GEOLOCATION
Exemplo:

"LIVENESS"

defer_until_flow_finishes
boolean
padrão:false

Enquanto a pessoa ainda estiver no fluxo, armazena a substituição como pending_until_flow_finishes e a aplica quando o fluxo terminar, em vez de imediatamente. Se omitido ou false, a substituição é aplicada imediatamente. Em uma sessão cujo fluxo já terminou, ela é aplicada imediatamente em qualquer caso.

Exemplo:

false

Resposta

A substituição foi registrada. new_status é o status da verificação conforme armazenado: o solicitado, depois que a substituição foi aplicada, ou o inalterado, enquanto ela aguarda a conclusão do fluxo. override indica o que aconteceu.

session_id
string<uuid>
obrigatório
node_id
string | null
obrigatório

O nó do fluxo da etapa atualizada, ou null para uma etapa sem nó (o caminho default em um fluxo que não é baseado em grafo).

Exemplo:

"feature_ocr_1"

feature_type
string
obrigatório

Nome do modelo do recurso atualizado (por exemplo, KYC, Face, FaceMatch, AML, POA).

Exemplo:

"KYC"

new_status
string
obrigatório

O status armazenado da verificação: o solicitado, depois que a substituição foi aplicada; o inalterado, enquanto a substituição aguarda a conclusão do fluxo.

Exemplo:

"Approved"

override
object
obrigatório

Uma substituição do status de uma verificação (recurso) feita com PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/: o que ela altera, se foi aplicada ou ainda aguarda a pessoa concluir o fluxo, quem a solicitou e por quê.

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