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

# Instrumentos

> Associe Titulares a Contas do Ledger e guarde informações bancárias, regulatórias, de metadados e de partes relacionadas.

Um **Instrumento** é o registro de CRM que associa um [Titular](https://docs.lerian.studio/pt/products/midaz/crm/holders.md) a uma Conta do Ledger no Midaz. Ele guarda o `ledgerId` e o `accountId` dessa associação, junto com dados bancários, campos regulatórios, metadados e partes relacionadas.

Instrumentos mantêm o contexto do CRM separado do Ledger transacional. O Ledger continua sendo o registro de saldos e movimentações. O Instrumento guarda o contexto associado a um Titular e à Conta do Ledger dele.

## Criar um Instrumento

Crie um Instrumento no escopo de um Titular. A entrada de criação exige `ledgerId` e `accountId` da Conta do Ledger associada. O ledger e a conta devem existir na organização.

O objeto `bankingDetails` pode conter `branch`, `account`, `type`, `openingDate`, `closingDate`, `iban`, `countryCode` e `bankId`. Os campos individuais dele são opcionais. O Midaz rejeita dados bancários cujos `bankId`, `branch` e `account` outro Instrumento da organização já tem.

A resposta de um Instrumento inclui o `id`, o `holderId`, o `ledgerId`, o `accountId`, o `document`, o `type`, as datas e horas e os dados bancários, regulatórios, de metadados ou de partes relacionadas que estiverem configurados.

Para abrir a Conta do Ledger e o Instrumento dela em uma única chamada, use `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts`. O Titular do caminho é o dono da nova Conta. O corpo recebe os campos da Conta e, opcionalmente, `bankingDetails`, `regulatoryFields` e `relatedParties`. Quando o corpo não tem nenhum desses três, o Midaz cria apenas a Conta.

Uma resposta `201` traz `account` e `instrument`. Quando o Midaz cria a Conta mas não consegue gravar o Instrumento, `instrument` é `null` e `instrumentError` traz `status` e `reason`. A Conta permanece, e você pode criar o Instrumento dela separadamente.

Envie `X-Idempotency` para repetir esta chamada com segurança. Uma repetição com a mesma chave retorna o primeiro `201`, inclusive um parcial, com `X-Idempotency-Replayed: true`. Depois de uma resposta `5xx`, a Conta pode já existir, então uma repetição com a mesma chave retorna `409` com `0084` até a chave expirar. `X-TTL` define esse tempo em segundos (padrão `300`).

## Campos regulatórios e partes relacionadas

Use `regulatoryFields.participantDocument` para guardar o documento do participante quando ele se aplicar. `regulatoryFields.accountType` aceita `DEPOSIT`, `SAVINGS`, `INVESTMENT`, `OTHER_FINANCIAL_INVESTMENTS`, `NON_RESIDENT` ou `PAYMENT`.

Um Instrumento pode incluir partes relacionadas. Cada parte relacionada exige `document`, `name`, `role` e `startDate`. O `role` é `PRIMARY_HOLDER`, `LEGAL_REPRESENTATIVE` ou `RESPONSIBLE_PARTY`. Os campos `id` e `endDate` são opcionais, e `endDate` não deve ser anterior a `startDate`.

## Gerenciar Instrumentos

A API do Midaz deixa você:

* Listar Instrumentos de uma organização.
* Criar um Instrumento para um Titular.
* Consultar, atualizar ou excluir um Instrumento no escopo do Titular dele.
* Excluir uma parte relacionada de um Instrumento.

Use a [referência da API do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-instruments.md) para conhecer o schema atual de requisição e resposta.

## Próximos passos

> [card] [Titulares](https://docs.lerian.studio/pt/products/midaz/crm/holders.md)
>
> Conheça o Titular associado a um Instrumento.

> [card] [Contas](https://docs.lerian.studio/pt/products/midaz/accounts.md)
>
> Veja como as Contas do Ledger do Midaz guardam saldos e movimentações.


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