> ## 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 central de um Ledger Midaz, registrando débitos, créditos e saldos vinculados a um Ativo específico.

Em termos bancários, uma Conta representa um produto financeiro, como uma conta corrente, conta poupança ou conta de empréstimo.

<Tip>
  O Midaz permite criar quantas contas sua estrutura exigir. Sem limites, sem restrições; apenas a flexibilidade que você precisa.
</Tip>

## Estrutura da Conta

***

* **Conta > Ledger**: As Contas são criadas *dentro* de um Ledger, que rastreia e consolida todos os saldos e operações.
* **Conta > Portfolio**: As Contas podem ser agrupadas em [**Portfólios**](/pt/midaz/portfolios) para representar grupos de clientes, linhas de produtos ou unidades de negócios.
* **Conta > Ativo**: Cada Conta está vinculada a um **único Ativo**, definindo o tipo de valor que ela mantém — como BRL, USD, BTC ou pontos de fidelidade.
* **Conta > Tipo de Conta**: Com a validação de Tipo de Conta **habilitada**, cada Conta deve ser categorizada por um Tipo de Conta que pode ser criado de acordo com necessidades específicas do usuário ou classificação do negócio.

## Características principais

***

* Cada Conta está vinculada a exatamente um tipo de Ativo.
* As Contas são identificadas de forma única dentro de um Ledger.
* Todas as transações envolvem débitos e créditos entre Contas.

## Várias contas por cliente

***

Um único cliente costuma ter mais de um saldo — e o Midaz modela cada um como sua própria Conta, em vez de rótulos sobre um saldo compartilhado. A regra que orienta: **crie uma conta separada sempre que um saldo precisar ter sua própria verdade.**

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

* **Natureza diferente** — um saldo principal, um saldo benefício, um saldo promocional.
* **Regras operacionais diferentes** — uma conta judicial ou bloqueada que aceita entradas mas restringe saídas.
* **Extrato e conciliação separados** — uma subconta de produto ou pocket que precisa ser acompanhada por conta própria.

Quando saldo, ledger, extrato ou regra difere, cada um vira sua própria Conta — classificada por um [Tipo de Conta](/pt/midaz/account-types), agrupada sob o cliente via um [Portfolio](/pt/midaz/portfolios) e vinculada à identidade pelo [CRM](/pt/midaz/crm/crm-overview). Modelar isso como uma conta com rótulos funciona até os saldos precisarem divergir; contas separadas mantêm cada uma precisa 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](/pt/midaz/midaz-for-multi-account-customers).
</Tip>

## Conta Externa

***

Contas Externas no Midaz representam contas fora da estrutura da sua organização. Elas são usadas para rastrear dinheiro que está entrando ou saindo, normalmente vinculadas a usuários, parceiros ou provedores financeiros fora do seu ledger interno.

Mas elas são mais do que simples marcadores. Contas externas:

* **Gerenciam saldos temporários** durante operações envolvendo partes externas.
* **São as únicas contas que podem ficar negativas**, o que sinaliza que os fundos estão em trânsito.
* **São criadas automaticamente pelo Ledger** sempre que você cria um Ativo.
* **Seguem um padrão de nomenclatura claro**: `@external/<asset-code>`, como `@external/BRL`.

Na prática, essas contas funcionam como pontes entre o seu sistema e o mundo externo, lidando com entradas, saídas e tudo entre eles com clareza e controle.

<Danger>
  Para manter o Ledger preciso e confiável, **contas externas não podem ser excluídas ou alteradas**.
</Danger>

### Códigos de conta externa

Toda conta externa segue o padrão de nomenclatura `@external/<asset-code>`. O asset code no alias atua como chave de lookup da conta externa — você pode recuperar a conta e seus saldos usando endpoints de conveniência que aceitam apenas o asset code:

