> ## 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, encerrar 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. Em seguida, encerre cada conta. A operação de encerramento recusa uma conta que ainda tem fundos. Arquive os registros de CRM por último. Este guia cobre o fluxo completo de encerramento, do [Titular](https://docs.lerian.studio/pt/products/midaz/crm/holders.md) aos seus [Instrumentos](https://docs.lerian.studio/pt/products/midaz/crm/alias-accounts.md). 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. > [!WARNING] > > Siga as etapas na ordem. Não arquive registros de CRM antes de encerrar as contas. ## 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 | Encerra as Contas do Ledger e arquiva os registros de CRM sob a política de retenção. | > [!NOTE] > > 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}` e `/v2/.../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. A Etapa 5 tem 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. A Etapa 5 atualiza instrumentos, então as credenciais devem ter acesso `patch` no recurso `instruments`. As Etapas 6 e 7 exigem acesso `post` e `delete` no recurso `accounts`. > [!WARNING] > > O encerramento de uma conta não pode ser desfeito. 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" } } ``` > [!NOTE] > > 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](https://docs.lerian.studio/pt/products/midaz/balances.md) da conta. Depois, atualize cada saldo para desativar o recebimento. Se um saldo tiver `overdraftUsed` diferente de zero, quite-o antes: um saldo que recusa entradas também recusa o pagamento. **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 } ``` > [!WARNING] > > 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. > [!TIP] > > 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](https://docs.lerian.studio/pt/products/midaz/balances.md). ### 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](https://docs.lerian.studio/pt/reference/products/midaz/v2/commit-transaction.md) ou [Cancelar uma transação pendente](https://docs.lerian.studio/pt/reference/products/midaz/v2/cancel-transaction.md). > [!WARNING] > > A operação de encerramento da Etapa 6 recusa uma conta cujos fundos uma transação pendente ainda retém. ### Etapa 4: Zerar o saldo Devolva quaisquer fundos remanescentes ao cliente (o titular da conta) e confirme `available = 0`, `onHold = 0` e `overdraftUsed = 0` em todos os saldos. * Se um saldo deve [dívida de tarifa](https://docs.lerian.studio/pt/products/midaz/fees/fee-debt.md), liquide-a antes com [Cobrar dívidas de tarifa em aberto](https://docs.lerian.studio/pt/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts.md). A operação de encerramento recusa um saldo que deve dívida de tarifa (`0527`). * 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](https://docs.lerian.studio/pt/reference/products/midaz/v1/create-transaction-json.md). * **Confirme `available = 0`, `onHold = 0` e `overdraftUsed = 0`** em todos os saldos de todas as contas do Ledger antes de prosseguir. Você pode verificar isso com [Recuperar saldos por conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-all-balances-by-account-id.md). > [!WARNING] > > A operação de encerramento recusa uma conta com qualquer saldo cujo valor `available`, `onHold` ou `overdraftUsed` não seja exatamente zero. ### Etapa 5: 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. Faça isso antes de excluir a conta na Etapa 7. Depois da exclusão, o Midaz responde a uma atualização do Instrumento com não encontrado. ```http theme={null} PATCH /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id} ``` ```json theme={null} { "bankingDetails": { "closingDate": "2026-06-09" } } ``` > [!NOTE] > > O campo `closingDate` fica no objeto `bankingDetails` do Instrumento e usa o formato `YYYY-MM-DD`. Veja [Instrumentos](https://docs.lerian.studio/pt/products/midaz/crm/alias-accounts.md) 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 6: Encerrar as Contas do Ledger no Midaz Depois de zerar os saldos e liquidar a atividade pendente, encerre cada Conta do Ledger. ```http theme={null} POST /v2/.../accounts/{accountId}/close ``` A requisição não tem corpo. Uma requisição bem-sucedida retorna `204 No Content`, e cada leitura posterior da conta mostra o instante do encerramento em `closedAt`. Repita para cada conta vinculada ao Titular. Veja [Encerrar uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/close-account.md) para o contrato completo e a [lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md) para cada recusa. > [!NOTE] > > O Midaz recusa qualquer movimentação posterior em uma conta encerrada, e desbloquear a conta não a reabre. Uma conta externa não pode ser encerrada. ### Etapa 7: Excluir as Contas do Ledger Exclua cada conta encerrada. A exclusão também arquiva (soft-delete) todos os Instrumentos vinculados à conta. ```http theme={null} DELETE /v2/.../accounts/{accountId} ``` A Etapa 8 recusa arquivar um Titular que ainda possui uma conta não excluída. Veja [Excluir uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-account.md). > [!NOTE] > > Excluir uma conta é uma remoção lógica. Suas transações permanecem disponíveis para auditoria e relatórios. ### Etapa 8: Arquivar o Titular no CRM Depois de excluir todas as suas contas, arquive o próprio Titular com uma soft delete. ```http theme={null} DELETE /v2/organizations/{organization_id}/holders/{holder_id} ``` > [!WARNING] > > **Não** passe `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](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-holder.md). ## Via Console *** Execute o mesmo fluxo de encerramento de oito etapas a partir do [Midaz Console](https://docs.lerian.studio/pt/products/midaz/console/midaz-module.md). O Console cobre a maior parte do fluxo por apontar e clicar, mas o bloqueio de créditos (Etapa 2) e o encerramento das contas (Etapa 6) exigem a API. Cada etapa abaixo indica a etapa equivalente da API nesta página. > [!WARNING] > > A ordem é a mesma do fluxo da API. Não arquive registros de CRM antes de encerrar as contas. ### 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ó. **Step 1** Na página **Titulares**, encontre o Titular a encerrar. **Step 2** Clique nos três pontos () na coluna **Ações** e selecione **Editar**. **Step 3** No formulário do Titular, defina o **Status** como **Inativo**. **Step 4** Confirme a atualização. > [!NOTE] > > 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](https://docs.lerian.studio/pt/products/midaz/console/crm-editing-a-holder.md). ### Etapa 2: Bloquear créditos nas contas > [!WARNING] > > **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. Quite qualquer `overdraftUsed` diferente de zero antes desta etapa. ### Etapa 3: Liquidar a atividade pendente Confirme que não há movimentações em andamento antes de zerar qualquer saldo. **Step 1** 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. **Step 2** 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`, `onHold = 0` e `overdraftUsed = 0` em todos os saldos. **Step 1** 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](https://docs.lerian.studio/pt/products/midaz/console/creating-a-transaction.md). **Step 2** Abra cada conta e confirme **available = 0**, **onHold = 0** e **overdraftUsed = 0** antes de continuar. > [!WARNING] > > A operação de encerramento recusa uma conta com qualquer saldo cujo valor `available`, `onHold` ou `overdraftUsed` não seja exatamente zero. ### Etapa 5: 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. Faça isso antes de excluir a conta na Etapa 7. **Step 1** Na página **Instrumentos**, encontre o instrumento a atualizar, clique nos três pontos () na coluna **Ações** e selecione **Editar**. **Step 2** No formulário do Instrumento, defina a **Data de Encerramento** (em `bankingDetails`) para a data oficial de encerramento usando o formato `YYYY-MM-DD`. **Step 3** Confirme a atualização. > [!NOTE] > > Os relatórios de ciclo de vida de conta do BACEN precisam de uma data de encerramento precisa. Veja [Editando um Instrumento](https://docs.lerian.studio/pt/products/midaz/console/crm-editing-alias-account.md). ### Etapa 6: Encerrar as Contas do Ledger no Midaz > [!WARNING] > > **O encerramento exige a API.** Siga a [Etapa 6: Encerrar as Contas do Ledger no Midaz](#step-6-close-the-ledger-accounts-in-midaz) na seção Via API. ### Etapa 7: Excluir as Contas do Ledger Exclua cada conta encerrada. A exclusão também arquiva todos os Instrumentos vinculados à conta. **Step 1** Na página **Contas**, encontre a Conta vinculada ao Titular, clique nos três pontos () na coluna **Ações** e selecione **Excluir**. **Step 2** Uma caixa de diálogo de confirmação aparecerá. Clique em **Confirmar** para finalizar a exclusão. **Step 3** Repita para cada conta vinculada ao Titular. Veja [Excluindo uma Conta](https://docs.lerian.studio/pt/products/midaz/console/deleting-an-account.md). ### Etapa 8: Arquivar o Titular no CRM Depois de excluir todas as suas contas, arquive o próprio Titular com uma **soft delete**. **Step 1** Na página **Titulares**, encontre o Titular a arquivar, clique nos três pontos () na coluna **Ações** e selecione **Excluir**. **Step 2** Uma caixa de diálogo de confirmação aparecerá. Clique em **Confirmar** para finalizar. > [!WARNING] > > 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](https://docs.lerian.studio/pt/products/midaz/console/crm-deleting-a-holder.md). ## 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 antes de encerrar uma conta. A operação de encerramento recusa uma conta que possui fundos. * **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.** As operações de uma conta excluída permanecem consultáveis para conciliação e relatórios. > [!TIP] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.