Guia de integração
Saldo
O endpoint de saldo retorna o estado atual da sua carteira na Zypfy. É útil para pre-check antes de disparar um saque e para reconciliar o saldo gerencial no seu ERP.
Endpoint
GET https://api.zypfy.com/api/accounts/balanceHeaders: Authorization: Bearer SEU_TOKEN.
Resposta 200 OK
{
"message": "Wallet balance retrieved successfully.",
"total_balance": 1000.00,
"balance": 800.00,
"balance_block": 200.00,
"balance_mxn": 0.00,
"available_balance": 800.00
}Semântica dos campos
| Campo | Descrição |
|---|---|
balance | Saldo disponível para saque no momento. É o valor que você pode efetivamente mover. |
balance_block | Saldo bloqueado — reservado por saques em processamento que ainda não foram liquidados. Não pode ser movido. |
total_balance | balance + balance_block. Reflete o total que você "tem" na Zypfy, incluindo o que está preso em saques pendentes. |
available_balance | Alias de balance (mesma coisa — há pelo histórico de API). |
balance_mxn | Saldo em pesos mexicanos (MXN), alimentado pelos Depósitos MXN. Carteira separada do BRL. Não é sacável direto: converta para reais com POST /api/accounts/mxn/convert antes de sacar. Vale 0 se sua conta não usa o México. |
Por que existe balance_block?
Quando você cria um saque:
- A Zypfy move
amount + feedebalance→balance_block. Esse valor fica reservado. - Se o saque for
COMPLETED, o valor é debitado debalance_block(sai da carteira). - Se o saque for
FAILED, o valor volta debalance_blockparabalance.
Isso evita que você disparar N saques concorrentes com saldo insuficiente real (cada um reserva sua fatia no block).
Exemplo: pre-check antes de saque
async function saqueSeguro({ amount, pix_key, key_type, external_id }) {
const token = await getToken();
// 1. Pre-check do saldo
const { data: saldoResp } = await axios.get(
'https://api.zypfy.com/api/accounts/balance',
{ headers: { Authorization: `Bearer ${token}` } }
);
const taxaEstimada = amount * 0.02; // sua fee contratada (exemplo)
const necessario = amount + taxaEstimada;
if (saldoResp.balance < necessario) {
throw new Error(
`Saldo insuficiente: disponível R$ ${saldoResp.balance.toFixed(2)}, ` +
`necessário R$ ${necessario.toFixed(2)}.`
);
}
// 2. Disparar saque
const { data } = await axios.post(
'https://api.zypfy.com/api/withdrawals/withdraw',
{ amount, pix_key, key_type, external_id },
{ headers: { Authorization: `Bearer ${token}` } }
);
return data;
}Códigos de erro
| HTTP | Resposta | Causa |
|---|---|---|
| 401 | Unauthorized. | Token ausente. |
| 403 | — | Token inválido ou expirado. |
| 404 | Wallet not found for this user. | Carteira não existe para este usuário (conta recém-criada sem carteira provisionada — contatar suporte). |
Boas práticas
- Não cache o saldo agressivamente. O
balancemuda a cada depósito confirmado e cada saque disparado. - Use antes de cada saque (pre-check) — custa pouco e evita
INSUFFICIENT_BALANCE. - Não use para reconciliar transações individuais — use
/api/transactions/*comexternal_idpara isso.