* `GET .../accounts/external/{code}` — Recupera a conta externa para um asset code (por exemplo, `BRL` resolve para `@external/BRL`).
* `GET .../accounts/external/{code}/balances` — Recupera os saldos dessa conta externa.

Esses endpoints são atalhos — eles prefixam `@external/` ao código que você fornece e realizam um lookup baseado em alias. O resultado é idêntico ao de consultar pelo alias completo.

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

O campo `entityId` em qualquer conta (não apenas em contas externas) permite vinculá-la a um registro em um sistema externo — como uma plataforma de core banking, um CRM ou um sistema de parceiro.

* **Não é o mesmo que alias**: aliases são usados em transações e precisam ser únicos dentro de um ledger. `entityId` é puramente informativo — uma referência para sua integração, não usado internamente pelo Midaz.
* **Opcional**: defina na criação ou via atualização. Máximo 256 caracteres.
* **Caso de uso**: quando seu sistema já possui um identificador de conta (por exemplo, `EXT-ACC-12345`), guarde-o em `entityId` para conseguir mapear entre o Midaz e a sua source of truth.

<CodeGroup>
  ```json JSON theme={null}
  {
    "name": "User Checking Account",
    "assetCode": "BRL",
    "alias": "@user/checking_123",
    "entityId": "EXT-ACC-12345",
    "type": "checking"
  }
  ```
</CodeGroup>

## ID da Conta Pai

***

O **ID da Conta Pai** vincula duas contas dentro do Midaz, dando a você a flexibilidade de definir o relacionamento com base na sua lógica de negócio.

Seja para representar uma estrutura pai-filho tradicional ou algo completamente diferente, a escolha é sua. O Midaz fornece a base — você decide como construir sobre ela.

## Aliases de Conta

***

Aliases facilitam a identificação de contas substituindo IDs complexos por rótulos legíveis e amigáveis.

* **Por exemplo**: Em vez de referenciar uma conta como `3172933b-50d2-4b17-96aa-9b378d6a6eac`, você pode simplesmente usar `@username_1`.

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

Ao criar uma transação, sempre use o **alias da conta** no campo `account` — não o ID da conta.

Atribuir um alias ao criar uma conta é **opcional**. Se você não fizer isso, sem problemas — o sistema usará automaticamente o ID da conta como alias. De qualquer forma, toda conta acaba com um alias único.

Então, quando for referenciar uma conta em uma transação, basta usar o alias. Limpo, consistente e pronto para uso.

## Gerenciando Contas

***

Você pode gerenciar suas Contas via API ou através do Lerian Console.

### Via API

* [Criar uma Conta](/pt/reference/midaz/create-an-account) — Abra uma nova Conta vinculada a um Ativo.
* [Listar Contas](/pt/reference/midaz/list-accounts) — Visualize todas as Contas no seu workspace.
* [Recuperar uma Conta](/pt/reference/midaz/retrieve-an-account) — Obtenha detalhes de uma Conta específica.
* [Recuperar uma Conta por Alias](/pt/reference/midaz/retrieve-an-account-by-alias) — Obtenha detalhes de uma Conta específica pelo seu alias.
* [Recuperar uma Conta Externa](/pt/reference/midaz/retrieve-an-external-account) — Obtenha detalhes de uma Conta Externa específica pelo código do ativo.
* [Atualizar uma Conta](/pt/reference/midaz/update-an-account) — Edite os metadados ou configurações de uma Conta existente.
* [Excluir uma Conta](/pt/reference/midaz/delete-an-account) — Exclua uma Conta específica.

<Warning>
  Você não pode desativar uma conta com saldo remanescente. Primeiro, transfira o valor para outra conta antes de desativá-la.
</Warning>

### Via Lerian Console

Todas as ações de gerenciamento de Contas, incluindo visualização, criação, edição e exclusão, podem ser feitas através da página de Contas no Módulo Midaz do Lerian Console.

[**Saiba mais no guia de Gerenciamento de Contas.**](/pt/midaz/console/managing-accounts)