Cenários práticos

Cenários Práticos de Utilização

Cenário 1: Bloqueio Simples

Situação: Cliente precisa bloquear R$ 150,00 de uma conta que possui R$500,00 de saldo, para garantia de uma operação.

Comportamento esperado:

• Saldo disponível é reduzido a R$ 350,00;
• Saldo bloqueado é acrescido em R$ 150,00;
• Operação vinculada ao correlationBlockedId da operação.

Request do bloqueio

{
  "amount": 150.00,
  "clientRequestId": "op-garantia-001",
  "correlationBlockedId": "operacao-xyz-123",
  "reason": "GARANTIA OPERACIONAL",
  "description": "Bloqueio para garantia da operação XYZ",
  "tags": [
    { "key": "tipo", "value": "garantia" },
    { "key": "operacao", "value": "XYZ-123" }
  ]
}

Response do bloqueio

{
  "status": "CONFIRMED",
  "body": {
    "id": "blq-001",
    "blockedAmount": 150.00,
    "correlationBlockedId": "operacao-xyz-123"
  }
}

Cenário 2: Múltiplos Bloqueios com Mesma Correlação

Situação: Uma operação exige bloqueios fracionados (ex: garantia em etapas), sendo:

• Bloqueio 1: R$ 50,00 | Bloqueio 2: R$ 30,00 | Bloqueio 3: R$ 20,00
• Total bloqueado: R$ 100,00
• Todos vinculados ao mesmo correlationBlockedId
• Possibilidade de liberação total ou parcial posteriormente

Requests dos bloqueios

Bloqueio 1

{
  "amount": 50.00,
  "clientRequestId": "op-001-parte-1",
  "correlationBlockedId": "operacao-abc-456",
  "reason": "BLOQUEIO PARCIAL 1/3"
}

Bloqueio 2

{
  "amount": 30.00,
  "clientRequestId": "op-001-parte-2",
  "correlationBlockedId": "operacao-abc-456",
  "reason": "BLOQUEIO PARCIAL 2/3"
}

Bloqueio 3

{
  "amount": 20.00,
  "clientRequestId": "op-001-parte-3",
  "correlationBlockedId": "operacao-abc-456",
  "reason": "BLOQUEIO PARCIAL 3/3"
}

• Observe que em todas as operações de bloqueio o campo correlationBlockedId é o mesmo "operacao-abc-456". Isso garante que o total bloqueado, vinculado ao mesmo evento, seja igual a R$ 100,00.
  Isso permite, no futuro, no caso do desbloqueio, que seja realizado 1 único evento de desbloqueio para N bloqueios.

Cenário 3: Desbloqueio Total

Situação: Liberar todos os valores relacionados a um mesmo correlationBlockedID (R$ 100,00 do cenário 2)

Comportamento:

• Todos os bloqueios vinculados à mesma correlação são liberados;
• O valor total retorna ao saldo disponível;

Request do desbloqueio

{
  "clientRequestId": "desblq-total-001",
  "correlationBlockedId": "operacao-abc-456",
  "reason": "OPERAÇÃO FINALIZADA",
  "description": "Liberação total após conclusão",
  "unBlockAll": true
}

• No campo "unBlockAll", como foi passado o parametro = True não é necessário informar o valor (amount).

Response do desbloqueio

{
  "status": "CONFIRMED",
  "body": {
    "id": "desblq-001",
    "unlockedAmount": 100.00,
    "clientRequestIdOriginal": [
      "op-001-parte-1",
      "op-001-parte-2",
      "op-001-parte-3"
    ]
  }
}

• Neste cenário, todos os 3 bloqueios foram liberados de uma vez.

Cenário 4: Desbloqueio Parcial

Situação: Liberação parcial de garantia, mantendo parte do valor ainda retido.

• Total bloqueado: R$ 150,00
• Desbloqueio parcial: R$ 50,00

Resultado:

• R$ 50,00 retornam ao saldo disponível;
• R$ 100,00 permanecem bloqueados;

Request do desbloqueio

{
  "clientRequestId": "desblq-parcial-001",
  "correlationBlockedId": "operacao-abc-456",
  "reason": "LIBERAÇÃO PARCIAL",
  "description": "Liberação parcial de garantia",
  "unBlockAll": false,
  "amount": 50.00
}

• Como o campo "unBlockAll" foi informado como false na requisição, o "amount" se tornou obrigatório.

Response do desbloqueio

{
  "status": "CONFIRMED",
  "body": {
    "id": "desblq-002",
    "unlockedAmount": 50.00,
    "correlationBlockedId": "operacao-abc-456"
  }
}

• Ainda restam R$ 100,00 bloqueados com a mesma correlação.