> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Sessões: Verificação KYC e KYB Unificada

> API de Sessões do Didit para KYC e KYB. Preços por utilização, inferência sub-2s, 220+ países, 14,000+ documentos, $10 gratuitos/mês.

As sessões são a unidade de verificação na Didit. Quando inicia uma verificação, é criada uma **sessão**; quando a verificação termina, a sessão contém o payload de decisão completo. A mesma API de sessões trata os dois tipos:

| Tipo | O que verifica | O payload de decisão inclui |
| - | - | - |
| **Sessão de Verificação de utilizadores (KYC)** | Uma pessoa individual | Verificação de identidade, prova de vida, correspondência facial, POA, NFC, validação de base de dados, telefone, e-mail, AML, questionários, Análise de dispositivo e IP |
| **Sessão de Verificação de empresas (KYB)** | Uma empresa / entidade jurídica | Verificação no registo de empresas, pessoas-chave (administradores/UBOs), verificações de documentos, telefone, e-mail, AML, questionários, Análise de dispositivo e IP |

Na lição da Academy sobre o que os utilizadores veem, o capítulo 5:34 compara o fluxo alojado com a criação de ecrãs próprios, que é exatamente o compromisso que esta API decide por si.

[Fluxo alojado ou criar os próprios ecrãs: Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=334\&rel=0\&playsinline=1)

## O tipo é determinado pelo fluxo

