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

# Cadastrar um titular e abrir uma conta (API)

> Cadastre a pessoa ou a empresa dona de uma conta no CRM do Midaz e depois abra a conta para esse titular, pela API do Midaz.

Cadastre o titular de uma conta, a pessoa ou a empresa dona dela, e abra a conta para esse titular.

## Participantes

***

* **Sua instituição.** O seu sistema. Ele cadastra o titular e abre a conta.
* **Midaz.** O ledger e o seu CRM. Ele guarda o titular, a conta e o instrumento que os liga.

## Antes de começar

***

* A organização, o ledger e o ativo existem. Veja [Montar um ledger e lançar a primeira transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-create-and-transact.md).
* O seu sistema tem um token que pode criar titulares e contas no Midaz.

## Diagrama

***

![Cadastrar um titular e abrir uma conta](https://mintcdn.com/lerian-49cb71fc/WuRfbo_y9uSbzyyX/images/pt/d2/id-midaz-register-a-holder.svg?fit=max\&auto=format\&n=WuRfbo_y9uSbzyyX\&q=85\&s=df160928a3f396bfba7651923ca80a60)

## Passo a passo pela API

***

| # | Origem | Destino | Mensagem | API da Lerian | O que acontece |
| - | - | - | - | - | - |
| 1 | Sua instituição | Midaz | Chamada de API | [`POST /v2/organizations/{organization_id}/holders`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder) | Cadastre o titular com seu `type` (`NATURAL_PERSON` ou `LEGAL_PERSON`), seu `name` e seu `document`. |
| 2 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201` com o `id` do titular. |
| 3 | Sua instituição | Midaz | Chamada de API | [`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts`](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder-account) | Abra a conta para o titular. Envie os campos da conta, como `assetCode`, `type` e `alias`. Para criar o instrumento também, adicione `bankingDetails`, `regulatoryFields` ou `relatedParties`. Envie o header `X-Idempotency`. |
| 4 | Midaz | Midaz | Etapa interna | | O Midaz cria a conta e o saldo `default` dela. O titular indicado no caminho é o dono da conta. |
| 5 | Midaz | Midaz | Etapa interna | | Quando a requisição tem campos de instrumento, o Midaz cria o instrumento que liga o titular à conta. |
| 6 | Midaz | Sua instituição | Resposta da API | | O Midaz responde `201` com o `account` e o `instrument`. |
| 7 | Sua instituição | Midaz | Chamada de API | [`GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts`](https://docs.lerian.studio/pt/reference/products/midaz/v2/list-accounts-by-holder) | Liste as contas do titular. |
| 8 | Midaz | Sua instituição | Resposta da API | | O Midaz devolve as contas de que o titular é dono. |

## Como saber que terminou

***

A lista de contas do titular mostra a conta nova.

## O que pode dar errado

***

| Situação | O que você vê | O que fazer |
| - | - | - |
| A conta foi criada, mas o instrumento não | `201` com `instrument` como `null` e um `instrumentError` | A conta existe e funciona. Crie o instrumento com [Criar um instrumento](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-instrument.md). |
| O titular não existe, e o ledger exige um titular | `404` com `CRM-0006` | Cadastre o titular primeiro. |
| Você abre uma conta sem titular, e o ledger exige um | `422` com `0491` | Abra a conta para um titular, como no passo 3. |
| A resposta do passo 3 não chega | Nenhuma resposta, ou um timeout | Dentro do tempo do header `X-TTL` (300 segundos por padrão), envie a mesma requisição com a mesma chave `X-Idempotency`. Uma repetição devolve a primeira resposta com `X-Idempotency-Replayed: true`. Depois de um `409` com `0084`, ou depois desse tempo, liste as contas do titular antes de tentar de novo. |

## Relacionados

***

* [Montar um ledger e lançar a primeira transação](https://docs.lerian.studio/pt/diagrams/lerian-products/midaz-create-and-transact.md)
* [Titulares](https://docs.lerian.studio/pt/products/midaz/crm/holders.md)
* [Instrumentos](https://docs.lerian.studio/pt/products/midaz/crm/alias-accounts.md)
* [Lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md)


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