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

# Contas

> Use Contas como a unidade financeira principal de um Ledger do Midaz, vinculada a um único Ativo e registrando cada débito, crédito e saldo de um cliente ou produto.

Uma Conta é a unidade financeira principal de um Ledger do Midaz. Cada Conta se vincula a um Ativo e registra cada débito, crédito e saldo desse Ativo. Em termos bancários, uma Conta é um produto financeiro, como uma conta corrente, uma conta poupança ou uma conta de empréstimo.

> [!TIP]
>
> O Midaz não limita quantas contas você cria. Crie quantas a sua estrutura precisar.

## Estrutura da Conta

***

* **Conta > Ledger**: Você cria uma Conta dentro de um Ledger. O Ledger rastreia e consolida todos os saldos e operações.
* **Conta > Portfólio**: Você pode agrupar Contas em [**Portfólios**](https://docs.lerian.studio/pt/products/midaz/portfolios.md) para representar grupos de clientes, linhas de produto ou unidades de negócio.
* **Conta > Ativo**: Cada Conta se vincula a um **único Ativo**. O Ativo define o tipo de valor que a Conta guarda, como BRL, USD, BTC ou pontos de fidelidade.
* **Conta > Tipo de Conta**: Quando você habilita a validação de Tipo de Conta, cada Conta não externa deve usar um Tipo de Conta registrado. Você registra Tipos de Conta para a sua classificação de negócio.

## Características principais

***

* Cada Conta se vincula a exatamente um Ativo.
* Cada Conta tem um identificador único dentro de um Ledger.

## Várias contas por cliente

***

Um único cliente costuma ter mais de um saldo.

O mesmo cliente pode ter saldos que se comportam de forma diferente:

* **Natureza diferente**: um saldo principal, um saldo de benefício ou um saldo promocional.
* **Regras operacionais diferentes**: uma conta por ordem judicial que aceita entradas mas restringe saídas.
* **Extrato e conciliação separados**: uma subconta de produto ou compartimento que você acompanha de forma independente.

Quando o saldo, o ledger, o extrato ou a regra são diferentes, cada um se torna sua própria Conta. Você a classifica por um [Tipo de Conta](https://docs.lerian.studio/pt/products/midaz/account-types.md), a agrupa sob o cliente com um [Portfólio](https://docs.lerian.studio/pt/products/midaz/portfolios.md) e a vincula à identidade pelo [CRM](https://docs.lerian.studio/pt/products/midaz/crm/crm-overview.md). Uma conta com rótulos funciona até os saldos divergirem. Contas separadas mantêm cada saldo correto desde o início.

> [!TIP]
>
> Para a arquitetura de referência completa (um cliente, várias contas, com exemplos passo a passo), veja [Midaz para clientes com várias contas](https://docs.lerian.studio/pt/products/midaz/midaz-for-multi-account-customers.md).

## Conta Externa

***

Contas Externas no Midaz representam contas fora da estrutura da sua organização. Elas rastreiam dinheiro que entra ou sai do seu ledger, geralmente de e para usuários, parceiros ou provedores financeiros.

Contas externas têm estas características:

* **Guardam o saldo da contraparte** do dinheiro que entra ou sai do seu ledger.
* **O Ledger cria uma Conta externa canônica automaticamente** quando você cria um Ativo.
* **A Conta externa canônica segue um padrão de nomenclatura claro**: `@external/<asset-code>`, como `@external/BRL`.

Essas contas registram entradas e saídas na fronteira do ledger.

> [!CAUTION]
>
> **Não tente excluir ou alterar uma conta externa.** O Midaz bloqueia essas operações para manter o Ledger preciso e rastreável.

### Códigos de conta externa

A Conta externa canônica criada com um Ativo segue o padrão de nomenclatura `@external/<asset-code>`. O código do ativo nesse alias é a chave de busca. Você pode buscar essa Conta canônica e os saldos dela com endpoints de conveniência que aceitam apenas o código do ativo:

* `GET .../accounts/external/{code}`: Busca a conta externa de um código de ativo (por exemplo, `BRL` resolve para `@external/BRL`).
* `GET .../accounts/external/{code}/balances`: Busca os saldos dessa conta externa.

Esses endpoints são atalhos para a Conta externa canônica. Eles adicionam `@external/` antes do código que você informa e então fazem uma busca baseada no alias. O resultado é idêntico a uma consulta por esse alias completo.

### Entity ID (referência de sistema externo)

O campo `entityId` existe em qualquer conta, não apenas em contas externas. Ele vincula a conta a um registro em um sistema externo, como uma plataforma de core banking, um CRM ou um sistema parceiro.

* **Não é o mesmo que o alias**: Você usa o alias nas transações, e ele deve ser único dentro de um ledger. O `entityId` é apenas uma referência para a sua integração, e o Midaz não o usa para movimentar valor.
* **Opcional**: Defina-o quando criar a conta ou quando atualizá-la. O tamanho máximo é 256 caracteres.
* **Caso de uso**: Quando o seu sistema já tem um identificador de conta, como `EXT-ACC-12345`, armazene-o em `entityId`. Assim você consegue mapear entre o Midaz e a sua fonte de verdade.

```json JSON theme={null}
{
  "name": "User Checking Account",
  "assetCode": "BRL",
  "alias": "@user_checking_123",
  "entityId": "EXT-ACC-12345",
  "type": "checking"
}
```

## ID da conta pai

***

O **ID da conta pai** vincula duas contas dentro do Midaz. Você define o relacionamento com base na sua lógica de negócio. A Conta pai deve estar no mesmo Ledger e usar o mesmo Ativo.

Você pode usá-lo para uma estrutura tradicional de pai e filho ou para outro relacionamento que o seu negócio precisar.

## Contas bloqueadas

***

Defina `blocked` como `true` quando criar ou atualizar uma Conta. O Midaz então recusa cada transação que movimenta a Conta, como origem ou destino. O bloqueio não impede o cancelamento de uma transação pendente.

Para permitir um débito de valor exato de uma Conta bloqueada, [crie uma exceção de bloqueio de uso único](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-account-block-exceptions.md). Depois, envie o ID dela no campo `accountBlockExceptionId` da transação.

## Aliases de conta

***

Um alias substitui um ID de conta complexo por um rótulo legível. Isso facilita identificar as contas.

* **Por exemplo**: Em vez do ID `3172933b-50d2-4b17-96aa-9b378d6a6eac`, você pode usar `@username_1`.

### Use o Alias da Conta nas Transações

Quando você cria uma transação, identifique cada Conta pelo **alias da conta**. Não use o ID da conta.

Um alias é **opcional** quando você cria uma Conta não externa. Se você não informar um, o Midaz usa o ID da conta como alias. Uma Conta externa criada pelo usuário exige um alias. O alias que você define pode ter no máximo 100 caracteres de `a-z`, `A-Z`, `0-9`, `@`, `:`, `_` e `-`.

## Gerenciando Contas

***

Você pode gerenciar suas Contas pela API ou pelo Lerian Console.

### Pela API

* [Criar uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-account.md): Abra uma nova Conta vinculada a um Ativo.
* [Abrir uma Conta de um Titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder-account.md): Abra uma Conta que pertence a um Titular e, opcionalmente, o Instrumento dela, em uma única chamada.
* [Listar Contas](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-accounts.md): Veja todas as Contas de um Ledger.
* [Buscar uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-account-by-id.md): Obtenha detalhes de uma Conta específica.
* [Buscar uma Conta pelo Alias](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-account-by-alias.md): Obtenha detalhes de uma Conta específica pelo alias dela.
* [Buscar uma Conta Externa](https://docs.lerian.studio/pt/reference/products/midaz/v2/get-account-external-by-code.md): Obtenha detalhes de uma Conta Externa específica pelo código do ativo dela.
* [Atualizar uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-account.md): Edite os metadados ou as configurações de uma Conta existente.
* [Excluir uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/delete-account.md): Exclua uma Conta específica. O Midaz também arquiva os Instrumentos dela, termina a atribuição de [plano de tarifas](https://docs.lerian.studio/pt/products/midaz/fees/account-plans.md) dela e remove o alias dela dos pacotes de tarifas e de cobrança do ledger.
* [Encerrar uma Conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/close-account.md): Encerre uma Conta cujos saldos estão todos exatamente em zero. O Midaz mantém o histórico dela e recusa qualquer movimentação posterior.

> [!WARNING]
>
> **Transfira qualquer saldo restante para outra conta antes de excluir uma conta.** O Midaz não exclui uma conta ou subconta que ainda tenha saldo. O Midaz também se recusa a excluir ou encerrar uma conta com um saldo que deve [dívida de tarifa](https://docs.lerian.studio/pt/products/midaz/fees/fee-debt.md) (`0527`) ou ao qual outros saldos devem dívida de tarifa (`0528`).

### Pelo Lerian Console

Você pode ver, criar, editar e excluir Contas na página Contas. Essa página fica no módulo Midaz do Lerian Console.

[**Saiba mais no guia Gerenciando Contas.**](https://docs.lerian.studio/pt/products/midaz/console/managing-accounts)


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