Bloqueio de Saldo

Bloqueia ou desbloqueia saldo de uma sub-conta.

POST /api/customer/{id}/blocks

Bloqueia ou desbloqueia saldo.

Endpoint

POST https://api.divipay.com.br/api/customer/{id}/blocks

Headers

Header	Valor	Obrigatório
Authorization	Bearer	Sim
Content-Type	application/json	Sim

Path Parameters

Parâmetro	Tipo	Descrição
id	string	ID da sub-conta

Body Parameters

Campo	Tipo	Descrição	Obrigatório
amount	number	Valor a bloquear (positivo) ou desbloquear (negativo)	Sim

Exemplo - Bloquear Saldo

cURL

curl -X POST https://api.divipay.com.br/api/customer/sub_abc123/blocks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00
  }'

JavaScript

const response = await fetch(
  'https://api.divipay.com.br/api/customer/sub_abc123/blocks',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer SEU_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 100.00
    })
  }
);

const result = await response.json();

Exemplo - Desbloquear Saldo

curl -X POST https://api.divipay.com.br/api/customer/sub_abc123/blocks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": -100.00
  }'

Resposta de Sucesso

Status: 201 Created

{
  "id": "sub_abc123",
  "status": 1
}

GET /api/customer/{id}/blocks

Consulta bloqueios ativos.

Endpoint

GET https://api.divipay.com.br/api/customer/{id}/blocks

Exemplo

curl -X GET https://api.divipay.com.br/api/customer/sub_abc123/blocks \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{
  "customerId": "sub_abc123",
  "totalBlocked": 100.00,
  "blocks": [
    {
      "id": "block_xyz789",
      "amount": 100.00,
      "reason": "Garantia de transação",
      "createdAt": "2024-11-04T15:00:00.000Z"
    }
  ]
}

Casos de Uso

1. Garantia de Transação

async function holdFunds(customerId, amount, transactionId) {
  try {
    // Bloquear saldo
    await fetch(
      `https://api.divipay.com.br/api/customer/${customerId}/blocks`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ amount })
      }
    );

    // Registrar bloqueio
    await db.holds.create({
      data: {
        customerId,
        amount,
        transactionId,
        status: 'ACTIVE',
        createdAt: new Date()
      }
    });

    console.log(`✅ Bloqueado R$ ${amount} para transação ${transactionId}`);

  } catch (error) {
    console.error('❌ Erro ao bloquear saldo:', error);
    throw error;
  }
}

2. Liberar Após Confirmação

async function releaseFunds(customerId, amount, transactionId) {
  try {
    // Desbloquear saldo
    await fetch(
      `https://api.divipay.com.br/api/customer/${customerId}/blocks`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ amount: -amount })
      }
    );

    // Atualizar registro
    await db.holds.update({
      where: { transactionId },
      data: {
        status: 'RELEASED',
        releasedAt: new Date()
      }
    });

    console.log(`✅ Liberado R$ ${amount} da transação ${transactionId}`);

  } catch (error) {
    console.error('❌ Erro ao liberar saldo:', error);
    throw error;
  }
}

3. Verificar Saldo Disponível

async function getAvailableBalance(customerId) {
  const response = await fetch(
    `https://api.divipay.com.br/api/customer/${customerId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );

  const customer = await response.json();

  return {
    total: customer.balance,
    blocked: customer.blockedBalance,
    available: customer.balance - customer.blockedBalance
  };
}

// Uso
const balance = await getAvailableBalance('sub_abc123');
console.log(`Disponível: R$ ${balance.available}`);

Boas Práticas

1. Sempre Registrar Motivo

await db.blocks.create({
  data: {
    customerId,
    amount,
    reason: 'Garantia de entrega',
    createdBy: userId,
    createdAt: new Date()
  }
});

2. Liberar Automaticamente

// Liberar após 7 dias
setTimeout(async () => {
  await releaseFunds(customerId, amount, transactionId);
}, 7 * 24 * 60 * 60 * 1000);

3. Validar Saldo Antes de Bloquear

const balance = await getAvailableBalance(customerId);

if (balance.available < amount) {
  throw new Error('Saldo insuficiente para bloqueio');
}

await holdFunds(customerId, amount, transactionId);

Próximos Passos

• Consultar Sub-conta
• Saques