Desbloqueio de saldo

Visão Geral

A API de Desbloqueio de Saldo permite realizar a liberação total ou parcial de valores previamente bloqueados na conta do cliente, transferindo o montante desbloqueado do saldo bloqueado para o saldo disponível.

A funcionalidade está disponível para clientes dos modelos BaaS e Core Banking, garantindo flexibilidade operacional, rastreabilidade e consistência contábil no gerenciamento de valores bloqueados.

Após a confirmação do desbloqueio, o valor torna-se imediatamente disponível para transações que utilizem saldo disponível.

Esta API foi projetada para permitir a reversão controlada de bloqueios de saldo previamente realizados, suportando diferentes cenários operacionais, tais como: Liberação de bloqueios judiciais, finalização de garantias operacionais, reversões antifraude, decisões comerciais, ajustes operacionais, etc.

Passos para Integrar

1. Realizar autenticação na API - [API Reference]
2. Realizar um desbloqueio de saldo - [API Reference]

📘

Informações importantes:

1. Regras gerais:

• Para realizar um desbloqueio, deve existir previamente um bloqueio válido registrado na conta.
• O desbloqueio deve estar obrigatoriamente vinculado a um bloqueio existente, identificado por meio do campo correlationBlockedId;
• O valor solicitado para desbloqueio deve ser menor ou igual ao saldo atualmente bloqueado para o respectivo correlationBlockedId;
• Ao realizar um desbloqueio com sucesso:
  • O valor é removido do saldo bloqueado;
  • O valor é retornado ao saldo disponível da conta;
  • A operação permanece vinculada ao bloqueio original para fins de rastreabilidade;
  • Um webhook de confirmação é enviado ao cliente.
• O desbloqueio não altera o status cadastral da conta, impactando exclusivamente a disponibilidade do saldo.

2. Tipos de Desbloqueio Suportados:

• Desbloqueio Total:
  • Realiza a liberação integral dos valores vinculados ao bloqueio original.
  • Regras:
    • Enviar no request o campo unBlockAll = true;
    • Não é necessário informar o campo amount;
  • O sistema irá liberar automaticamente todo o saldo ainda bloqueado vinculado ao correlationBlockedId informado.
• Desbloqueio Parcial:
  • Realiza a liberação de parte do valor previamente bloqueado, mantendo o saldo remanescente ainda bloqueado
  • Regras:
    • Enviar no request o campo unBlockAll = false;
    • O campo amount torna-se obrigatório e o valor informado deve ser:
      • Maior que R$ 0,01
      • Menor ou igual ao saldo bloqueado disponível para o correlationBlockedId
  • É permitido realizar múltiplos desbloqueios parciais para o mesmo correlationBlockedId, até que o valor total bloqueado seja completamente liberado.

3. Rastreabilidade e Auditoria

• O campo clientRequestId garante idempotência e rastreabilidade da operação;

  • Requisições com o mesmo clientRequestId serão rejeitadas caso já tenham sido processadas;
  • Recomenda-se o uso de UUID único para cada nova operação.

• O envio do correlationBlockedId é obrigatório na requisição de desbloqueio:

  • Esse campo identifica o bloqueio original;
  • Garante a correta conciliação entre o bloqueio e seu(s) respectivo(s) desbloqueio(s);
  • Permite auditoria completa do tempo em que os valores ficaram retidos na conta e o controle dos desbloqueios realizados;

Campos do Request

Exemplo de request

{
  "clientRequestId": "29bbf354-e33e-4e42-b5b9-ac982377ffb4",
  "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
  "reason": "DESBLOQUEIO JUDICIAL",
  "description": "desbloqueio de saldo",
  "unBlockAll": true,
  "amount": 0.01
}

cURL da chamada

Exemplo 1: Desbloqueio Total

curl --location 'https://kubernetes-prod.celcoin.dev/sandbox-baas-wallet-transactions-webservice/wallet/30023646094074/balance/unblock' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --data '{
    "clientRequestId": "29bbf354-e33e-4e42-b5b9-ac982377ffb4",
    "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "reason": "DESBLOQUEIO CLIENTE",
    "description": "Desbloqueio total de saldo",
    "unBlockAll": true
  }'

Exemplo 1: Desbloqueio Parcial

curl --location 'https://kubernetes-prod.celcoin.dev/sandbox-baas-wallet-transactions-webservice/wallet/30023646094074/balance/unblock' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --data '{
    "clientRequestId": "29bbf354-e33e-4e42-b5b9-ac982377ffb4",
    "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "reason": "DESBLOQUEIO PARCIAL",
    "description": "Liberação parcial de garantia",
    "unBlockAll": false,
    "amount": 0.01
  }'

Exemplo de retorno

👍

Sucesso 200

{
  "status": "CONFIRMED",
  "version": "1.0.0",
  "body": {
    "id": "a4dee906-00b4-4a28-a084-9f0e900fad06",
    "unlockedAmount": 0.01,
    "clientRequestId": "954c192e-85fb-48b9-ae32-5e2fc9e2f5fe",
    "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "clientRequestIdOriginal": [
      "a4bbc5b0-dd62-4d87-ab29-19564b8e7955"
    ],
    "debitParty": {
      "account": "30023646094074",
      "ispb": null,
      "name": null,
      "branch": "0001",
      "bank": null
    },
    "description": "desbloqueio de saldo",
    "reason": "DESBLOQUEIO JUDICIAL"
  }
}

Campos do Response

Webhook

Campos importantes do webhook:

Exemplos de webhook - "entity": "balance-amount-even" e "type": ""unblocked-amount".

{
  "webhookId": "a4dee906-00b4-4a28-a084-9f0e900fad06",
  "body": {
    "reason": "DESBLOQUEIO JUDICIAL",
    "amount": 0.01,
    "correlationBlockedId": "3e8b3dbf-8da8-4acd-b3e7-bb11055a3320",
    "taxId": "66877376781",
    "clientCode": "954c192e-85fb-48b9-ae32-5e2fc9e2f5fe",
    "name": "Frank Mante",
    "description": "desbloqueio de saldo",
    "id": "a4dee906-00b4-4a28-a084-9f0e900fad06",
    "type": "unblocked-amount",
    "branch": "0001",
    "account": "30023646094074"
  },
  "entity": "balance-amount-event",
  "createTimestamp": "2026-02-20T12:38:05.8120625",
  "status": "CONFIRMED"
}

Erros

❗

Error 400

{
  "status": "ERROR",
  "version": "1.0.0",
  "error": {
    "errorCode": "CBE316",
    "message": "Lançamento não permitido. Não existe saldo em moeda eletrônica para o lançamento."
  }
}

Tabela de errorCode