Referência da API

Saldo

Saldos e extrato conciliado.

Saldos observados, conciliados e elegíveis

GET/v1/balanceImplementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· getBalance

Saldo observado no provedor, conciliado pelo extrato e elegível para saque. pendingCents e blockedCents são projeções, não saldo; saldo estimado nunca autoriza saque.

Escopo da chave: balance:read.

Headers de getBalance
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getBalance
Parâmetro	Onde	Tipo	Descrição
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/balance" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getBalance
Campo	Tipo	Descrição
`accountId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`environment` obrigatório	Environment
`providerAvailableCents` obrigatório	SignedCents (texto)	Último GET /finance/balance observado; não é saldo eterno. formato ^-?(0\|[1-9][0-9]{0,14})$
`eligibleCents` obrigatório	Cents (texto)	Estimativa conservadora: min(provedor, conciliado) − reservas − retenções − suspense. formato ^(0\|[1-9][0-9]{0,14})$
`withdrawableNowCents` obrigatório	Cents (texto)	O que pode ser despachado agora (snapshot recente, ledger em dia, sem divergência). formato ^(0\|[1-9][0-9]{0,14})$
`reservedCents` obrigatório	Cents (texto)	Transferências em andamento (reservas ativas). formato ^(0\|[1-9][0-9]{0,14})$
`reconciledCents` obrigatório	SignedCents (texto)	Caixa conciliado pelo extrato importado. formato ^-?(0\|[1-9][0-9]{0,14})$
`suspenseCents` obrigatório	SignedCents (texto)	Movimentos sem classificação confirmada; nunca autorizam saque. formato ^-?(0\|[1-9][0-9]{0,14})$
`pendingCents` obrigatório	Cents (texto)	Projeção: confirmado a liberar. Não é saldo. formato ^(0\|[1-9][0-9]{0,14})$
`blockedCents` obrigatório	Cents (texto)	Projeção: retenções informadas pelo provedor. formato ^(0\|[1-9][0-9]{0,14})$
`asOf` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`stale` obrigatório	booleano
`restrictions` obrigatório	lista de texto	PROVIDER_SNAPSHOT_STALE \| LEDGER_LAGGING \| BALANCE_MISMATCH \| PROVIDER_SNAPSHOT_MISSING
`openCases` obrigatório	inteiro	0 a 9007199254740991
`reconciliationStatus` obrigatório	texto

Exemplo 200

{
  "accountId": "acc_01JDY7Q2M3N4P5R6S7T8V9W0XB",
  "environment": "sandbox",
  "providerAvailableCents": "9801",
  "eligibleCents": "9801",
  "withdrawableNowCents": "9801",
  "reservedCents": "0",
  "reconciledCents": "9801",
  "suspenseCents": "0",
  "pendingCents": "0",
  "blockedCents": "0",
  "asOf": "2026-11-13T13:00:00.000Z",
  "stale": false,
  "restrictions": [],
  "openCases": 0,
  "reconciliationStatus": "MATCHED"
}

Erros

Erros de getBalance
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Extrato conciliado

GET/v1/statementImplementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· getStatement

Extrato importado do provedor, com o vínculo à cobrança quando conhecido. Itens de tipo desconhecido aparecem como SUSPENSE até revisão.

Escopo da chave: balance:read.

Headers de getStatement
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de getStatement
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/statement" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de getStatement
Campo	Tipo	Descrição
`data` obrigatório	lista de StatementEntry
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].signedCents` obrigatório	SignedCents (texto)	formato ^-?(0\|[1-9][0-9]{0,14})$
`data[].type` obrigatório	texto
`data[].occurredAt` obrigatório	texto
`data[].paymentId` obrigatório	texto ou nulo
`data[].reconciliationStatus` obrigatório	"MATCHED" \| "SUSPENSE"
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "stm_01JDY8H1B2C3D4E5F6G7H8J9KM",
      "signedCents": "14970",
      "type": "PAYMENT_RECEIVED",
      "occurredAt": "2026-11-13",
      "paymentId": "pay_01JDY8C1B2C3D4E5F6G7H8J9KC",
      "reconciliationStatus": "MATCHED"
    }
  ],
  "nextCursor": null
}

Erros

Erros de getStatement
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Casos de conciliação da conta

GET/v1/reconciliation/casesImplementada

Chave de API (Authorization: Bearer ep_…)· escopo balance:read· listReconciliationCases

