API de atualização de dados de sessão: corrigir KYC e KYB

Por vezes, o OCR lê mal um documento de identificação, uma fatura de serviços públicos ou um registo de empresa. A Didit disponibiliza três endpoints PATCH que pode chamar para corrigir os dados extraídos sem ter de repetir toda a verificação.

Endpoint	Utilizar quando
`PATCH /v3/session/{id}/update-data/`	Corrigir valores extraídos de um documento de identificação numa sessão de Verificação de utilizadores (KYC)
`PATCH /v3/session/{id}/update-poa-data/`	Corrigir valores extraídos de uma fatura de serviços públicos, extrato bancário ou contrato de arrendamento numa sessão de Verificação de utilizadores (KYC)
`PATCH /v3/session/{id}/kyb/{company_uuid}/update-data/`	Corrigir campos extraídos do registo numa sessão de Verificação de empresas (KYB)
`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`	Isentar uma parte de Pessoas-chave da verificação quando já não consegue concluir a sua própria verificação

Todos os quatro aceitam a sua chave de API de cliente ou um cabeçalho de autorização de utilizador, e todos os quatro enviam um webhook data.updated em caso de sucesso, para que o seu sistema e as análises subsequentes se mantenham sincronizados.

Requisitos comuns

Autorização: chave de API de cliente (x-api-key / Authorization bearer padrão) ou token de autenticação de utilizador.
Privilégio:
- KYC e POA: write:sessions
- Empresa KYB e parte de Pessoas-chave: write:businesses
Estado da sessão (apenas KYC / POA): tem de ser um de APPROVED, DECLINED, IN_REVIEW ou KYC_EXPIRED. As sessões que ainda não atingiram um estado passível de revisão não podem ser corrigidas. As atualizações dos dados da empresa KYB não têm restrição de estado.
O registo da funcionalidade tem de existir: só pode corrigir campos KYC se a sessão tiver capturado um KYC, campos POA se tiver capturado um POA, e campos da empresa KYB se a sessão tiver uma verificação de registo.
Atualizações parciais: só são alterados os campos que incluir. Omita um campo para o manter como está. Envie null para limpar uma chave de extra_fields.
Webhooks: uma atualização bem-sucedida dispara data.updated com session_kind: "user" ou "business", e o registo de auditoria da sessão regista quais os campos específicos que foram alterados e quem os alterou.

Atualizar dados de identidade KYC

PATCH /v3/session/{sessionId}/update-data/ Corrija qualquer campo extraído do documento de identificação. Suporta fluxos com várias instâncias baseados em grafo, através do parâmetro de consulta opcional node_id ou de um campo no corpo do pedido: indique um registo KYC específico quando uma única sessão tiver vários passos KYC.

Campos modificáveis

Campo	Notas
`document_type`	Código ISO do documento: `P` (passaporte), `ID`, `DL`, `RP`.
`document_number`	O número do documento impresso.
`personal_number`	Número pessoal / de identificação fiscal, quando impresso no documento.
`date_of_birth`	Data ISO 8601.
`date_of_issue` / `expiration_date`	Datas ISO 8601.
`issuing_state`	País emissor, ISO 3166-1 alpha-3.
`first_name` / `last_name`	`full_name` é recalculado automaticamente a partir destes dois.
`gender`	`M`, `F` ou `X`, quando presente.
`nationality`	Texto livre.
`marital_status`	Texto livre.
`place_of_birth`	Texto livre.
`address`	Morada em texto livre, tal como consta do documento. Aciona nova geocodificação.
`parsed_address`	Morada estruturada: ver a forma aninhada abaixo.
`extra_fields`	Campos adicionais arbitrários do documento de identificação (por exemplo, `blood_group`, `municipality`). Envie `null` para uma chave a remover.

parsed_address aceita apenas estas chaves aninhadas: address_type, city, region, street_1, street_2, postal_code, country (ISO 3166-1 alpha-2).

Exemplo

curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "issuing_state": "ESP",
    "extra_fields": { "municipality": "Madrid" }
  }'

Para um fluxo de grafo com várias instâncias, acrescente ?node_id=feature_ocr_2 ao URL (ou envie "node_id": "feature_ocr_2" no corpo) para indicar um registo KYC específico.

Atualizar dados do comprovativo de morada (POA)

PATCH /v3/session/{sessionId}/update-poa-data/ Corrija campos extraídos de um comprovativo de morada. Aplicam-se as mesmas restrições de estado e o mesmo privilégio das atualizações KYC. Também suporta node_id para fluxos com várias instâncias.

