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

# Ciclo de vida de entidades: estados de usuário e empresa

> Estados e transições das entidades de usuário e empresa da Didit: criação, verificação, ACTIVE/FLAGGED/BLOCKED e exclusão. Pagamento por chamada.

Cada entidade de usuário e de empresa no Didit passa por um ciclo de vida previsível. Entender esse ciclo de vida é essencial para projetar seus fluxos de onboarding, monitoramento contínuo e remediação.

## Diagrama do ciclo de vida

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Session declined / manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## Status em detalhes

| Status | Significado | Efeito |
| - | - | - |
| `ACTIVE` | Padrão: a entidade está em situação regular | Novas sessões e transações passam pelos fluxos e regras que você configurou |
| `FLAGGED` | A entidade tem uma pendência que exige revisão | Novas sessões continuam sendo executadas, mas ficam por padrão em `IN_REVIEW`; transações podem ser escaladas automaticamente, dependendo das regras |
| `BLOCKED` | A entidade está bloqueada de acessar sua plataforma | Novas sessões são recusadas automaticamente; novas transações são recusadas automaticamente; nenhum novo link de sessão pode ser criado para este `vendor_data` |

> [!NOTE]
>
> Alterar o status via `PATCH /v3/users/{vendor_data}/update-status/` ou `PATCH /v3/businesses/{vendor_data}/update-status/` emite um webhook (`user.status.updated` / `business.status.updated`) para que os sistemas downstream possam reagir em tempo real.

## Fases do ciclo de vida

**1. Criação**

Uma entidade é criada de uma destas três formas:

* **Criada automaticamente** quando você inicia uma sessão com um novo `vendor_data`. A entidade é criada com o status `ACTIVE`.
* **Pré-criada via API** usando `POST /v3/users/create/` ou `POST /v3/businesses/create/`. O status padrão é `ACTIVE`.
* **Criada no console** por um operador de conformidade: o status começa como `ACTIVE`, a menos que o operador especifique outro.

Toda entidade recebe um `uuid` gerado pelo Didit e um identificador `vendor_data` de propriedade do cliente.

**2. Verificação**

As sessões são vinculadas à entidade via `vendor_data`. Cada sessão passa pelo [fluxo de verificação (workflow)](https://docs.didit.me/pt-br/console/workflows.md) que você configurou: verificação de identidade, prova de vida, correspondência facial, AML, documentos, consulta ao registro de empresas para KYB e assim por diante.

As sessões concluídas atualizam os contadores agregados da entidade:

* `session_count`, `approved_count`, `declined_count`, `in_review_count`
* Mapa `features`: o status mais recente de cada recurso em todas as sessões (por exemplo, `{ "id_verification": "APPROVED", "aml": "IN_REVIEW" }`)
* Os campos de perfil são propagados a partir da sessão aprovada mais recente (por exemplo, `full_name`, `date_of_birth`, `portrait_image`).

**3. Uso ativo**

Quando uma entidade tem uma ou mais sessões aprovadas, você pode:

* **Enviar transações** que fazem referência à entidade via `vendor_data` no payload da transação
* **Executar o monitoramento AML contínuo**: novas varreduras periódicas das listas de sanções, PEP e mídia adversa
* **Reverificar periodicamente**: criar novas sessões para o mesmo `vendor_data` em intervalos regulares
* **Agregar sinais de risco** de sessões e transações

**4. Transições de status**

As mudanças de status da entidade acontecem de forma automática ou manual.

**Transições automáticas**

* `ACTIVE → BLOCKED` quando uma sessão é `DECLINED` e seu fluxo está configurado para bloquear automaticamente.
* `ACTIVE → FLAGGED` quando uma transação ultrapassa o limiar de revisão ou uma regra adiciona a entidade a uma lista de monitoramento.
* `ACTIVE → BLOCKED` quando uma biometria facial corresponde a uma entrada da lista de bloqueio.

**Transições manuais** acontecem quando um analista altera o status pelo console ou quando você chama o endpoint `update-status`.

Toda transição emite um webhook `user.status.updated` ou `business.status.updated`.

**5. Exclusão**

As entidades são excluídas via `POST /v3/users/delete/` ou `POST /v3/businesses/delete/` (em lote). O registro da entidade é removido permanentemente. Excluir um usuário também elimina todos os [templates biométricos](https://docs.didit.me/pt-br/management-api/biometric-templates/overview.md) retidos para ele após a exclusão da sessão, de modo que a pessoa deixa de gerar correspondências na detecção de duplicatas e na Busca facial.

As sessões de verificação não são abrangidas por esses endpoints, nem as transações. Exclua sessões com [Excluir sessão](https://docs.didit.me/pt-br/sessions-api/delete-session.md) ou [Excluir sessões em lote](https://docs.didit.me/pt-br/management-api/sessions/batch-delete.md); as transações são excluídas pelo Console.

## Registros de data e hora de atividade

As entidades registram atividade para ajudar você a identificar perfis inativos ou ativos:

| Registro de data e hora | Atualizado quando |
| - | - |
| `first_session_at` | A primeira sessão foi criada para esta entidade |
| `last_session_at` | A sessão mais recente foi criada ou atualizada |
| `last_activity_at` | Ocorreu qualquer alteração, como uma sessão, transação, mudança de status ou atualização de perfil |

Use esses registros de data e hora para filtrar entidades inativas, agendar reverificações ou acionar o monitoramento contínuo.

## Eventos emitidos durante o ciclo de vida

| Fase do ciclo de vida | Webhooks emitidos |
| - | - |
| Criação (automática a partir da sessão) | `status.updated` (sessão), `user.data.updated` ou `business.data.updated` |
| Verificação | `status.updated` (sessão), `data.updated` |
| Mudança de status | `user.status.updated` ou `business.status.updated` |
| Transação enviada | `transaction.created` |
| Status da transação alterado | `transaction.status.updated` |

Consulte [webhooks de entidades](https://docs.didit.me/pt-br/entities/webhooks.md) para ver os formatos de payload e a semântica de entrega.

## Próximos passos

> [card] [Vinculação com vendor\_data](https://docs.didit.me/pt-br/entities/vendor-data-linking.md)
>
> Como o `vendor_data` conecta sessões, transações e entidades.

> [card] [Operações de usuários](https://docs.didit.me/pt-br/entities/users/operations.md)
>
> Crie, atualize, altere o status e exclua entidades de usuário.

> [card] [Operações de empresas](https://docs.didit.me/pt-br/entities/businesses/operations.md)
>
> Crie, atualize, altere o status e exclua entidades de empresa.


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