Listar cobranças

Quick Reference

WhatListar cobranças com filtros e paginação

WhyConstruir dashboards de conciliação, relatórios financeiros e ferramentas de investigação de disputas

Reading Time8 min

DifficultyIntermediate

PrerequisitesAuthentication → At least one created charge

GET/api/v1/bank/wallet/charges/Bearer TokenListar cobranças com filtros

Por que listar cobranças

Sem Listar Cobranças	Com Listar Cobranças
Conciliação é manual — exportar CSVs e cruzar referências	Conciliação automatizada consulta transações via API em agendamento
Relatórios financeiros exigem esperar arquivos de liquidação	Dashboards de receita em tempo real consultam cobranças por intervalo de datas
Investigação de disputas começa com "encontre a transação"	Busca por bandeira de cartão, BIN, data ou status em segundos
Sem visibilidade do volume de transações diárias	Monitore volume de cobranças, taxas de aprovação e taxas programaticamente
Fechamento mensal leva dias de trabalho manual	Scripts automatizados consultam todas as cobranças, calculam totais, sinalizam discrepâncias

Pipeline de conciliação

Autenticação

Requer token Bearer. Veja Autenticação.

Parâmetros de consulta

Campo	Tipo	Obrigatório	Descrição
`wallet_uuid`	string (UUID)	Sim	Limitar resultados a esta carteira
`merchant_uuid`	string (UUID)	Não	Filtrar por identificador do merchant
`date_start`	string	Não	Início do intervalo de datas (ISO 8601: `2026-03-01` ou `2026-03-01T00:00:00Z`)
`date_end`	string	Não	Fim do intervalo de datas (ISO 8601)
`page`	integer	Não	Número da página (iniciando em 1). Padrão: `1`
`limit`	integer	Não	Itens por página (1–100). Padrão: `20`
`filter`	string	Não	Filtros adicionais (status, tipo, bandeira do cartão)
`sort`	string	Não	Critérios de ordenação (ex.: `created:desc`)

Combinações de filtros

Caso de uso	Query string
Todas as cobranças deste mês	`date_start=2026-03-01&date_end=2026-03-31`
Apenas cobranças confirmadas	`filter=status:confirmed`
Apenas cobranças de cartão de crédito	`filter=type:credit`
Transações Visa	`filter=card_brand:Visa`
Cobranças de alto valor	`filter=amount_gte:1000`
Cobranças liquidadas ontem	`date_start=2026-03-19&date_end=2026-03-19&filter=status:confirmed`

Caminho do endpoint no plural

Este endpoint usa /charges/ (plural), não /charge/. Usar o caminho no singular chama Consultar Cobrança em vez disso.

Exemplos de código

Listagem básica com paginação

cURL
Python
JavaScript

curl -s -X GET "https://core-manager.a55.tech/api/v1/bank/wallet/charges/?wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479&page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")

charges = requests.get(
    f"{base}/api/v1/bank/wallet/charges/",
    params={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "page": 1,
        "limit": 20,
    },
    headers={"Authorization": f"Bearer {token}"},
).json()

for c in charges.get("data", []):
    print(f"{c['created']} | {c['transaction_id']} | {c['currency']} {c['amount']} | {c['status']}")

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://core-manager.a55.tech";

const params = new URLSearchParams({
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  page: "1",
  limit: "20",
});

const charges = await fetch(`${base}/api/v1/bank/wallet/charges/?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

for (const c of charges.data || []) {
  console.log(`${c.created} | ${c.transaction_id} | ${c.currency} ${c.amount} | ${c.status}`);
}

Conciliação completa — paginar por todas as cobranças

Python
JavaScript

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")

def fetch_all_charges(wallet_uuid, date_start, date_end):
    all_charges = []
    page = 1

    while True:
        resp = requests.get(
            f"{base}/api/v1/bank/wallet/charges/",
            params={
                "wallet_uuid": wallet_uuid,
                "date_start": date_start,
                "date_end": date_end,
                "page": page,
                "limit": 100,
            },
            headers={"Authorization": f"Bearer {token}"},
        ).json()

        data = resp.get("data", [])
        all_charges.extend(data)

        if len(data) < 100:
            break
        page += 1

    return all_charges

charges = fetch_all_charges(
    wallet_uuid="f47ac10b-58cc-4372-a567-0e02b2c3d479",
    date_start="2026-03-01",
    date_end="2026-03-20",
)

total_amount = sum(c["amount"] for c in charges)
total_fees = sum(c.get("fee", 0) for c in charges)
print(f"Charges: {len(charges)} | Total: {total_amount} | Fees: {total_fees}")

async function fetchAllCharges(walletUuid, dateStart, dateEnd) {
  const allCharges = [];
  let page = 1;

  while (true) {
    const params = new URLSearchParams({
      wallet_uuid: walletUuid,
      date_start: dateStart,
      date_end: dateEnd,
      page: String(page),
      limit: "100",
    });

    const resp = await fetch(`${base}/api/v1/bank/wallet/charges/?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json());

    const data = resp.data || [];
    allCharges.push(...data);

    if (data.length < 100) break;
    page++;
  }

  return allCharges;
}