Campos modificáveis

Campo	Notas
`issuing_state`	País que emitiu o documento, ISO 3166-1 alpha-3.
`document_type`	Por exemplo, `utility_bill`, `bank_statement`, `lease_agreement`.
`document_language`	Idioma ISO 639-1 do documento.
`issuer`	Empresa de serviços públicos, banco, senhorio, etc.
`issue_date`	Data ISO 8601.
`poa_address`	Morada tal como impressa no documento (texto livre). Aciona nova geocodificação.
`name_on_document`	Nome completo impresso no documento.
`poa_parsed_address`	Morada estruturada, com a mesma estrutura aninhada que `parsed_address` do KYC.
`extra_fields`	Campos específicos do documento: dados bancários (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names` (lista ou `null`).

Exemplo

curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-poa-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "utility_bill",
    "issuer": "Iberdrola",
    "issue_date": "2026-03-15",
    "name_on_document": "Jane Doe",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    }
  }'

Atualizar dados de empresa KYB

PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/ Corrija campos extraídos do registo de uma empresa KYB. O endpoint edita tanto as colunas canónicas da empresa como registry_data, para que a vista “Extraído do registo” na consola reflita as suas correções. user_provided_data (o que o utilizador final confirmou no fluxo alojado) não é alterado. last_console_edit_at é marcado com a data e hora, e é disparado um webhook data.updated com trigger: "console_registry_edit".

Requisitos

Privilégio: write:businesses (diferente do privilégio de KYC / POA).
O companyUuid no URL tem de pertencer ao sessionId indicado; caso contrário, recebe uma resposta 404.
Sem restrição de estado da sessão: os dados da empresa KYB podem ser corrigidos a qualquer momento.

Campos alteráveis

Campo	Notas
`company_name`	Nome jurídico.
`registration_number`	Número de registo oficial.
`country_code`	País de constituição, ISO 3166-1 alpha-3.
`incorporation_date` / `registration_date` / `dissolution_date`	Datas em ISO 8601.
`tax_number`	Número de identificação fiscal.
`legal_address`	Alias de `registered_address`: é guardado na coluna canónica `registered_address`.
`company_type`	Ltd / LLC / PLC / SA / GmbH / SL etc.
`registry_status`	`active`, `dissolved`, `struck_off`, `inactive`, etc.
`verification_status`	`verified`, `failed`, `unknown`.
`alternative_names`	Nomes comerciais, nomes anteriores, DBAs.
`nature_of_business`	Descrição breve.
`registered_capital`	Capital autorizado / emitido.
`website`, `email`, `phone`	Dados de contacto.
`legal_entity_identifier`	LEI.
`location_of_registration`	Cidade / subdivisão.
`control_scheme`	Esquema de governação, quando o registo o disponibiliza.

Qualquer campo omitido fica inalterado. Qualquer campo enviado é guardado na coluna canónica (quando existe) e integrado em registry_data. As datas são serializadas como strings ISO 8601 quando integradas em registry_data.

Exemplo

curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/f7a9c1b2-4e6d.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "registry_status": "active",
    "legal_address": "1 Main Street, London EC1A 1AA, United Kingdom",
    "alternative_names": "Acme Ltd, Acme Group"
  }'

Resposta: o objeto completo da empresa KYB, com a mesma estrutura de registry_checks[].company na decisão da sessão.

Ignorar uma parte de pessoas-chave

PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/ Isenta uma parte de pessoas-chave da verificação. É a via de exceção para uma parte que nunca consegue concluir a sua própria verificação. A causa habitual é uma sessão filha eliminada: depois de a sessão KYC individual atribuída a um UBO ou administrador ser eliminada, o seu estado fica congelado e nunca se resolve, pelo que a KYB não tem nada que a possa tirar de Awaiting User. Ao ignorar a parte, esta sai da agregação de pessoas-chave, a verificação é recalculada de imediato e a sessão pode ser concluída e aprovada ou recusada.

Requisitos

Privilégio: write:businesses.
O partyUuid no URL tem de pertencer ao sessionId indicado; caso contrário, recebe uma resposta 404.
Não condicionado por allow_skip. Essa definição da função limita o que o candidato pode ignorar ao preencher o ecrã alojado de pessoas-chave. Este endpoint permite a substituição feita pelo operador, pelo que funciona mesmo em funções em que o candidato não poderia ter ignorado a parte.

Corpo

Campo	Tipo	Notas
`is_skipped`	boolean	`true` isenta a parte; `false` volta a incluí-la no âmbito e a verificação volta a aguardar por ela.

requires_verification fica deliberadamente inalterado, pelo que uma parte isenta aparece com requires_verification: true e is_skipped: true. O registo continua a mostrar que as regras exigiam uma verificação.

Exemplo

curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/parties/0a3f1e2c-7c2f.../" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_skipped": true }'

Resposta: a parte atualizada, com a mesma estrutura de uma entrada de key_people_checks[].submitted.parties[] na decisão da sessão. É disparado um webhook data.updated com trigger: "console_key_people_skip".

Uma parte cuja sessão filha foi eliminada é assinalada no payload da decisão com kyc_session_deleted: true (ou kyb_sub_session_deleted: true para partes empresariais), e o seu kyc_session_url / kyb_sub_session_url é devolvido como null, porque a ligação já não funciona. Eliminar uma sessão filha nunca aprova, por si só, a parte. A verificação de pessoas-chave passa para In Review para que uma pessoa tome a decisão.

O que acontece após uma atualização

Webhook: data.updated é disparado na sessão, com o session_kind da sessão no payload ("user" ou "business"). Subscreva uma vez ao nível do destino e encaminhe com base em session_kind.
Registo de auditoria: a sessão regista exatamente os campos alterados, os valores anteriores e novos e (nas chamadas com autenticação de utilizador) o e-mail do ator. Visível no separador Eventos da consola.
Nova geocodificação da morada: para atualizações de KYC e POA que alterem address / poa_address, a Didit volta a executar a geocodificação em segundo plano. As falhas são ignoradas, pelo que a atualização nunca falha por causa de um problema de geocodificação.
Reavaliação AML: atualizações de KYC que alterem nome, data de nascimento ou nacionalidade podem voltar a disparar a triagem AML, se a triagem AML ainda não tiver terminado na sessão. Os resultados aparecem na decisão da sessão.

Quando não usar estes endpoints

Repetir toda a verificação: se o cliente tiver de voltar a tirar a fotografia do documento de identificação ou a carregar um documento, use update-status para mover a sessão para Resubmitted.
Alterar dados de perfil da entidade User ou Business: use PATCH /v3/users/{vendor_data}/ ou PATCH /v3/businesses/{vendor_data}/. Estes endpoints atualizam dados ao nível da entidade, não dados ao nível da sessão.
Editar dados de pessoas-chave: não existe nenhuma API pública para alterar o nome, as funções ou a propriedade de uma parte. Esses dados são submetidos através do fluxo alojado. O único campo que pode ser alterado por PATCH é is_skipped (ver Ignorar uma parte de pessoas-chave).

Erros

Estado	Significado
`401`	Credenciais em falta ou inválidas.
`403`	O autor do pedido não tem o privilégio necessário (`write:sessions` ou `write:businesses`).
`404`	Sessão não encontrada, ou a sessão não contém o registo que está a atualizar (sem KYC, sem POA, sem empresa correspondente, sem parte correspondente ou com uma parte que pertence a outra sessão).
`400`	Erro de validação: código de país inválido, chave `parsed_address` desconhecida, `extra_fields` que não é um objeto, etc.

Próximos passos

Obter sessão

Obter a decisão completa para ver os campos atualizados.

Atualizar estado

Aprovar, recusar ou reabrir uma sessão após uma correção de dados.

Webhooks

Subscrever os eventos data.updated.

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

​Requisitos comuns

​Atualizar dados de identidade KYC

​Campos modificáveis

​Exemplo

​Atualizar dados do comprovativo de morada (POA)

​Campos modificáveis

​Exemplo

​Atualizar dados de empresa KYB

​Requisitos

​Campos alteráveis

​Exemplo

​Ignorar uma parte de pessoas-chave

​Requisitos

​Corpo

​Exemplo

​O que acontece após uma atualização

​Quando não usar estes endpoints

​Erros

​Próximos passos

Obter sessão

Atualizar estado

Webhooks

Requisitos comuns

Atualizar dados de identidade KYC

Campos modificáveis

Exemplo

Atualizar dados do comprovativo de morada (POA)

Campos modificáveis

Exemplo

Atualizar dados de empresa KYB

Requisitos

Campos alteráveis

Exemplo

Ignorar uma parte de pessoas-chave

Requisitos

Corpo

Exemplo

O que acontece após uma atualização

Quando não usar estes endpoints

Erros

Próximos passos