Migra de la API v1 a la API v2

​

Rutas del Ledger

• /v2/organizations y /v2/organizations/{organization_id}/ledgers reciben solo la organización.
• /v2/settings/metadata-indexes no recibe organización ni ledger.
• /v2/transactions/direct, /v2/transactions/hold, /v2/transactions/block y /v2/transactions/unblock no reciben organización ni ledger en la URL.

​

Organización y ledger en el cuerpo de la transacción

# API v1: the organization and the ledger are in the path
POST /v1/organizations/3fa85f64-5717-4562-b3fc-2c963f66afa6/ledgers/9c858901-8a57-4791-81fe-4a34d4dd8ab5/transactions/json

# API v2: the organization and the ledger are in each item of the body
POST /v2/transactions/direct

{
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

• Envía organizationId y ledgerId en cada elemento. Ambos son obligatorios, y ambos son UUID.
• Todos los elementos deben indicar la misma organización y el mismo ledger.
• A partir de v4.1.0, direct y hold aceptan elementos en ledgers distintos cuando cada ledger habilita crossLedger.enabled. Consulta transacciones entre Ledgers.
• block y unblock siempre necesitan una organización y un ledger en todos los elementos.

​

Excepciones

• Anotaciones. POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/annotation no tiene una ruta v2.
• Cotizaciones de activos. Estas rutas v1 no tienen una ruta v2:
  • PUT /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/{external_id}
  • GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/asset-rates/from/{asset_code}
• Tracer. Tracer conserva su propia API v1. Consulta el Inicio rápido de la API de Tracer.

​

CRM y Fees en la API v2

​

CRM

​

Fees

​

Cambios de alcance y de permisos

• Envía la organización en la URL. No envíes el header X-Organization-Id.
• En Fees, envía el ledger en la URL. Elimina ledgerId del cuerpo de los paquetes, las estimaciones, los paquetes de facturación y el cálculo de facturación.
• Las listas de paquetes y de paquetes de facturación siempre cubren un solo ledger. En el plugin, ledgerId era un parámetro de consulta opcional. Para listar los paquetes de una organización completa, llama a la lista una vez por cada ledger.
• En los instrumentos de CRM, conserva ledgerId y accountId en el cuerpo.
• Usa las estimaciones solo para simular comisiones. Una estimación no registra nada.

​

Contrato de transacción

• asset: el código del activo.
• amount: el total, como una cadena decimal.
• debits y credits: arreglos con uno o más elementos cada uno.

• alias: el alias de la cuenta.
• organizationId y ledgerId: los UUID de la organización y del ledger de la cuenta. Consulta Organización y ledger en el cuerpo de la transacción.
• amount o share: envía exactamente uno de los dos.

• Usa /v2/transactions/direct para registrar la transacción de inmediato.
• Usa /v2/transactions/hold para crear una transacción pendiente. Después, confírmala o cancélala.

​

Ejemplo de una transacción directa

{
  "asset": "BRL",
  "amount": "100.00",
  "debits": [
    {
      "alias": "@source",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ],
  "credits": [
    {
      "alias": "@destination",
      "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
      "amount": "100.00"
    }
  ]
}

​

Campos que el cuerpo v2 no acepta

• rate y remaining en un elemento.
• metadata en un elemento. La transacción en sí sigue aceptando metadata.
• transactionDate.
• balanceKey en un elemento, solo en Midaz v4.0.x. A partir de v4.1.0, cada elemento acepta un balanceKey opcional.

​

Respuestas y errores

​

Respuestas de transacción

• source y destination pasan a ser debit y credit, en singular.
• La transacción ya no tiene route ni chartOfAccountsGroupName.
• Las operaciones dentro de una transacción ya no tienen route ni chartOfAccounts. Conservan routeId, routeCode y routeDescription.
• Las respuestas de una operación que lees por separado no cambian.
• A partir de v4.1.0, un direct o hold que abarca varios ledgers devuelve un grupo con groupId y transactions[]. Confirmar, cancelar y revertir también pueden devolver un grupo.

​

Errores

• type, title, status y detail.
• code: el código de error de Midaz. El mismo error tiene el mismo código en v1 y v2.
• errors[]: los errores de campo, cuando la solicitud los tiene.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://errors.lerian.studio/v1/0053",
  "title": "Unexpected Fields in the Request",
  "status": 400,
  "detail": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
  "errors": [
    {
      "message": "unexpected field",
      "location": "transactionDate"
    }
  ],
  "code": "0053"
}

​

Cuentas y reglas en la API v2

​

Rutas de cuentas

• Leer una cuenta por alias y por código externo.
• Actualizar y eliminar una cuenta.
• Contar las cuentas con HEAD.

​

Reglas de titulares

• Cuando accounting.requireHolder está activado, cada cuenta necesita un titular de la organización. Sin un titular, Midaz no crea la cuenta.
• Para omitir esa verificación, envía skip.holder. Midaz lo acepta solo cuando overrides.allowHolderSkip está activado. De lo contrario, Midaz rechaza la solicitud con 422 y el error 0490.
• Cuando accounting.requireHolder está desactivado y no envías un titular, una cuenta no externa recibe el titular de su organización. Una cuenta externa no recibe un titular.
• Cuando accounting.requireHolder está desactivado, Midaz no verifica que exista el holderId que envías.
• Una cuenta que creas a través de v1 no recibe un titular. v1 no aplica estas reglas.

​

Fees y Tracer

• Fees. Midaz cobra una comisión cuando un paquete de comisiones coincide con la transacción.
• Tracer. Midaz reserva la transacción en Tracer cuando el modo de Tracer del ledger no es off.

​

Lista de verificación de la migración

• Lista las rutas que usas, la versión del producto y la URL base de cada servicio. Separa las rutas que tienen una ruta v2 de las rutas que no la tienen. Planifica dejar de usar las rutas que no la tienen a más tardar el 29 de abril de 2027.
• Para cada transacción, elige direct o hold. Actualiza debits, credits, los valores decimales y el alcance de cada elemento.
• Cambia los alias de CRM por instrumentos. Mueve la organización y el ledger de Fees a la URL. Después de la migración de datos, verifica los vínculos y los identificadores.
• Otorga los permisos midaz. Prueba las reglas de titulares de las cuentas en un entorno de staging.
• Actualiza cómo lees las respuestas de éxito y de error. Prueba los campos eliminados, los datos de entrada no válidos, los recursos inexistentes y el acceso denegado.
• Prueba cada flujo que usa tu integración: crear, leer, retener, confirmar, cancelar, revertir, bloquear y desbloquear. Verifica los saldos, las operaciones, las comisiones y los rechazos por límites de Tracer.
• Sigue enviando X-Idempotency y X-TTL en las solicitudes de creación. No envíes la misma transacción por v1 y v2 para comparar resultados. Usa datos y escenarios controlados en un entorno de staging.
• Mueve el tráfico en pasos controlados. Supervisa los errores y los resultados financieros. Mantén un plan de rollback que no vuelva a enviar transacciones ya procesadas.