Skip to navigation

Saldo, saldo diário e encerramento

Saldo atual, série de saldos diários e encerramento de uma conta, no host https://tenant.api.corpx.com. Todas as chamadas levam Authorization: Bearer {token} e X-Tenant-Id.

Saldo

GET /v1/accounts/{accountId}/balance

curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/balance" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa"
{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"total": 18254.17,
"locked": 500.00,
"available": 17754.17,
"currency": "BRL",
"updatedAt": "2026-02-05T22:00:00Z"
}

available é o que a conta pode enviar. locked é o total retido (por exemplo, uma retenção de MED); a resposta não lista cada retenção. includeLocks é aceito por compatibilidade e não tem efeito.

Saldo diário

GET /v1/accounts/{accountId}/daily-balance?startDate=2026-06-04&endDate=2026-06-05

Devolve, por dia, a abertura (total / bloqueado / disponível) e os fluxos do dia, em horário de Brasília. Janela máxima de 30 dias; sem datas, vale os últimos 30 dias. Só há fechamentos a partir de 2026-06-04 (cutoffDate).

{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"startDate": "2026-06-04",
"endDate": "2026-06-04",
"cutoffDate": "2026-06-04",
"timezone": "America/Sao_Paulo",
"items": [
{
"date": "2026-06-04",
"openTotalBalance": 10000.00,
"openBlockedBalance": 0,
"openAvailableBalance": 10000.00,
"pixIn": 1200.00,
"pixOut": 300.00,
"pixBillingOut": 1.50,
"tedIn": 0,
"tedOut": 0,
"tedBillingOut": 0,
"internalTransferIn": 0,
"internalTransferOut": 0,
"internalTransferBillingOut": 0,
"bankSlipOut": 0,
"stablecoinBurn": 0,
"stablecoinMint": 0,
"cardSettlementIn": 845.30,
"cardSettlementOut": 0,
"currency": "BRL"
}
],
"fetchedAt": "2026-06-05T12:00:00Z"
}

Os fluxos vêm somados por tipo, sempre presentes e com 0 quando não houve movimento:

TipoEntradasSaídasTarifas
PixpixInpixOutpixBillingOut
TEDtedIntedOuttedBillingOut
Transferência internainternalTransferIninternalTransferOutinternalTransferBillingOut
Boleto—bankSlipOut—
BRMTstablecoinMintstablecoinBurn—
Liquidação de cartõescardSettlementIn (débito, crédito e antecipação)cardSettlementOut—

A abertura de um dia é a abertura do dia anterior mais as entradas, menos as saídas e as tarifas daquele dia.

Encerrar a conta

POST /v1/accounts/{accountId}/close

Tira o acesso do seu tenant à conta. Pessoas precisam do papel tenant_manager ou admin; credenciais, do escopo accounts.close (o legado api2/write também passa). Mande um Idempotency-Key para poder repetir a chamada com segurança.

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/close" \
-H "Authorization: Bearer {token}" \
-H "X-Tenant-Id: tenant-suaempresa" \
-H "Idempotency-Key: close-2e6b725b-001"
{
"accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
"message": "Este tenant perdeu o acesso à conta. Ela será encerrada em breve se nenhum outro tenant estiver usando."
}

A resposta 200 é a mesma quando outro tenant da CorpX ainda opera a conta e quando o seu é o último. A conta não é apagada: passa a status=closed. Repetir o pedido numa conta já encerrada no seu tenant devolve o mesmo 200, sem novo pedido de encerramento.

Quando a conta é só sua, o encerramento é pedido ao liquidante, que só aceita conta zerada: sem saldo disponível e sem saldo bloqueado. O saldo do liquidante é conferido antes:

SituaçãoRespostaO que fazer
Saldo disponível diferente de zero422 account_has_balanceRetire o saldo e repita.
Disponível zerado, mas com saldo bloqueado (por exemplo, retenção de MED)422 account_has_locked_balanceEspere a liberação do bloqueio e repita.
Saldo zerado200O encerramento é pedido ao liquidante e o acesso sai na mesma chamada.

Nos dois 422 a conta continua ativa e o corpo traz o saldo do liquidante:

{
"errorCode": "account_has_locked_balance",
"message": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
"errorReason": "para cancelar a conta no liquidante é preciso liberar o saldo bloqueado antes",
"balance": {
"total": 50.00,
"available": 0,
"locked": 50.00,
"currency": "BRL"
}
}

A conta bancária em si é encerrada quando o liquidante processa o pedido; o 200 não diz quando.

Outros erros:

StatusCódigoQuando
404account_not_foundConta inexistente, de outro tenant ou suspended. Nunca 403 tenant_mismatch.
403forbiddenPessoa sem papel tenant_manager ou admin (um viewer, por exemplo).
403insufficient_scopeCredencial sem o escopo accounts.close.
409request_in_progressO mesmo Idempotency-Key ainda está sendo processado.
503banking_unavailable / email_unavailableLiquidante ou envio do pedido indisponível. A conta continua ativa; tente de novo mais tarde.