Lista os casos de conciliação da conta (cobrança sem extrato, extrato sem cobrança, valor divergente, split) com situação e prazo. Casos são resolvidos por fluxo formal; saldo nunca é editado.

Escopo da chave: balance:read.

Headers de listReconciliationCases
Header	Obrigatório	Descrição
`X-Account-Id`	sim	Conta permitida pelos grants do principal.

Parâmetros de listReconciliationCases
Parâmetro	Onde	Tipo	Descrição
`cursor`	query	texto	0–200 caracteres
`limit`	query	inteiro	1 a 100 · padrão 20
`status`	query	"OPEN" \| "IN_REVIEW" \| "ADJUSTMENT_PENDING" \| "RESOLVED"
`kind`	query	"missing_payment" \| "orphan_statement" \| "amount_mismatch" \| "fee_mismatch" \| "split_mismatch" \| "balance_mismatch" \| "unknown_type"
`Eclipta-Pay-Version`	header	"2026-11-13"	Versão de data do contrato. Opcional; a resposta sempre informa a versão usada. Valor desconhecido responde 400 UNSUPPORTED_API_VERSION.

Exemplo

curl -X GET "$ECLIPTA_PAY_API/v1/reconciliation/cases" \
  -H "Authorization: Bearer $ECLIPTA_PAY_KEY" \
  -H "X-Account-Id: $ECLIPTA_PAY_ACCOUNT"

Resposta 200: Sucesso.

Campos da resposta 200 de listReconciliationCases
Campo	Tipo	Descrição
`data` obrigatório	lista de ReconciliationCase
`data[].id` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].accountId` obrigatório	Id (texto)	8–160 caracteres · formato ^[A-Za-z0-9_]+$
`data[].kind` obrigatório	"missing_payment" \| "orphan_statement" \| "amount_mismatch" \| "fee_mismatch" \| "split_mismatch" \| "balance_mismatch" \| "unknown_type"
`data[].classA` obrigatório	"MISSING_IN_LEDGER" \| "AMOUNT_MISMATCH" \| "MISSING_IN_PROVIDER" \| "BALANCE"	Classe equivalente de A REQ-16-02 (C-23).
`data[].status` obrigatório	"OPEN" \| "IN_REVIEW" \| "ADJUSTMENT_PENDING" \| "RESOLVED"
`data[].statementEntryId` obrigatório	Id (texto) ou nulo
`data[].paymentId` obrigatório	Id (texto) ou nulo
`data[].transferId` obrigatório	Id (texto) ou nulo
`data[].details` obrigatório	mapa
`data[].dueAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].openedAt` obrigatório	data e hora (ISO 8601)	formato ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`data[].resolvedAt` obrigatório	data e hora (ISO 8601) ou nulo
`data[].resolutionKind` obrigatório	"EXPLAINED" \| "ADJUSTED" \| "AUTO_MATCHED" ou nulo
`data[].resolutionNote` obrigatório	texto ou nulo
`nextCursor` obrigatório	texto ou nulo

Exemplo 200

{
  "data": [
    {
      "id": "rcc_01JDYA81B2C3D4E5F6G7H8J9KH",
      "accountId": "acc_01JDY7Q2M3N4P5R6S7T8V9W0XB",
      "kind": "missing_payment",
      "classA": "MISSING_IN_LEDGER",
      "status": "OPEN",
      "statementEntryId": "stm_01JDYA91B2C3D4E5F6G7H8J9KJ",
      "paymentId": null,
      "transferId": null,
      "details": {
        "statementType": "PAYMENT_RECEIVED",
        "valueCents": "14970"
      },
      "dueAt": "2026-11-15T13:00:00.000Z",
      "openedAt": "2026-11-13T13:00:00.000Z",
      "resolvedAt": null,
      "resolutionKind": null,
      "resolutionNote": null
    }
  ],
  "nextCursor": null
}

Erros

Erros de listReconciliationCases
HTTP	Exemplo de code	Quando
400	`INVALID_REQUEST`	Requisição inválida: fieldErrors aponta cada campo.
401	`INVALID_API_KEY`	Chave de API ausente, inválida, expirada ou revogada.
403	`SCOPE_MISSING`	Escopo ausente, conta não permitida em X-Account-Id, IP fora da lista ou conta suspensa.
429	`TOO_MANY_REQUESTS`	Limite de requisições da chave atingido (rajada de 100 e 6.000 por minuto). Toda resposta traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 traz Retry-After em segundos. Aguarde e repita com a mesma Idempotency-Key.

Todas as rotas