Registrar un titular y abrir una cuenta (API) - Lerian

Registra al titular de una cuenta, la persona o la empresa dueña de ella, y abre la cuenta para ese titular.

Participantes

Tu institución. Tu sistema. Registra al titular y abre la cuenta.
Midaz. El ledger y su CRM. Guarda al titular, la cuenta y el instrumento que los vincula.

Antes de empezar

La organización, el ledger y el activo existen. Consulta Montar un ledger y registrar la primera transacción.
Tu sistema tiene un token que puede crear titulares y cuentas en Midaz.

Diagrama

Registrar un titular y abrir una cuenta

Pasos por la API

#	Origen	Destino	Mensaje	API de Lerian	Qué ocurre
1	Tu institución	Midaz	Llamada a la API	`POST /v2/organizations/{organization_id}/holders`	Registra al titular con su `type` (`NATURAL_PERSON` o `LEGAL_PERSON`), su `name` y su `document`.
2	Midaz	Tu institución	Respuesta de la API		Midaz responde `201` con el `id` del titular.
3	Tu institución	Midaz	Llamada a la API	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts`	Abre la cuenta para el titular. Envía los campos de la cuenta, como `assetCode`, `type` y `alias`. Para crear también el instrumento, agrega `bankingDetails`, `regulatoryFields` o `relatedParties`. Envía el header `X-Idempotency`.
4	Midaz	Midaz	Paso interno		Midaz crea la cuenta y su saldo `default`. El titular de la ruta es el dueño de la cuenta.
5	Midaz	Midaz	Paso interno		Cuando la solicitud tiene campos de instrumento, Midaz crea el instrumento que vincula al titular con la cuenta.
6	Midaz	Tu institución	Respuesta de la API		Midaz responde `201` con el `account` y el `instrument`.
7	Tu institución	Midaz	Llamada a la API	`GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts`	Lista las cuentas del titular.
8	Midaz	Tu institución	Respuesta de la API		Midaz devuelve las cuentas de las que el titular es dueño.

Cómo saber que terminó

La lista de cuentas del titular muestra la cuenta nueva.

Qué puede salir mal

Situación	Qué ves	Qué hacer
La cuenta se creó, pero el instrumento no	`201` con `instrument` como `null` y un `instrumentError`	La cuenta existe y funciona. Crea el instrumento con Crear un instrumento.
El titular no existe, y el ledger exige un titular	`404` con `CRM-0006`	Registra primero al titular.
Abres una cuenta sin titular, y el ledger exige uno	`422` con `0491`	Abre la cuenta para un titular, como en el paso 3.
La respuesta del paso 3 no llega	Ninguna respuesta, o un timeout	Dentro del tiempo del header `X-TTL` (300 segundos por defecto), envía la misma solicitud con la misma clave `X-Idempotency`. Una repetición devuelve la primera respuesta con `X-Idempotency-Replayed: true`. Después de un `409` con `0084`, o después de ese tiempo, lista las cuentas del titular antes de intentarlo otra vez.

Relacionados