const charges = await fetchAllCharges(
  "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "2026-03-01",
  "2026-03-20"
);

const totalAmount = charges.reduce((sum, c) => sum + c.amount, 0);
const totalFees = charges.reduce((sum, c) => sum + (c.fee || 0), 0);
console.log(`Charges: ${charges.length} | Total: ${totalAmount} | Fees: ${totalFees}`);

Campos da resposta

Cada objeto de cobrança no array data contém:

Campo	Tipo	Descrição
`created`	string	Timestamp de criação ISO 8601
`transaction_id`	string	Identificador de transação A55
`charge_uuid`	string	Identificador único da cobrança
`merchant`	string	Nome do merchant
`amount`	number	Valor total da cobrança
`currency`	string	Código de moeda ISO 4217
`net_amount`	number	Valor após taxas
`fee`	number	Taxa de processamento descontada
`status`	string	`issued`, `pending`, `confirmed`, `paid`, `error`, `canceled`, `refunded`
`card_brand`	string	Bandeira do cartão (`Visa`, `Mastercard`, `Amex`, `Elo`) — `null` para métodos não-cartão
`card_bin`	string	Primeiros 6 dígitos do cartão — `null` para métodos não-cartão
`type`	string	Tipo de pagamento: `credit`, `debit`, `pix`, `boleto`, etc.
`settlement_date`	string	Data de liquidação prevista ou realizada
`message`	array	Mensagens de status ou detalhes do erro

Metadados de paginação

Campo	Tipo	Descrição
`page`	integer	Número da página atual
`total`	integer	Número total de cobranças correspondentes à consulta

Exemplo completo de resposta

{
  "data": [
    {
      "created": "2026-03-20T14:32:11Z",
      "transaction_id": "TX1234567890",
      "charge_uuid": "7f8d4e2c-9c3f-4a7f-83b5-4e2f7f2b9d11",
      "merchant": "Loja Online ABC",
      "amount": 150.75,
      "currency": "BRL",
      "net_amount": 145.23,
      "fee": 5.52,
      "status": "confirmed",
      "card_brand": "Visa",
      "card_bin": "411111",
      "type": "credit",
      "settlement_date": "2026-03-23",
      "message": ["Success"]
    },
    {
      "created": "2026-03-20T15:10:45Z",
      "transaction_id": "TX1234567891",
      "charge_uuid": "a2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
      "merchant": "Loja Online ABC",
      "amount": 49.90,
      "currency": "BRL",
      "net_amount": 48.01,
      "fee": 1.89,
      "status": "confirmed",
      "card_brand": null,
      "card_bin": null,
      "type": "pix",
      "settlement_date": "2026-03-20",
      "message": ["Success"]
    },
    {
      "created": "2026-03-19T09:22:00Z",
      "transaction_id": "TX1234567892",
      "charge_uuid": "b3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f",
      "merchant": "Loja Online ABC",
      "amount": 899.00,
      "currency": "BRL",
      "net_amount": 865.84,
      "fee": 33.16,
      "status": "refunded",
      "card_brand": "Mastercard",
      "card_bin": "515590",
      "type": "credit",
      "settlement_date": "2026-03-22",
      "message": ["Refunded by merchant"]
    }
  ],
  "page": 1,
  "total": 142
}

Respostas de erro

Status	Código	Descrição	Resolução
400	`validation_error`	`wallet_uuid` ausente ou formato de parâmetro inválido	`wallet_uuid` é obrigatório. Verifique se o formato da data é ISO 8601
400	`errors.wallet.not_found`	UUID da carteira não existe	Verifique se o `wallet_uuid` está correto
401	`unauthorized`	Token Bearer inválido ou expirado	Renove seu token de acesso via Cognito
429	`rate_limit_exceeded`	Muitas requisições	Aguarde e tente novamente após o valor do header `Retry-After`

Otimize a paginação para grandes conjuntos de dados

Defina limit=100 (máximo) para reduzir o número de chamadas à API. Para conciliação diária, restrinja o intervalo de datas com date_start e date_end para manter os conjuntos de resultados pequenos e rápidos.

Não pule páginas

Sempre pagine da página 1 até a última página. Pular para páginas arbitrárias pode perder cobranças se novas transações forem criadas entre as requisições. Para dashboards em tempo real, ordene por created:desc e processe as primeiras páginas.

Valor líquido e detalhamento de taxas

O campo net_amount é amount - fee. Use net_amount para conciliação com depósitos bancários, e fee para contabilidade. As taxas variam por método de pagamento, moeda e acordo do merchant.

Consultar cobrança →Recuperar detalhes completos de uma cobrança específica da lista.Reembolsar cobrança →Emitir um reembolso para qualquer cobrança da lista.Webhooks →Receber notificações em tempo real em vez de consultar a lista.

Quick Reference

Por que listar cobranças​

Pipeline de conciliação​

Autenticação​

Parâmetros de consulta​

Combinações de filtros​

Exemplos de código​

Listagem básica com paginação​

Conciliação completa — paginar por todas as cobranças​

Campos da resposta​

Metadados de paginação​

Exemplo completo de resposta​

Respostas de erro​