Quando [cria uma sessão](https://docs.didit.me/pt/sessions-api/create-session.md), passa um `workflow_id`. O tipo do fluxo determina se a sessão é de Verificação de utilizadores ou de Verificação de empresas; quem chama a API não escolhe separadamente. Os fluxos KYB criam sessões de Verificação de empresas; os fluxos KYC criam sessões de Verificação de utilizadores.

## Discriminador `session_kind`

Cada resposta de sessão (de criar, obter, listar, atualizar estado, partilhar e importar) inclui um campo de nível superior:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
```

* `"user"`: a sessão é uma **sessão de Verificação de utilizadores (KYC)**. A resposta contém arrays de funcionalidades específicos de utilizadores.
* `"business"`: a sessão é uma **sessão de Verificação de empresas (KYB)**. A resposta contém arrays de funcionalidades específicos de empresas.

Use este campo para determinar a estrutura da resposta no seu sistema.

> [!NOTE]
>
> Os valores do enum são os identificadores curtos `"user"` e `"business"`. Mantemo-los curtos para facilitar a utilização da API. Os nomes completos **Verificação de utilizadores (KYC)** e **Verificação de empresas (KYB)** são usados ao longo da documentação para maior clareza.

## Arrays de funcionalidades por tipo

Os arrays de funcionalidades presentes numa decisão dependem do tipo. Os campos que não existem num dos tipos simplesmente não aparecem na resposta desse tipo (sem valores nulos e sem marcadores de posição):

| Array de funcionalidades | Verificação de utilizadores (KYC) | Verificação de empresas (KYB) |
| - | :-: | :-: |
| `id_verifications` | ✅ | — |
| `liveness_checks` | ✅ | — |
| `face_matches` | ✅ | — |
| `nfc_verifications` | ✅ | — |
| `poa_verifications` | ✅ | — |
| `database_validations` | ✅ | — |
| `registry_checks` | — | ✅ |
| `document_verifications` | — | ✅ |
| `key_people_checks` | — | ✅ |
| `aml_screenings` | ✅ | ✅ |
| `phone_verifications` | ✅ | ✅ |
| `email_verifications` | ✅ | ✅ |
| `questionnaire_responses` | ✅ | ✅ |
| `ip_analyses` | ✅ | ✅ |
| `reviews` | ✅ | ✅ |
| `contact_details` | ✅ | ✅ |

## Campos de nível superior partilhados

Todas as sessões (dos dois tipos) incluem estes campos:

| Campo | Descrição |
| - | - |
| `session_id` | UUID da sessão |
| `session_kind` | `"user"` (Verificação de utilizadores / KYC) ou `"business"` (Verificação de empresas / KYB) |
| `session_number` | Número sequencial dentro da aplicação |
| `session_url` | URL da página de verificação alojada |
| `status` | Estado geral da sessão: `APPROVED`, `DECLINED`, `IN_REVIEW`, `IN_PROGRESS`, etc. |
| `workflow_id` | UUID do fluxo utilizado |
| `vendor_data` | O seu identificador para a entidade. [Saiba mais](https://docs.didit.me/pt/entities/vendor-data-linking.md) |
| `metadata` | JSON livre que anexou na criação |
| `callback` | URL de retorno opcional |
| `features` | Lista de funcionalidades separadas por vírgulas que o fluxo executa |
| `expected_details` | Payload opcional de dados esperados, para validação cruzada |
| `created_at`, `expires_at` | Datas e horas |

## Endpoints abrangidos

Os endpoints seguintes aceitam qualquer um dos tipos. Não existem caminhos `/v3/business-session/*` separados.

| Endpoint | Funciona para |
| - | - |
| [`POST /v3/session/`](https://docs.didit.me/pt/sessions-api/create-session) | Cria uma sessão de Verificação de utilizadores ou de Verificação de empresas, conforme o tipo de fluxo |
| [`GET /v3/session/{id}/decision/`](https://docs.didit.me/pt/sessions-api/retrieve-session) | Obtém qualquer um dos tipos; encaminha com base no `session_id` |
| [`GET /v3/sessions/`](https://docs.didit.me/pt/sessions-api/list-sessions) | Lista qualquer um dos tipos. Use o parâmetro de consulta `session_kind` para filtrar |
| [`PATCH /v3/session/{id}/update-status/`](https://docs.didit.me/pt/sessions-api/update-status) | Atualiza qualquer um dos tipos |
| [`DELETE /v3/session/{id}/delete/`](https://docs.didit.me/pt/sessions-api/delete-session) | Elimina qualquer um dos tipos |
| [`GET /v3/session/{id}/generate-pdf/`](https://docs.didit.me/pt/sessions-api/generate-pdf) | Gera um PDF para qualquer um dos tipos; encaminha para o modelo de Verificação de utilizadores ou de Verificação de empresas |
| [`POST /v3/session/{id}/share/`](https://docs.didit.me/pt/sessions-api/share-session/share) | O token de partilha inclui `session_kind` |
| [`POST /v3/session/import-shared/`](https://docs.didit.me/pt/sessions-api/share-session/import) | Importa qualquer um dos tipos; preserva o `session_kind` do token |

## Como funcionam as pesquisas

As sessões de Verificação de utilizadores e as de Verificação de empresas são dois tipos distintos. Os IDs usam UUID, pelo que colisões são impossíveis. Quando chama um endpoint com um `session_id`, a Didit:

1. Procura o ID primeiro na tabela de Verificação de utilizadores (cobre a maior parte do tráfego).
2. Recorre à tabela de Verificação de empresas se não o encontrar.
3. Devolve 404 se nenhuma das tabelas tiver correspondência.

Não precisa de indicar à API o tipo que procura.

## Os estados são idênticos

Os valores de estado são os mesmos nos dois tipos, e a API devolve-os exatamente como estão escritos aqui: `"Not Started"`, `"In Progress"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`, `"Expired"`, `"Kyc Expired"`, `"Resubmitted"`, `"Awaiting User"`. A comparação é exata e diferencia maiúsculas de minúsculas. Consulte [estados de verificação](https://docs.didit.me/pt/integration/verification-statuses.md) para a referência completa.

## Webhooks

Os eventos de webhook já incluem um campo `session_kind`, para que os seus manipuladores de webhook possam encaminhar cada evento consoante o tipo:

| Evento | Tipo | Dispara quando |
| - | - | - |
| `status.updated` | Ambos | O estado de uma sessão foi alterado. O payload inclui `session_kind: "user"` ou `"business"`. |
| `data.updated` | Ambos | Os dados de uma sessão foram alterados (resultados das funcionalidades, atualização do registo de empresas, monitorização AML contínua). O payload inclui `session_kind`. |
| `business.status.updated` / `business.data.updated` | Entidade empresarial | A entidade empresarial associada foi alterada. |
| `user.status.updated` / `user.data.updated` | Entidade de utilizador | A entidade de utilizador associada foi alterada. |

Consulte [webhooks](https://docs.didit.me/pt/integration/webhooks.md) para a verificação da assinatura e o comportamento das novas tentativas, e [webhooks KYB](https://docs.didit.me/pt/business-verification/webhooks.md) para o catálogo de eventos de Verificação de empresas (KYB).

## Próximos passos

> [card] [Criar sessão](https://docs.didit.me/pt/sessions-api/create-session.md)
>
> Inicie uma verificação: Verificação de utilizadores ou Verificação de empresas (KYB).

> [card] [Obter sessão](https://docs.didit.me/pt/sessions-api/retrieve-session.md)
>
> Obtenha a decisão. Funciona para os dois tipos.

> [card] [Listar sessões](https://docs.didit.me/pt/sessions-api/list-sessions.md)
>
> Filtre por `session_kind`.

> [card] [Atualizar estado](https://docs.didit.me/pt/sessions-api/update-status.md)
>
> Aprovar, recusar, analisar, reenviar.

> [card] [Gerar PDF](https://docs.didit.me/pt/sessions-api/generate-pdf.md)
>
> Relatórios PDF por tipo.

> [card] [Partilhar e importar](https://docs.didit.me/pt/sessions-api/share-session/overview.md)
>
> Transfira sessões entre aplicações.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.