> ## 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: estados de utilizadores e empresas

> Estados e transições das entidades Didit de utilizador e empresa: criação, verificação, ACTIVE/FLAGGED/BLOCKED e eliminação. Pagamento por chamada.

Todas as entidades de Utilizador e de Empresa na Didit percorrem um ciclo de vida previsível. Compreender este ciclo de vida é essencial para desenhar os seus fluxos de onboarding, de monitorização contínua e de 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: Manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## Estados em detalhe

| Estado | Significado | Medidas aplicadas |
| - | - | - |
| `ACTIVE` | Predefinido: a entidade está em boa situação | As novas sessões e transações são processadas pelos fluxos e regras configurados |
| `FLAGGED` | A entidade tem um problema pendente que requer revisão | As novas sessões continuam a ser executadas, mas ficam, por predefinição, como `IN_REVIEW`; as transações podem ser escaladas automaticamente, consoante as regras |
| `BLOCKED` | A entidade está bloqueada na sua plataforma | As novas sessões são recusadas automaticamente; as novas transações são recusadas automaticamente; não podem ser criadas novas ligações de sessão para este `vendor_data` |

> [!NOTE]
>
> A alteração do estado através de `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 a jusante possam reagir em tempo real.

## Fases do ciclo de vida

**1. Criação**

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

* **Criada automaticamente** quando inicia uma sessão com um novo `vendor_data`. A entidade é criada com o estado `ACTIVE`.
* **Pré-criada através da API** com `POST /v3/users/create/` ou `POST /v3/businesses/create/`. O estado é `ACTIVE` por predefinição.
* **Criada na consola** por um operador de conformidade: o estado começa em `ACTIVE`, a menos que o operador especifique outro.

Cada entidade recebe um `uuid` gerado pela Didit e um identificador `vendor_data` que pertence ao cliente.

**2. Verificação**

As sessões são associadas à entidade através de `vendor_data`. Cada sessão é executada no [fluxo](https://docs.didit.me/pt/console/workflows.md) configurado: verificação de identidade, prova de vida, correspondência facial, AML, documentos, consulta ao registo 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 estado mais recente de cada funcionalidade 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. Utilização ativa**

Quando uma entidade tiver uma ou mais sessões aprovadas, pode:

* **Submeter transações** que referenciem a entidade através de `vendor_data` no payload da transação
* **Executar monitorização AML contínua**: análises periódicas às listas de sanções, PEP e notícias adversas
* **Reverificar de forma programada**: 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 estado**

As alterações de estado de uma entidade acontecem de forma automática ou manual.

**Transições automáticas**

* `ACTIVE → FLAGGED` quando uma transação ultrapassa o limiar de revisão ou quando uma regra adiciona a entidade a uma lista de vigilância.
* `ACTIVE → BLOCKED` quando uma biometria facial corresponde a uma entrada da lista de bloqueio.

Uma sessão recusada não coloca a entidade na lista de bloqueio, pelo que o estado não é alterado. Incluir na lista de bloqueio um titular com sessão recusada é um passo manual: adicione a entrada na [página da lista de bloqueio](https://docs.didit.me/pt/console/blocklist-users.md) ou através da [API de listas](https://docs.didit.me/pt/management-api/lists/overview.md), e uma entrada `USER` (o `vendor_data`) define o estado como `BLOCKED`.

**Transições manuais** acontecem quando um analista altera o estado a partir da consola ou quando chama o endpoint `update-status`.

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

**5. Eliminação**

As entidades são eliminadas através de `POST /v3/users/delete/` ou `POST /v3/businesses/delete/` (em lote). O registo da entidade é removido de forma permanente. Eliminar um utilizador elimina também todos os [templates biométricos](https://docs.didit.me/pt/management-api/biometric-templates/overview.md) retidos para esse utilizador após a eliminação da sessão, para que a pessoa deixe de ser identificada como correspondência na deteção de duplicados e na Pesquisa facial.

As sessões de verificação não são abrangidas por estes endpoints, tal como as transações. Elimine as sessões com [Eliminar sessão](https://docs.didit.me/pt/sessions-api/delete-session.md) ou [Eliminar sessões em lote](https://docs.didit.me/pt/management-api/sessions/batch-delete.md); as transações são eliminadas a partir da consola.

## Marcas temporais de atividade

As entidades registam a atividade para ajudar a identificar perfis desatualizados ou ativos:

| Marca temporal | Atualizada quando |
| - | - |
| `first_session_at` | Foi criada a primeira sessão para esta entidade |
| `last_session_at` | A sessão mais recente foi criada ou atualizada |
| `last_activity_at` | Ocorreu qualquer alteração numa sessão, transação, estado ou perfil |

Use estas marcas temporais para filtrar entidades inativas, agendar reverificações ou acionar a monitorização contínua.

## Eventos emitidos durante o ciclo de vida

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

Consulte [webhooks de entidades](https://docs.didit.me/pt/entities/webhooks.md) para ver a estrutura dos payloads e a semântica de entrega.

## Próximos passos

> [card] [Associação de vendor\_data](https://docs.didit.me/pt/entities/vendor-data-linking.md)
>
> Como o `vendor_data` associa sessões, transações e entidades entre si.

> [card] [Operações de utilizadores](https://docs.didit.me/pt/entities/users/operations.md)
>
> Criar, atualizar, alterar o estado e eliminar entidades de Utilizador.

> [card] [Operações de empresas](https://docs.didit.me/pt/entities/businesses/operations.md)
>
> Criar, atualizar, alterar o estado e eliminar entidades de Empresa.


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