> ## 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. # Crear una Transacción de Desbloqueo > Utilice este endpoint para crear una transacción cuyas operaciones resultantes son del tipo `UNBLOCK`. Midaz es agnóstico respecto al motivo de negocio para desbloquear fondos: utilice el campo `metadata` para registrarlo. Este endpoint siempre crea una transacción confirmada de inmediato y no pendiente: el campo `pending` del cuerpo de la solicitud se ignora (se sobrescribe a `false`); las transacciones de desbloqueo nunca están pendientes. El endpoint acepta el mismo cuerpo que el endpoint de creación JSON. ## OpenAPI ````yaml es/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock openapi: 3.1.0 info: title: API de Midaz Ledger description: >- Referencia completa de la API para los servicios de Midaz Ledger, incluyendo gestión de organizaciones, operaciones de ledger, activos, segmentos, portafolios, cuentas, tipos de cuenta, transacciones, operaciones, saldos, rutas de operación, rutas de transacción e índices de metadatos. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: Organizations API - name: Ledgers API - name: Assets API - name: Segments API - name: Portfolios API - name: Account Types API - name: Accounts API - name: Balances API - name: Transactions API - name: Operations API - name: Operation Routes API - name: Transaction Routes API - name: Metadata Indexes API paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock: post: tags: - Transactions API summary: Crear una Transacción de Desbloqueo description: >- Utilice este endpoint para crear una transacción cuyas operaciones resultantes son del tipo `UNBLOCK`. Midaz es agnóstico respecto al motivo de negocio para desbloquear fondos: utilice el campo `metadata` para registrarlo. Este endpoint siempre crea una transacción confirmada de inmediato y no pendiente: el campo `pending` del cuerpo de la solicitud se ignora (se sobrescribe a `false`); las transacciones de desbloqueo nunca están pendientes. El endpoint acepta el mismo cuerpo que el endpoint de creación JSON. parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LedgerId' - $ref: '#/components/parameters/ContentType' - $ref: '#/components/parameters/XRequestId' - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/XIdempotency' - $ref: '#/components/parameters/XTTL' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTransactionRequest' example: chartOfAccountsGroupName: FUNDING description: Liberar fondos previamente bloqueados code: UNB-2026-001 transactionDate: '2026-06-23T12:00:00Z' metadata: reason: investigación finalizada channel: api send: asset: BRL value: '1000' source: from: - accountAlias: '@source-account' balanceKey: default amount: asset: BRL value: '1000' description: Débito en la cuenta de origen distribute: to: - accountAlias: '@destination-account' balanceKey: default remaining: remaining description: Crédito en la cuenta de destino responses: '201': description: >- Indica que el recurso fue creado exitosamente y la operación se completó como se esperaba. La respuesta incluye el header `X-Idempotency-Replayed`. Si el valor es false, la transacción fue recién procesada. Si el valor es true, la respuesta es una repetición de una solicitud procesada anteriormente. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. headers: X-Idempotency-Replayed: $ref: '#/components/headers/XIdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/CreateTransactionResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0073: $ref: '#/components/examples/Error0073' headers: {} '401': description: No autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Prohibido content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0043: $ref: '#/components/examples/Error0043' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0105: $ref: '#/components/examples/Error0105' headers: {} '409': description: >- Conflicto — la clave de idempotencia ya está en uso por una solicitud que aún se está procesando. El header `X-Idempotency-Replayed` se incluye en la respuesta y se establece en `false`. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. headers: X-Idempotency-Replayed: $ref: '#/components/headers/XIdempotencyReplayed' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0084: $ref: '#/components/examples/Error0084' '422': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0018: $ref: '#/components/examples/Error0018' Error0019: $ref: '#/components/examples/Error0019' headers: {} '500': description: Error Interno del Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: El identificador único de la Organización asociada al Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: El identificador único del Ledger asociado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid ContentType: name: Content-Type in: header description: >- El tipo de medio del recurso. El valor recomendado es `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: Un identificador único utilizado para rastrear y seguir cada solicitud. required: false example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid Authorization: name: Authorization in: header required: false schema: type: string description: > Token JWT bearer para autenticación. Requerido cuando `PLUGIN_AUTH_ENABLED=true` (obligatorio en despliegues multiinquilino). Opcional en el modo OSS de inquilino único predeterminado. Formato: `Bearer ` XIdempotency: name: X-Idempotency in: header description: >- Una clave única que garantiza la idempotencia de la transacción. Si no se proporciona, el sistema genera automáticamente un hash SHA-256 basado en el cuerpo de la solicitud. Las claves están delimitadas por organización y ledger. Siempre valide el header de respuesta `X-Idempotency-Replayed` para distinguir transacciones nuevas de reproducciones en caché. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para mejores prácticas. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string XTTL: name: X-TTL in: header description: >- El tiempo de vida (TTL) de la clave de idempotencia, definido en segundos. Si no se proporciona, el valor predeterminado es 300 segundos (5 minutos). Solo se usa el TTL de la primera solicitud; cambiarlo en reintentos no tiene efecto. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. required: false example: 3600 schema: type: integer schemas: CreateTransactionRequest: type: object nullable: true properties: chartOfAccountsGroupName: type: string maxLength: 256 description: El nombre del grupo del plan de cuentas asociado a la transacción. description: type: string maxLength: 256 description: Una descripción para la transacción. pending: type: boolean description: >- Indica si la transacción debe seguir un proceso de dos pasos: autorización seguida de ejecución. Cuando se establece en **true**, la transacción se crea en estado pendiente, reservando fondos (`on_hold`) sin moverlos de inmediato. Se requiere una confirmación posterior para finalizar la transferencia. default: false code: type: string maxLength: 100 description: Código de transacción para referencia. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` en su lugar. Identificador heredado de la ruta mantenido por compatibilidad; se acepta pero no se utiliza en la validación de enrutamiento. routeId: type: string format: uuid description: >- El identificador único (UUID) de la Ruta de Transacción asociada a esta transacción. **Importante:** Cuando la validación de Enrutamiento de Transacciones está habilitada para su Ledger, este campo se vuelve **obligatorio** y debe coincidir con un `id` existente de sus [Rutas de Transacción](/es/reference/midaz/create-transaction-route) configuradas. Sin embargo, cuando la validación está deshabilitada (comportamiento predeterminado), este campo es **opcional**. transactionDate: type: string description: >- La fecha y hora en que se realizó la transacción. Se utiliza para agregar transacciones pasadas. **Debe ser una fecha en el pasado**. send: type: object description: >- Un objeto que contiene información sobre la transacción que se enviará. required: - asset - value - source - distribute properties: asset: type: string description: El código que identifica el activo que se enviará. value: type: string description: >- El monto que se enviará. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. source: $ref: '#/components/schemas/SourceRequest' distribute: $ref: '#/components/schemas/DistributeRequest' metadata: $ref: '#/components/schemas/Metadata' CreateTransactionResponse: type: object properties: id: type: string description: El identificador único de la transacción. format: uuid parentTransactionId: type: string description: >- El identificador único de la transacción padre/original para reversiones. Este campo es completado por el servidor cuando una transacción es revertida y debe ser tratado como solo lectura por los clientes. format: uuid nullable: true organizationId: type: string format: uuid description: El identificador único de la Organización. ledgerId: type: string description: El identificador único del Ledger. format: uuid description: type: string description: Descripción de la transacción. route: type: string description: Especifica la Ruta de Transacción asociada a la transacción. routeId: type: string format: uuid description: >- El identificador único de la Ruta de Transacción aplicada a esta transacción. status: type: object description: El estado de la transacción (pendiente, completada, revertida). properties: code: type: string description: Código de estado de la transacción. description: type: string description: Descripción del estado de la transacción. amount: type: string description: El monto enviado. assetCode: type: string description: El nombre del activo utilizado en la operación. chartOfAccountsGroupName: type: string description: El nombre del grupo del plan de cuentas. source: type: array description: La lista de cuentas utilizadas como origen. items: type: string destination: type: array description: La lista de cuentas utilizadas como destino. items: type: string createdAt: type: string format: date-time description: Fecha y hora de creación (UTC). updatedAt: type: string format: date-time description: Fecha y hora de la última actualización (UTC). deletedAt: type: string format: date-time description: Fecha y hora de la eliminación lógica, si aplica (UTC). nullable: true operations: type: array items: $ref: '#/components/schemas/OperationResponse' metadata: $ref: '#/components/schemas/Metadata' ErrorFormat: type: object description: El mensaje de error de respuesta. required: - code - title - message properties: code: type: string description: Un identificador único y estable para el error. title: type: string description: Un breve resumen del problema. message: type: string description: Orientación detallada para resolver el error. entityType: type: string description: >- El tipo de entidad a la que se refiere el error (p. ej. organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Información adicional sobre los campos que causaron el error. SourceRequest: type: object required: - from description: Un objeto que contiene información sobre las cuentas de origen. properties: remaining: type: string description: >- Especifica cómo manejar cualquier monto restante a nivel de origen después de procesar todas las entradas `from`. from: type: array description: >- La lista de cuentas que se utilizarán como origen. Cada entrada del arreglo debe incluir uno de los siguientes campos: `amount`, `share` o `remaining`. Si una entrada incluye más de uno de estos campos, se producirá un error. minItems: 1 items: type: object properties: accountAlias: type: string description: El alias de la cuenta utilizada en la operación. balanceKey: type: string description: >- La clave identificadora única del saldo de la cuenta. Si se omite, se utiliza el saldo `default`. Use una [clave creada previamente](https://docs.lerian.studio/es/reference/midaz/create-a-balance) para dirigir los fondos a un saldo específico. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` en su lugar. Identificador heredado de la ruta mantenido por compatibilidad; se acepta pero no se utiliza en la validación de enrutamiento. routeId: type: string format: uuid description: >- El identificador único (UUID) de la Ruta de Transacción asociada a esta transacción. **Importante:** Cuando la validación de Enrutamiento de Transacciones está habilitada para su Ledger, este campo se vuelve **obligatorio** y debe coincidir con un `id` existente de sus [Rutas de Transacción](/es/reference/midaz/create-transaction-route) configuradas. Sin embargo, cuando la validación está deshabilitada (comportamiento predeterminado), este campo es **opcional**. amount: $ref: '#/components/schemas/SendAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- El monto o porcentaje restante. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. rate: type: object description: >- La tasa de cambio a aplicar cuando la transacción involucra activos diferentes. properties: from: type: string description: El código del activo de origen para la tasa de cambio. to: type: string description: El código del activo de destino para la tasa de cambio. value: type: string description: >- El valor de la tasa de cambio. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. externalId: type: string format: uuid description: El identificador externo de la tasa de cambio. description: type: string description: Una descripción para la operación. chartOfAccounts: type: string deprecated: true description: El nombre del Plan de Cuentas al que pertenece la operación. metadata: $ref: '#/components/schemas/Metadata' DistributeRequest: type: object required: - to description: >- Un objeto que contiene la información de la cuenta a la que se transferirá el monto. properties: remaining: type: string description: >- Especifica cómo manejar cualquier monto restante a nivel de distribución después de procesar todas las entradas `to`. to: type: array description: >- Una lista de las cuentas a las que se transferirá el monto. Cada entrada del arreglo debe incluir uno de los siguientes campos: `amount`, `share` o `remaining`. Si una entrada incluye más de uno de estos campos, se producirá un error. minItems: 1 items: type: object properties: accountAlias: type: string description: >- El identificador único o el alias de la cuenta que recibirá el monto. balanceKey: type: string description: >- La clave identificadora única del saldo de la cuenta. Si se omite, se utiliza el saldo `default`. Use una [clave creada previamente](https://docs.lerian.studio/es/reference/midaz/create-a-balance) para dirigir los fondos a un saldo específico. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` en su lugar. Identificador heredado de la ruta mantenido por compatibilidad; se acepta pero no se utiliza en la validación de enrutamiento. routeId: type: string format: uuid description: >- El identificador único (UUID) de la Ruta de Transacción asociada a esta transacción. **Importante:** Cuando la validación de Enrutamiento de Transacciones está habilitada para su Ledger, este campo se vuelve **obligatorio** y debe coincidir con un `id` existente de sus [Rutas de Transacción](/es/reference/midaz/create-transaction-route) configuradas. Sin embargo, cuando la validación está deshabilitada (comportamiento predeterminado), este campo es **opcional**. amount: $ref: '#/components/schemas/DistributeAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- El monto o porcentaje restante. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. rate: type: object description: >- La tasa de cambio a aplicar cuando la transacción involucra activos diferentes. properties: from: type: string description: El código del activo de origen para la tasa de cambio. to: type: string description: El código del activo de destino para la tasa de cambio. value: type: string description: >- El valor de la tasa de cambio. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. externalId: type: string format: uuid description: El identificador externo de la tasa de cambio. description: type: string description: Una descripción para la operación. chartOfAccounts: type: string deprecated: true description: El nombre del Plan de Cuentas al que pertenece la operación. metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- Un objeto que contiene pares clave-valor para agregar como metadatos, donde el campo `name` es la clave y el campo `value` es el valor. Por ejemplo, para agregar un Centro de Costo, use `'costCenter': 'BR_11101997'`. **Restricciones:** las claves deben tener como máximo 100 caracteres; los valores de cadena de texto, como máximo 2000 caracteres. No se permiten objetos anidados (los valores deben ser cadena de texto, número o booleano), la estructura no puede exceder una profundidad máxima de 10, y se permite un máximo de 100 claves. OperationResponse: type: object properties: id: type: string description: El identificador único de la Operación. format: uuid transactionId: type: string format: uuid description: El identificador único de la Transacción. organizationId: type: string format: uuid description: El identificador único de la Organización. ledgerId: type: string description: El identificador único del Ledger. format: uuid accountId: type: string description: El identificador único de la Cuenta. format: uuid accountAlias: type: string description: El alias de la cuenta utilizada en la operación. balanceId: type: string description: El identificador único del Saldo. balanceKey: type: string description: El identificador de clave del Saldo. description: type: string description: Una descripción para la operación. type: type: string description: >- El tipo de la operación. `OVERDRAFT` identifica operaciones companion generadas por el sistema en el saldo interno `"overdraft"` — `direction` lleva entonces la semántica del ciclo de vida (`debit` para un draw, `credit` para un reembolso). `BLOCK` y `UNBLOCK` identifican operaciones producidas por los endpoints de transacción de bloqueo/desbloqueo; `direction` sigue llevando la semántica de débito/crédito. enum: - CREDIT - DEBIT - ON_HOLD - RELEASE - OVERDRAFT - BLOCK - UNBLOCK assetCode: type: string description: El código que identifica el activo enviado. chartOfAccounts: type: string description: El nombre del Plan de Cuentas al que pertenece la operación. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` en su lugar. Se eliminará en la próxima versión mayor. routeId: type: string format: uuid description: >- El identificador único de la ruta de operación asociada a esta operación. Las operaciones companion de overdraft heredan este valor de la operación primaria que las generó. routeCode: type: string maxLength: 100 description: >- Un código legible de la ruta de operación, útil para auditoría y rastreabilidad. routeDescription: type: string description: La descripción de la ruta de operación asociada a esta operación. direction: type: string enum: - debit - credit description: La dirección de la operación en la contabilidad de partida doble. amount: type: object description: >- Un objeto que contiene información sobre el monto utilizado en la operación. properties: value: type: string description: El monto que se enviará. balance: type: object description: >- Un objeto que contiene información sobre el saldo antes de la operación. properties: available: type: string description: Saldo disponible anterior. onHold: type: string description: Monto retenido/reservado. version: type: integer description: Versión del saldo, que se actualiza con cada transacción. overdraftUsed: type: string description: >- El overdraft consumido por este saldo antes de la operación, como string decimal. `"0"` para operaciones que no tocan el overdraft. balanceAfter: type: object description: >- Un objeto que contiene información sobre el saldo después de la operación. properties: available: type: string description: Saldo disponible actual. onHold: type: string description: Monto retenido/reservado. version: type: integer description: Versión del saldo, que se actualiza con cada transacción. overdraftUsed: type: string description: >- El overdraft consumido por este saldo después de la operación, como string decimal. `"0"` para operaciones que no tocan el overdraft. status: type: object description: El estado de la transacción (pendiente, completada, revertida). properties: code: type: string description: Código de estado de la transacción. description: type: string description: Descripción del estado de la transacción. nullable: true balanceAffected: type: boolean description: Indica si la operación tuvo impacto en el saldo de la cuenta. createdAt: type: string format: date-time description: Fecha y hora de creación (UTC). updatedAt: type: string format: date-time description: Fecha y hora de la última actualización (UTC). deletedAt: type: string format: date-time description: Fecha y hora de la eliminación lógica, si aplica (UTC). nullable: true metadata: $ref: '#/components/schemas/Metadata' SendAmountRequest: type: object required: - asset - value description: >- Un objeto que contiene información sobre el monto que se utilizará en la operación. properties: asset: type: string description: El nombre del activo utilizado en la operación. value: type: string description: >- El monto que se enviará. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. SendShareRequest: type: object description: >- Si distintas cuentas forman parte de la operación, este objeto contendrá la información sobre el porcentaje utilizado para cada cuenta. properties: percentage: type: string description: >- El porcentaje que se compartirá. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. percentageOfPercentage: type: integer description: >- El porcentaje del porcentaje que se compartirá. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. DistributeAmountRequest: type: object required: - asset - value description: >- Un objeto que contiene información sobre el monto utilizado en la operación. properties: asset: type: string description: El nombre del activo utilizado en la operación. value: type: string description: >- El monto que se recibirá. **Importante:** Use un punto (`.`) como separador decimal — las comas no son aceptadas. headers: XIdempotencyReplayed: description: >- Indica si la respuesta fue reproducida desde caché (`true`) o es una respuesta nueva de una transacción recién procesada (`false`). Siempre verifique este header para evitar procesar la misma transacción dos veces de su lado. Consulte [Reintentos e idempotencia](/es/reference/retries-idempotency) para más detalles. schema: type: boolean example: false examples: Error0073: value: code: '0073' title: Transaction Value Mismatch message: >- The values for the source, the destination, or both do not match the specified transaction amount. Please verify the values and try again. summary: Transaction Value Mismatch Error0041: summary: Token Missing value: code: '0041' title: Token Missing message: >- A valid token must be provided in the request header. Please include a token and try again. Error0042: summary: Invalid Token value: code: '0042' title: Invalid Token message: >- The provided token is expired, invalid or malformed. Please provide a valid token and try again. Error0043: summary: Insufficient Privileges value: code: '0043' title: Insufficient Privileges message: >- You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error. Error0105: value: code: '0105' title: Transaction Route Not Found message: >- The provided transaction route does not exist in our records. Please verify the transaction route and try again. summary: Transaction Route Not Found Error0084: value: code: 84 title: Duplicate Idempotency Key message: >- The idempotency key '{{key}}' is already in use and the original request is still being processed. Please retry later using the same idempotency key. summary: Duplicate Idempotency Key Error0018: value: code: 18 title: Insufficient Funds Error message: >- The transaction could not be completed due to insufficient funds in the account. Please add sufficient funds to your account and try again. summary: Insufficient Funds Error0019: value: code: 19 title: Account Ineligibility Error message: >- One or more accounts listed in the transaction are not eligible to participate. Please review the account statuses and try again. summary: Account Ineligibility Error0046: summary: Internal Server Error value: code: '0046' title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later or contact support. ````