Instrumentos

Un Instrumento es el registro de CRM que asocia un Titular con una Cuenta del Ledger en Midaz. Almacena el ledgerId y el accountId de esa asociación, junto con detalles bancarios, campos regulatorios, metadatos y partes relacionadas. Los Instrumentos mantienen el contexto de CRM separado del Ledger transaccional. El Ledger sigue siendo el registro de saldos y movimientos. El Instrumento contiene el contexto asociado a un Titular y su Cuenta del Ledger.

​

Crear un Instrumento

Crea un Instrumento dentro del alcance de un Titular. La entrada de creación requiere ledgerId y accountId de la Cuenta del Ledger asociada. El ledger y la cuenta deben existir en la organización. El objeto bankingDetails puede contener branch, account, type, openingDate, closingDate, iban, countryCode y bankId. Sus campos individuales son opcionales. Midaz rechaza los datos bancarios cuyos bankId, branch y account ya tiene otro Instrumento de la organización. Una respuesta de Instrumento incluye su id, holderId, ledgerId, accountId, document, type, marcas de tiempo y cualquier dato bancario, regulatorio, de metadatos o de partes relacionadas configurado. Para abrir la Cuenta del Ledger y su Instrumento en una sola llamada, usa POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts. El Titular de la ruta es el dueño de la nueva Cuenta. El cuerpo recibe los campos de la Cuenta y, opcionalmente, bankingDetails, regulatoryFields y relatedParties. Cuando el cuerpo no tiene ninguno de estos tres, Midaz crea solo la Cuenta. Una respuesta 201 incluye account e instrument. Cuando Midaz crea la Cuenta pero no puede escribir el Instrumento, instrument es null e instrumentError incluye status y reason. La Cuenta se mantiene, y puedes crear su Instrumento por separado. Envía X-Idempotency para repetir esta llamada de forma segura. Una repetición con la misma clave devuelve el primer 201, incluido uno parcial, con X-Idempotency-Replayed: true. Después de una respuesta 5xx, la Cuenta puede existir ya, así que una repetición con la misma clave devuelve 409 con 0084 hasta que la clave expire. X-TTL define ese tiempo en segundos (predeterminado 300).

​

Campos regulatorios y partes relacionadas

Usa regulatoryFields.participantDocument para almacenar el documento del participante cuando aplique. regulatoryFields.accountType acepta DEPOSIT, SAVINGS, INVESTMENT, OTHER_FINANCIAL_INVESTMENTS, NON_RESIDENT o PAYMENT. Un Instrumento puede incluir partes relacionadas. Cada parte relacionada requiere document, name, role y startDate. El role es PRIMARY_HOLDER, LEGAL_REPRESENTATIVE o RESPONSIBLE_PARTY. Los campos id y endDate son opcionales, y endDate no debe ser anterior a startDate.

​

Administrar Instrumentos

La API de Midaz permite:

• Listar Instrumentos de una organización.
• Crear un Instrumento para un Titular.
• Consultar, actualizar o eliminar un Instrumento dentro del alcance de su Titular.
• Eliminar una parte relacionada de un Instrumento.

Usa la referencia de la API de Midaz para conocer el esquema actual de solicitud y respuesta.

​

Próximos pasos