> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Encerrando a conta de um cliente
> Siga o fluxo de oito etapas para congelar, liquidar e arquivar a conta de um cliente entre Ledger e CRM, de acordo com os requisitos de encerramento de conta e auditoria do BACEN.
Para encerrar a conta de um cliente no Midaz, você trabalha em duas áreas: o **Ledger** (contas e saldos) e o **CRM** (titulares e instrumentos). As regras do BACEN tornam o encerramento de conta um evento regulado, então a ordem importa. Bloqueie novos créditos primeiro, depois liquide a atividade pendente e devolva os fundos remanescentes. Desative os registros subjacentes por último.
Este guia cobre o fluxo completo de encerramento, do [Titular](/pt/products/midaz/crm/holders) aos seus [Instrumentos](/pt/products/midaz/crm/alias-accounts). Você pode executar o fluxo de duas formas. **[Via API](#via-api)** fornece o endpoint, um payload de exemplo e a justificativa de compliance para cada etapa. **[Via Console](#via-console)** fornece as mesmas etapas como ações de apontar e clicar no Console Midaz.
Siga as etapas na ordem. Não feche contas nem arquive registros de CRM antes de zerar os saldos. O encerramento antecipado pode deixar fundos órfãos ou quebrar a trilha de auditoria que os relatórios regulatórios exigem.
## Visão geral
***
O fluxo de encerramento tem oito etapas, agrupadas em três fases:
| Fase | Etapas | Objetivo |
| :------------------------- | :----- | :------------------------------------------------------------------------------------- |
| **1. Congelar** | 1–2 | Marca o Titular como inativo e bloqueia novos créditos no nível do saldo. |
| **2. Liquidar e zerar** | 3–4 | Limpa a atividade pendente e devolve os fundos remanescentes ao cliente. |
| **3. Encerrar e arquivar** | 5–8 | Desativa as Contas do Ledger e arquiva os registros de CRM sob a política de retenção. |
Ao longo deste guia, `{organization_id}` e `{ledger_id}` identificam a Organização e o Ledger do Midaz que possuem as contas. Este guia abrevia os caminhos para `/v1/.../accounts/{accountId}` para facilitar a leitura.
## Pré-requisitos
***
Antes de começar, confirme que você tem:
* O `holderId` do cliente a ser desligado.
* Os valores de `accountId` vinculados a esse Titular em cada Ledger da Organização. Recupere-os com `GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts`; a resposta é paginada, então recupere todas as páginas. Adicione o parâmetro de consulta opcional `ledger_id` apenas quando precisar restringir a lista a um único Ledger.
* O `instrument_id` de cada Instrumento, mapeado ao `accountId` correspondente. Liste os instrumentos do Titular com `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` (também paginado) e use o campo `accountId` de cada instrumento para mapeá-lo à Conta do Ledger. As Etapas 6 e 7 têm como alvo esses valores de `instrument_id`.
* Confirmação da sua equipe de compliance de que você pode encerrar o relacionamento com o cliente (sem retenções legais, disputas em aberto ou exigências regulatórias pendentes).
* Credenciais de API apropriadas com permissão para modificar titulares, instrumentos, saldos e contas. As Etapas 6 e 7 atualizam e excluem instrumentos, então as credenciais devem ter acesso `patch` e `delete` no recurso `instruments`.
O encerramento de conta é irreversível do ponto de vista do cliente. Antes de prosseguir, confirme que não há produtos ativos ou obrigações em aberto.
Via API
***
Execute o fluxo completo de encerramento de forma programática. Cada etapa lista o endpoint, um payload de exemplo e a justificativa de compliance.
### Etapa 1: Congelar o Titular
Marque o Titular como inativo para registrar o encerramento em todos os seus sistemas. Atualize o Titular e defina o campo `status` do seu perfil de pessoa como um valor inativo.
```http theme={null}
PATCH /v2/organizations/{organization_id}/holders/{holder_id}
```
```json theme={null}
{
"naturalPerson": {
"status": "INACTIVE"
}
}
```
Marcar o Titular como inativo é uma mudança de registro, não uma exclusão. O registro do Titular permanece totalmente legível para auditoria. Esse status não bloqueia novos créditos por si só: a Etapa 2 bloqueia as entradas no nível do saldo. Para uma pessoa jurídica, defina `legalPerson.status` em vez disso.
Etapa 2: Bloquear créditos nas contas
Para cada conta vinculada ao Titular, impeça a entrada de novos fundos. Primeiro, liste os [Saldos](/pt/products/midaz/balances) da conta. Depois, atualize cada saldo para desativar o recebimento.
**Recupere os saldos da conta:**
```http theme={null}
GET /v1/.../accounts/{accountId}/balances
```
**Para cada `balanceId` retornado, bloqueie a entrada de fundos:**
```http theme={null}
PATCH /v1/.../balances/{balanceId}
```
```json theme={null}
{
"allowReceiving": false
}
```
Repita esta etapa para **todos** os `balanceId` de **todas** as contas pertencentes ao Titular. Um único saldo deixado aberto ainda pode receber créditos e bloquear o encerramento mais tarde.
Quando você define `allowReceiving` como `false`, o saldo bloqueia novas entradas, mas continua permitindo saídas. É exatamente isso que você precisa na Etapa 4 para devolver o saldo remanescente ao cliente. Para detalhes sobre os flags de permissão, veja [Saldos](/pt/products/midaz/balances).
### Etapa 3: Liquidar a atividade pendente
Antes de zerar um saldo, a conta não pode ter movimentações em andamento.
* **Verifique transações em processamento.** Confirme que a conta não tem transações pendentes ou não confirmadas. Confirme ou cancele conforme apropriado usando [Confirmar uma transação pendente](/pt/reference/products/midaz/v2/commit-transaction) ou [Cancelar uma transação pendente](/pt/reference/products/midaz/v2/cancel-transaction).
Se você pular esta etapa, uma conta encerrada pode receber lançamentos tardios. Lançamentos tardios quebram a conciliação e a trilha de auditoria do BACEN.
### Etapa 4: Zerar o saldo
Devolva quaisquer fundos remanescentes ao cliente (o titular da conta) e confirme `available = 0` e `onHold = 0` em todos os saldos.
* Registre uma **transação de devolução** que move o valor `available` remanescente de cada conta do cliente para o destino designado do titular (por exemplo, uma conta de liquidação externa). Use [Criar uma transação](/pt/reference/products/midaz/v1/create-transaction-json).
* **Confirme `available = 0` e `onHold = 0`** em todos os saldos de todas as contas do Ledger antes de prosseguir. Você pode verificar isso com [Recuperar saldos por conta](/pt/reference/products/midaz/v2/get-all-balances-by-account-id).
O Midaz **não permite excluir uma conta que ainda tenha saldo**. Todos os saldos devem estar zerados antes da Etapa 5.
### Etapa 5: Encerrar as Contas do Ledger no Midaz
Depois de zerar os saldos e liquidar a atividade pendente, exclua cada Conta do Ledger.
```http theme={null}
DELETE /v1/.../accounts/{accountId}
```
Uma solicitação bem-sucedida retorna `204 No Content`. Repita para cada conta vinculada ao Titular. Veja [Excluir uma conta](/pt/reference/products/midaz/v2/delete-account) para o contrato completo.
Excluir uma Conta do Ledger é uma remoção lógica. A conta e suas operações históricas permanecem disponíveis para auditoria e relatórios, sujeitas à sua política de retenção.
### Etapa 6: Registrar a data de encerramento no instrumento
Registre a data oficial de encerramento no Instrumento do Titular para que o CRM e quaisquer exportações regulatórias reflitam quando o relacionamento terminou.
```http theme={null}
PATCH /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
```json theme={null}
{
"bankingDetails": {
"closingDate": "2026-06-09"
}
}
```
O campo `closingDate` fica no objeto `bankingDetails` do Instrumento e usa o formato `YYYY-MM-DD`. Veja [Instrumentos](/pt/products/midaz/crm/alias-accounts) para a referência completa dos campos. Os relatórios de ciclo de vida de conta do BACEN precisam de uma data de encerramento precisa.
### Etapa 7: Arquivar os instrumentos no CRM
Arquive cada Instrumento no CRM. Use uma **soft delete**. Isso remove o registro do uso ativo, mas o mantém pelo período de retenção regulatória.
```http theme={null}
DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```
**Não** passe `hard_delete=true`. Um encerramento regulado deve arquivar (soft-delete) o registro e mantê-lo. Ele não deve apagar o registro permanentemente. Veja [Excluir um instrumento](/pt/reference/products/midaz/v2/delete-instrument).
### Etapa 8: Arquivar o Titular no CRM
Depois de arquivar todos os seus instrumentos, arquive o próprio Titular com uma soft delete.
```http theme={null}
DELETE /v2/organizations/{organization_id}/holders/{holder_id}
```
Como na Etapa 7, omita `hard_delete=true`. Mantenha o registro do Titular sob a política de retenção aplicável para auditoria e inspeção regulatória. Veja [Excluir um titular](/pt/reference/products/midaz/v2/delete-holder).
Via Console
***
Execute o mesmo fluxo de encerramento de oito etapas a partir do [Midaz Console](/pt/products/midaz/console/midaz-module). O Console cobre a maior parte do fluxo por apontar e clicar, mas o bloqueio de créditos (Etapa 2) ainda exige a API. Cada etapa abaixo indica a etapa equivalente da API nesta página.
A ordem é a mesma do fluxo da API. Não exclua contas nem arquive registros de CRM antes de zerar os saldos.
### Etapa 1: Congelar o Titular
Marque o Titular como inativo para registrar o encerramento. Isso é uma mudança de registro e não bloqueia novos créditos por si só.
Na página **Titulares**, encontre o Titular a encerrar.
Clique nos três pontos () na coluna **Ações** e selecione **Editar**.
No formulário do Titular, defina o **Status** como **Inativo**.
Confirme a atualização.
Marcar o Titular como inativo é uma mudança de registro, não uma exclusão. O registro permanece totalmente legível para auditoria. Isso não bloqueia novos créditos por si só: a Etapa 2 bloqueia as entradas no nível do saldo. Veja [Editando um Titular](/pt/products/midaz/console/crm-editing-a-holder).
### Etapa 2: Bloquear créditos nas contas
**Esta etapa exige a API. O Console não permite editar os flags de saldo depois que a conta é criada.** O Console permite definir `allowReceiving` apenas ao criar uma Conta pela primeira vez, não ao editar um saldo existente. Use a API para desativar o recebimento em cada saldo.
Siga a [Etapa 2: Bloquear créditos nas contas](#step-2-block-credits-on-the-accounts) na seção Via API.
Para cada conta vinculada ao Titular, use a API para definir `allowReceiving` como `false` em todos os `balanceId`. Isso bloqueia novas entradas enquanto as saídas permanecem disponíveis para a transação de devolução na Etapa 4.
### Etapa 3: Liquidar a atividade pendente
Confirme que não há movimentações em andamento antes de zerar qualquer saldo.
Na página **Transações**, filtre pelas contas vinculadas ao Titular. Confirme que a conta não tem transações pendentes ou não confirmadas, e confirme ou cancele as que estiverem em andamento.
Revise as transações pendentes e confirme ou cancele conforme apropriado.
### Etapa 4: Zerar o saldo
Devolva os fundos remanescentes ao cliente e confirme `available = 0` e `onHold = 0` em todos os saldos.
Na página **Transações**, clique em **Nova Transação**. Crie uma **transação de devolução** que move o valor `available` remanescente de cada conta do cliente para o destino designado do titular, por exemplo, uma conta de liquidação externa. Veja [Criando uma Transação](/pt/products/midaz/console/creating-a-transaction).
Abra cada conta e confirme **available = 0** e **onHold = 0** antes de continuar.
O Midaz **não permite excluir uma conta que ainda tenha saldo**. Todos os saldos devem estar zerados antes da Etapa 5.
### Etapa 5: Encerrar as Contas do Ledger no Midaz
Depois de zerar os saldos e liquidar a atividade pendente, exclua cada Conta do Ledger.
Na página **Contas**, encontre a Conta vinculada ao Titular, clique nos três pontos () na coluna **Ações** e selecione **Excluir**.
Uma caixa de diálogo de confirmação aparecerá. Clique em **Confirmar** para finalizar a exclusão.
Repita para cada conta vinculada ao Titular.
Excluir uma Conta do Ledger é uma remoção lógica. A conta e suas operações históricas permanecem disponíveis para auditoria e relatórios, sujeitas à sua política de retenção. Veja [Excluindo uma Conta](/pt/products/midaz/console/deleting-an-account).
### Etapa 6: Registrar a data de encerramento no instrumento
Registre a data oficial de encerramento no Instrumento do Titular para que o CRM e as exportações regulatórias reflitam quando o relacionamento terminou.
Na página **Instrumentos**, encontre o instrumento a atualizar, clique nos três pontos () na coluna **Ações** e selecione **Editar**.
No formulário do Instrumento, defina a **Data de Encerramento** (em `bankingDetails`) para a data oficial de encerramento usando o formato `YYYY-MM-DD`.
Confirme a atualização.
Os relatórios de ciclo de vida de conta do BACEN precisam de uma data de encerramento precisa. Veja [Editando um Instrumento](/pt/products/midaz/console/crm-editing-alias-account).
### Etapa 7: Arquivar os instrumentos no CRM
Arquive cada Instrumento com uma **soft delete**. Isso remove o registro do uso ativo, mas o mantém pelo período de retenção regulatória.
Na página **Instrumentos**, encontre o instrumento a arquivar, clique nos três pontos () na coluna **Ações** e selecione **Excluir**.
Uma caixa de diálogo de confirmação aparecerá. Clique em **Confirmar** para finalizar.
Use a exclusão padrão (soft delete). Ela arquiva e mantém o registro em vez de apagá-lo permanentemente. Em deploys regulados, o Midaz mantém o registro subjacente pelo período de retenção. Veja [Excluindo um Instrumento](/pt/products/midaz/console/crm-deleting-alias-account).
### Etapa 8: Arquivar o Titular no CRM
Depois de arquivar todos os seus instrumentos, arquive o próprio Titular com uma **soft delete**.
Na página **Titulares**, encontre o Titular a arquivar, clique nos três pontos () na coluna **Ações** e selecione **Excluir**.
Uma caixa de diálogo de confirmação aparecerá. Clique em **Confirmar** para finalizar.
Use **Soft Delete** (o padrão), não Hard Delete. Mantenha o registro do Titular sob a política de retenção aplicável para auditoria e inspeção regulatória. Veja [Excluindo um Titular](/pt/products/midaz/console/crm-deleting-a-holder).
## Notas de compliance do BACEN
***
* **A ordem é obrigatória.** Congele primeiro (Etapas 1–2), depois liquide e zere (Etapas 3–4). Essa ordem impede que fundos entrem em uma conta que está em processo de encerramento.
* **Devolva os fundos antes de encerrar.** Devolva qualquer saldo residual ao cliente e confirme `available = 0` e `onHold = 0` antes de excluir uma conta. O Midaz bloqueia o encerramento de uma conta que possui fundos, e esse encerramento também violaria a compliance.
* **Arquive, não apague.** Uma soft delete (sem `hard_delete`) mantém Titulares e instrumentos disponíveis pelo período de retenção regulatória. A exclusão permanente removeria evidências que as auditorias do BACEN precisam.
* **Registre a data de encerramento.** O `closingDate` no instrumento fornece aos reguladores um registro de data e hora oficial de quando o relacionamento terminou.
* **Preserve a trilha de auditoria.** O Midaz remove Contas do Ledger e operações de forma lógica. Elas permanecem consultáveis para conciliação e relatórios.
Trate as oito etapas como uma única transação do ponto de vista de compliance. Se qualquer etapa falhar, pause e resolva antes de continuar. Não deixe o cliente em um estado parcialmente encerrado.