Instrumentos

Um Instrumento é o registro de CRM que associa um Titular 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 para conhecer o schema atual de requisição e resposta.

​

Próximos passos