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

## 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**](/pt/products/midaz/portfolios) 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 tipo de Ativo.
* Cada Conta tem um identificador único dentro de um Ledger.
* Toda transação registra débitos e créditos entre Contas.

## Várias contas por cliente

***

Um único cliente costuma ter mais de um saldo. O Midaz modela cada saldo como sua própria Conta, não como rótulos em uma conta compartilhada. Crie uma conta separada sempre que um saldo precisar de sua própria verdade.

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 bloqueada ou 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](/pt/products/midaz/account-types), a agrupa sob o cliente com um [Portfólio](/pt/products/midaz/portfolios) e a vincula à identidade pelo [CRM](/pt/products/midaz/crm/crm-overview). 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](/pt/products/midaz/midaz-for-multi-account-customers).
</Tip>

## 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.
* **Podem representar uma posição externa negativa.** Quando uma conta externa usa overdraft, a posição derivada dela pode ficar negativa. O saldo `Available` persistido permanece em zero e o Midaz rastreia o uso em `OverdraftUsed`.
* **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.

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

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

<h3 id="entity-id-external-system-reference">
  Entity ID (referência de sistema externo)
</h3>

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.

<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. Você define o relacionamento com base na sua lógica de negócio.

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

<h2 id="account-aliases">
  Aliases de conta
</h2>

***

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, sempre use o **alias da conta** no campo `account`. 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. Assim, toda conta tem um alias único.

## Gerenciando Contas

***

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

### Pela API

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

<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.
</Warning>

### 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.**](/pt/products/midaz/console/managing-accounts)