> ## 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 da Didit unifica KYC e KYB num endpoint. Pague por uso, inferência sub-2s, 220+ países, 14,000+ documentos, $10 de crédito grátis/mês.

As sessões são a unidade de verificação na Didit. Quando você inicia uma verificação, uma **sessão** é criada; quando a verificação termina, a sessão traz o payload completo da decisão. A mesma API de sessões atende aos dois tipos:

| Tipo | O que verifica | O payload da decisão inclui |
| - | - | - |
| **Sessão de Verificação de Usuário (KYC)** | Uma pessoa física | Verificação de identidade, prova de vida, correspondência facial, comprovante de endereço, NFC, validação de banco de dados, telefone, e-mail, AML, questionários, Análise de dispositivo e IP |
| **Sessão de Verificação de Empresas (KYB)** | Uma empresa / pessoa jurídica | Consulta ao registro de empresas, pessoas-chave (administradores/UBOs), verificações de documentos, telefone, e-mail, AML, questionários, Análise de dispositivo e IP |

Na aula da Academy sobre o que os usuários veem, o capítulo de 5:34 compara o fluxo hospedado com a criação das suas próprias telas, que é justamente a escolha que esta API faz por você.

[O fluxo hospedado vs criar suas próprias telas — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=334\&rel=0\&playsinline=1)

## O tipo é definido pelo fluxo de verificação

Ao [criar uma sessão](https://docs.didit.me/pt-br/sessions-api/create-session.md), você informa um `workflow_id`. O tipo do fluxo de verificação (workflow) define se a sessão é de Verificação de Usuário ou de Verificação de Empresas; quem chama a API não escolhe isso separadamente. Fluxos de KYB criam sessões de Verificação de Empresas; fluxos de KYC criam sessões de Verificação de Usuário.

## Discriminador `session_kind`

Toda resposta de sessão (de criação, consulta, listagem, atualização de status, compartilhamento e importação) 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 Usuário (KYC)**. A resposta contém arrays de recursos específicos do usuário.
* `"business"`: a sessão é uma **sessão de Verificação de Empresas (KYB)**. A resposta contém arrays de recursos específicos da empresa.

Use este campo para tratar o formato da resposta do seu lado.

> [!NOTE]
>
> Os valores do enum são os identificadores curtos `"user"` e `"business"`; eles são curtos para facilitar o uso da API. Os nomes completos **Verificação de Usuário (KYC)** e **Verificação de Empresas (KYB)** são usados em toda a documentação para maior clareza.

## Arrays de recursos por tipo

Os arrays de recursos presentes em uma decisão dependem do tipo. Campos que não existem em um tipo simplesmente não aparecem nessa resposta (sem nulos, sem valores de preenchimento):

| Array de recursos | Verificação de Usuário (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 compartilhados

Toda sessão (dos dois tipos) traz estes campos:

| Campo | Descrição |
| - | - |
| `session_id` | UUID da sessão |
| `session_kind` | `"user"` (Verificação de Usuário / 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 hospedada |
| `status` | Status geral da sessão: `APPROVED`, `DECLINED`, `IN_REVIEW`, `IN_PROGRESS` etc. |
| `workflow_id` | UUID do fluxo usado |
| `vendor_data` | O identificador que você atribuiu à entidade. [Saiba mais](https://docs.didit.me/pt-br/entities/vendor-data-linking.md) |
| `metadata` | JSON de formato livre que você anexou na criação |
| `callback` | URL de retorno opcional |
| `features` | Lista de recursos separados por vírgula executados pelo fluxo |
| `expected_details` | Payload opcional com os dados esperados para validação cruzada |
| `created_at`, `expires_at` | Carimbos de data e hora |

## Endpoints abrangidos

Todos os endpoints a seguir aceitam os dois tipos. Não há caminhos `/v3/business-session/*` separados.

| Endpoint | Funciona para |
| - | - |
| [`POST /v3/session/`](https://docs.didit.me/pt-br/sessions-api/create-session) | Cria uma sessão de Verificação de Usuário ou de Verificação de Empresas conforme o tipo do fluxo |
| [`GET /v3/session/{id}/decision/`](https://docs.didit.me/pt-br/sessions-api/retrieve-session) | Recupera qualquer um dos tipos, com base no `session_id` |
| [`GET /v3/sessions/`](https://docs.didit.me/pt-br/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-br/sessions-api/update-status) | Atualiza qualquer um dos tipos |
| [`DELETE /v3/session/{id}/delete/`](https://docs.didit.me/pt-br/sessions-api/delete-session) | Exclui qualquer um dos tipos |
| [`GET /v3/session/{id}/generate-pdf/`](https://docs.didit.me/pt-br/sessions-api/generate-pdf) | Gera um PDF para qualquer um dos tipos, usando o modelo de Verificação de Usuário ou de Verificação de Empresas |
| [`POST /v3/session/{id}/share/`](https://docs.didit.me/pt-br/sessions-api/share-session/share) | O token de compartilhamento inclui `session_kind` |
| [`POST /v3/session/import-shared/`](https://docs.didit.me/pt-br/sessions-api/share-session/import) | Importa qualquer um dos tipos e preserva o `session_kind` do token |

## Como funcionam as consultas

As sessões de Verificação de Usuário e de Verificação de Empresas são dois tipos distintos. Os IDs são UUIDs, então colisões são impossíveis. Quando você chama um endpoint com um `session_id`, a Didit:

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

Você nunca precisa informar à API qual tipo está procurando.

## Os status são idênticos

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

## Webhooks

Os eventos de webhook já trazem um campo `session_kind`, para que seus handlers de webhook possam direcionar o processamento conforme o tipo:

| Evento | Tipo | Disparado quando |
| - | - | - |
| `status.updated` | Ambos | O status de uma sessão mudou. O payload traz `session_kind: "user"` ou `"business"`. |
| `data.updated` | Ambos | Os dados de uma sessão mudaram (resultados de recursos, atualização do registro, AML contínuo). O payload traz `session_kind`. |
| `business.status.updated` / `business.data.updated` | Entidade Business | A entidade Business vinculada mudou. |
| `user.status.updated` / `user.data.updated` | Entidade User | A entidade User vinculada mudou. |

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

## Próximos passos

> [card] [Criar sessão](https://docs.didit.me/pt-br/sessions-api/create-session.md)
>
> Inicie uma verificação: Verificação de Usuários ou Verificação de Empresas.

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

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

> [card] [Atualizar status](https://docs.didit.me/pt-br/sessions-api/update-status.md)
>
> Aprove, recuse, envie para revisão ou solicite novo envio.

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

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


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