> ## 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. # Criar uma Transação de Desbloqueio > Use este endpoint para criar uma transação cujas operações resultantes são do tipo `UNBLOCK`. O Midaz é agnóstico quanto ao motivo de negócio para desbloquear fundos — use o campo `metadata` para registrá-lo. Este endpoint sempre cria uma transação confirmada imediatamente e não pendente: o campo `pending` do corpo da requisição é ignorado (sobrescrito para `false`); transações de desbloqueio nunca ficam pendentes. O endpoint aceita o mesmo corpo que o endpoint de criação JSON. ## OpenAPI ````yaml pt/openapi/v3-current/ledger.yaml post /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock openapi: 3.1.0 info: title: API Midaz Ledger description: >- Referência completa da API para serviços do Midaz Ledger incluindo gerenciamento de organizações, operações de ledger, ativos, segmentos, portfolios, contas, tipos de conta, transações, operações, saldos, rotas de operação, rotas de transação e índices de metadata. version: 3.7.8 servers: - url: https://ledger.sandbox.lerian.net security: [] tags: - name: API de Organizações - name: API de Ledgers - name: API de Ativos - name: API de Segmentos - name: API de Portfolios - name: API de Tipos de Conta - name: API de Contas - name: API de Saldos - name: API de Transações - name: API de Operações - name: API de Rotas de Operação - name: API de Rotas de Transação - name: API de Índices de Metadata paths: /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/unblock: post: tags: - API de Transações summary: Criar uma Transação de Desbloqueio description: >- Use este endpoint para criar uma transação cujas operações resultantes são do tipo `UNBLOCK`. O Midaz é agnóstico quanto ao motivo de negócio para desbloquear fundos — use o campo `metadata` para registrá-lo. Este endpoint sempre cria uma transação confirmada imediatamente e não pendente: o campo `pending` do corpo da requisição é ignorado (sobrescrito para `false`); transações de desbloqueio nunca ficam pendentes. O endpoint aceita o mesmo corpo que o endpoint de criação 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 fundos previamente bloqueados code: UNB-2026-001 transactionDate: '2026-06-23T12:00:00Z' metadata: reason: investigação concluída channel: api send: asset: BRL value: '1000' source: from: - accountAlias: '@source-account' balanceKey: default amount: asset: BRL value: '1000' description: Débito na conta de origem distribute: to: - accountAlias: '@destination-account' balanceKey: default remaining: remaining description: Crédito na conta de destino responses: '201': description: >- Indica que o recurso foi criado com sucesso e a operação foi concluída conforme esperado. A resposta inclui o header `X-Idempotency-Replayed`. Se o valor for false, a transação foi recém-processada. Se o valor for true, a resposta é uma repetição de uma requisição processada anteriormente. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes. 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: Não autorizado content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0041: $ref: '#/components/examples/Error0041' Error0042: $ref: '#/components/examples/Error0042' '403': description: Proibido 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: >- Conflito — a chave de idempotência já está em uso por uma requisição que ainda está sendo processada. O header `X-Idempotency-Replayed` é incluído na resposta e definido como `false`. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes. 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: Erro Interno do Servidor content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' examples: Error0046: $ref: '#/components/examples/Error0046' components: parameters: OrganizationId: name: organization_id in: path description: O identificador único da Organização associada ao Ledger. required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string format: uuid LedgerId: name: ledger_id in: path description: O identificador único do Ledger associado. required: true example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a schema: type: string format: uuid ContentType: name: Content-Type in: header description: O tipo de mídia do recurso. O valor recomendado é `application/json`. required: false example: application/json schema: type: string XRequestId: name: X-Request-Id in: header description: >- Um identificador único utilizado para rastrear e acompanhar cada requisição. 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 autenticação. Obrigatório quando `PLUGIN_AUTH_ENABLED=true` (exigido em implantações multi-tenant). Opcional no modo OSS single-tenant padrão. Formato: `Bearer ` XIdempotency: name: X-Idempotency in: header description: >- Uma chave única que garante a idempotência da transação. Se não fornecida, o sistema gera automaticamente um hash SHA-256 com base no corpo da requisição. As chaves são escopadas por organização e ledger. Sempre valide o header de resposta `X-Idempotency-Replayed` para distinguir transações novas de replays em cache. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para boas práticas. required: false example: 019c96a0-10ce-75fc-a273-dc799079a99c schema: type: string XTTL: name: X-TTL in: header description: >- O tempo de vida (TTL) da chave de idempotência, definido em segundos. Se não fornecido, o padrão é 300 segundos (5 minutos). Apenas o TTL da primeira requisição é utilizado; alterá-lo em retentativas não tem efeito. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes. required: false example: 3600 schema: type: integer schemas: CreateTransactionRequest: type: object nullable: true properties: chartOfAccountsGroupName: type: string maxLength: 256 description: O nome do grupo do plano de contas associado à transação. description: type: string maxLength: 256 description: Uma descrição para a transação. pending: type: boolean description: >- Indica se a transação deve seguir um processo em duas etapas: autorização seguida de execução. Quando definido como **true**, a transação é criada em estado pendente, reservando fundos (`on_hold`) sem movê-los imediatamente. Um commit subsequente é necessário para finalizar a transferência. default: false code: type: string maxLength: 100 description: Código da transação para referência. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` em vez disso. Identificador legado da rota mantido por compatibilidade; é aceito mas não é utilizado na validação de roteamento. routeId: type: string format: uuid description: >- O identificador único (UUID) da Rota de Transação associada a esta transação. **Importante:** Quando a validação de Rota de Transação está habilitada para o seu Ledger, este campo se torna **obrigatório** e deve corresponder a um `id` existente das suas [Rotas de Transação](/pt/reference/midaz/create-transaction-route) configuradas. No entanto, quando a validação está desabilitada (comportamento padrão), este campo é **opcional**. transactionDate: type: string description: >- A data em que a transação foi realizada. Usado para adicionar transações passadas. **Deve ser uma data no passado**. send: type: object description: Um objeto contendo informações sobre a transação que será enviada. required: - asset - value - source - distribute properties: asset: type: string description: O código que identifica o ativo que será enviado. value: type: string description: >- O valor que será enviado. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. source: $ref: '#/components/schemas/SourceRequest' distribute: $ref: '#/components/schemas/DistributeRequest' metadata: $ref: '#/components/schemas/Metadata' CreateTransactionResponse: type: object properties: id: type: string description: O identificador único da transação. format: uuid parentTransactionId: type: string description: >- O identificador único da transação pai/original para reversões. Este campo é preenchido pelo servidor quando uma transação é revertida e deve ser tratado como somente leitura pelos clientes. format: uuid nullable: true organizationId: type: string format: uuid description: O identificador único da Organização. ledgerId: type: string description: O identificador único do Ledger. format: uuid description: type: string description: Descrição da transação. route: type: string description: Especifica a Rota de Transação associada à transação. routeId: type: string format: uuid description: >- O identificador único da Rota de Transação aplicada a esta transação. status: type: object description: O status da transação (pendente, concluída, revertida). properties: code: type: string description: Código de status da transação. description: type: string description: Descrição do status da transação. amount: type: string description: O valor enviado. assetCode: type: string description: O nome do ativo utilizado na operação. chartOfAccountsGroupName: type: string description: O nome do grupo do plano de contas. source: type: array description: A lista de contas utilizadas como origem. items: type: string destination: type: array description: A lista de contas utilizadas como destino. items: type: string createdAt: type: string format: date-time description: Data e hora de criação (UTC). updatedAt: type: string format: date-time description: Data e hora da última atualização (UTC). deletedAt: type: string format: date-time description: Data e hora da exclusão lógica, se aplicável (UTC). nullable: true operations: type: array items: $ref: '#/components/schemas/OperationResponse' metadata: $ref: '#/components/schemas/Metadata' ErrorFormat: type: object description: A mensagem de erro da resposta. required: - code - title - message properties: code: type: string description: Um identificador único e estável para o erro. title: type: string description: Um breve resumo do problema. message: type: string description: Orientação detalhada para resolver o erro. entityType: type: string description: >- O tipo de entidade ao qual o erro se refere (por exemplo, organization, ledger, account, transaction). Opcional. fields: type: object additionalProperties: true description: Informações adicionais sobre os campos que causaram o erro. SourceRequest: type: object required: - from description: Um objeto contendo informações sobre as contas de origem. properties: remaining: type: string description: >- Especifica como lidar com qualquer valor restante no nível da origem após o processamento de todas as entradas `from`. from: type: array description: >- A lista de contas que serão utilizadas como origem. Cada entrada no array deve incluir um dos seguintes campos: `amount`, `share` ou `remaining`. Se uma entrada incluir mais de um desses campos, um erro ocorrerá. minItems: 1 items: type: object properties: accountAlias: type: string description: O alias da conta utilizada na operação. balanceKey: type: string description: >- A chave identificadora única do saldo da conta. Se omitido, o saldo `default` é utilizado. Use uma [chave previamente criada](https://docs.lerian.studio/pt/reference/midaz/create-a-balance) para direcionar fundos para um saldo específico. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` em vez disso. Identificador legado da rota mantido por compatibilidade; é aceito mas não é utilizado na validação de roteamento. routeId: type: string format: uuid description: >- O identificador único (UUID) da Rota de Transação associada a esta transação. **Importante:** Quando a validação de Rota de Transação está habilitada para o seu Ledger, este campo se torna **obrigatório** e deve corresponder a um `id` existente das suas [Rotas de Transação](/pt/reference/midaz/create-transaction-route) configuradas. No entanto, quando a validação está desabilitada (comportamento padrão), este campo é **opcional**. amount: $ref: '#/components/schemas/SendAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- O valor ou percentual restante. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. rate: type: object description: >- A taxa de câmbio a ser aplicada quando a transação envolve ativos diferentes. properties: from: type: string description: O código do ativo de origem para a taxa de câmbio. to: type: string description: O código do ativo de destino para a taxa de câmbio. value: type: string description: >- O valor da taxa de câmbio. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. externalId: type: string format: uuid description: O identificador externo da taxa de câmbio. description: type: string description: Uma descrição para a operação. chartOfAccounts: type: string deprecated: true description: O nome do Plano de Contas ao qual a operação pertence. metadata: $ref: '#/components/schemas/Metadata' DistributeRequest: type: object required: - to description: >- Um objeto contendo as informações da conta para a qual o valor será transferido. properties: remaining: type: string description: >- Especifica como lidar com qualquer valor restante no nível de distribuição após o processamento de todas as entradas `to`. to: type: array description: >- Uma lista das contas para as quais o valor será transferido. Cada entrada no array deve incluir um dos seguintes campos: `amount`, `share` ou `remaining`. Se uma entrada incluir mais de um desses campos, um erro ocorrerá. minItems: 1 items: type: object properties: accountAlias: type: string description: >- O identificador único ou o alias da conta que receberá o valor. balanceKey: type: string description: >- A chave identificadora única do saldo da conta. Se omitido, o saldo `default` é utilizado. Use uma [chave previamente criada](https://docs.lerian.studio/pt/reference/midaz/create-a-balance) para direcionar fundos para um saldo específico. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` em vez disso. Identificador legado da rota mantido por compatibilidade; é aceito mas não é utilizado na validação de roteamento. routeId: type: string format: uuid description: >- O identificador único (UUID) da Rota de Transação associada a esta transação. **Importante:** Quando a validação de Rota de Transação está habilitada para o seu Ledger, este campo se torna **obrigatório** e deve corresponder a um `id` existente das suas [Rotas de Transação](/pt/reference/midaz/create-transaction-route) configuradas. No entanto, quando a validação está desabilitada (comportamento padrão), este campo é **opcional**. amount: $ref: '#/components/schemas/DistributeAmountRequest' share: $ref: '#/components/schemas/SendShareRequest' remaining: type: string description: >- O valor ou percentual restante. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. rate: type: object description: >- A taxa de câmbio a ser aplicada quando a transação envolve ativos diferentes. properties: from: type: string description: O código do ativo de origem para a taxa de câmbio. to: type: string description: O código do ativo de destino para a taxa de câmbio. value: type: string description: >- O valor da taxa de câmbio. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. externalId: type: string format: uuid description: O identificador externo da taxa de câmbio. description: type: string description: Uma descrição para a operação. chartOfAccounts: type: string deprecated: true description: O nome do Plano de Contas ao qual a operação pertence. metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object additionalProperties: oneOf: - type: string maxLength: 2000 - type: number - type: boolean description: >- Um objeto contendo pares de chave-valor para adicionar como metadata, onde o campo `name` é a chave e o campo `value` é o valor. Por exemplo, para adicionar um Centro de Custo, use `'costCenter': 'BR_11101997'`. **Restrições:** as chaves devem ter no máximo 100 caracteres; valores de string no máximo 2000 caracteres. Objetos aninhados não são permitidos (os valores devem ser string, número ou booleano), a estrutura não pode exceder uma profundidade máxima de 10, e é permitido um máximo de 100 chaves. OperationResponse: type: object properties: id: type: string description: O identificador único da Operação. format: uuid transactionId: type: string format: uuid description: O identificador único da Transação. organizationId: type: string format: uuid description: O identificador único da Organização. ledgerId: type: string description: O identificador único do Ledger. format: uuid accountId: type: string description: O identificador único da Conta. format: uuid accountAlias: type: string description: O alias da conta utilizada na operação. balanceId: type: string description: O identificador único do Saldo. balanceKey: type: string description: O identificador chave do Saldo. description: type: string description: Uma descrição para a operação. type: type: string description: >- O tipo da operação. `OVERDRAFT` identifica operações companion geradas pelo sistema no saldo interno `"overdraft"` — `direction` carrega então a semântica do ciclo de vida (`debit` para um draw, `credit` para um reembolso). `BLOCK` e `UNBLOCK` identificam operações produzidas pelos endpoints de transação de block/unblock; `direction` continua carregando a semântica de débito/crédito. enum: - CREDIT - DEBIT - ON_HOLD - RELEASE - OVERDRAFT - BLOCK - UNBLOCK assetCode: type: string description: O código que identifica o ativo enviado. chartOfAccounts: type: string description: O nome do Plano de Contas ao qual a operação pertence. route: type: string deprecated: true description: >- **Obsoleto.** Use `routeId` no lugar. Será removido na próxima versão major. routeId: type: string format: uuid description: >- O identificador único da rota de operação associada a esta operação. Operações companion de overdraft herdam esse valor da operação primária que as gerou. routeCode: type: string maxLength: 100 description: >- Um código legível da rota de operação, útil para auditoria e rastreabilidade. routeDescription: type: string description: A descrição da rota de operação associada a esta operação. direction: type: string enum: - debit - credit description: A direção da operação na contabilidade de partida dobrada. amount: type: object description: Um objeto contendo informações sobre o valor utilizado na operação. properties: value: type: string description: O valor que será enviado. balance: type: object description: Um objeto contendo informações sobre o saldo antes da operação. properties: available: type: string description: Saldo disponível anterior. onHold: type: string description: Valor retido/reservado. version: type: integer description: Versão do saldo, que é atualizada a cada transação. overdraftUsed: type: string description: >- O overdraft consumido por este saldo antes da operação, como string decimal. `"0"` para operações que não tocam o overdraft. balanceAfter: type: object description: Um objeto contendo informações sobre o saldo após a operação. properties: available: type: string description: Saldo disponível atual. onHold: type: string description: Valor retido/reservado. version: type: integer description: Versão do saldo, que é atualizada a cada transação. overdraftUsed: type: string description: >- O overdraft consumido por este saldo após a operação, como string decimal. `"0"` para operações que não tocam o overdraft. status: type: object description: O status da transação (pendente, concluída, revertida). properties: code: type: string description: Código de status da transação. description: type: string description: Descrição do status da transação. nullable: true balanceAffected: type: boolean description: Indica se a operação teve impacto no saldo da conta. createdAt: type: string format: date-time description: Data e hora de criação (UTC). updatedAt: type: string format: date-time description: Data e hora da última atualização (UTC). deletedAt: type: string format: date-time description: Data e hora da exclusão lógica, se aplicável (UTC). nullable: true metadata: $ref: '#/components/schemas/Metadata' SendAmountRequest: type: object required: - asset - value description: >- Um objeto contendo informações sobre o valor que será utilizado na operação. properties: asset: type: string description: O nome do ativo utilizado na operação. value: type: string description: >- O valor que será enviado. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. SendShareRequest: type: object description: >- Se diferentes contas fazem parte da operação, este objeto conterá as informações sobre o percentual utilizado para cada conta. properties: percentage: type: string description: >- O percentual que será compartilhado. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. percentageOfPercentage: type: integer description: >- O percentual do percentual que será compartilhado. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. DistributeAmountRequest: type: object required: - asset - value description: Um objeto contendo informações sobre o valor utilizado na operação. properties: asset: type: string description: O nome do ativo utilizado na operação. value: type: string description: >- O valor que será recebido. **Importante:** Use um ponto (`.`) como separador decimal — vírgulas não são aceitas. headers: XIdempotencyReplayed: description: >- Indica se a resposta foi reproduzida a partir do cache (`true`) ou é uma resposta nova de uma transação recém-processada (`false`). Sempre verifique este header para evitar processar a mesma transação duas vezes do seu lado. Consulte [Retentativas e idempotência](/pt/reference/retries-idempotency) para mais detalhes. 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: '0084' 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: '0018' 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: '0019' 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. ````