Documentação de API

Listar Cobranças

Endpoint:

GET /v3/charges

Descrição

Retorna a lista de cobranças com base nos filtros informados. Nenhum filtro é obrigatório, mas recomendamos seu uso para uma busca mais eficiente e segmentada.

Headers Obrigatórios

Header	Descrição
X-Token-Api	Token de autenticação do seller.

Parâmetros de Query

Parâmetro	Tipo	Descrição
status	String	Status da cobrança. Ver valores possíveis abaixo.
paymentMethod	String	Forma de pagamento. Ver valores possíveis abaixo.
startCreatedAt	String	Data/hora inicial de criação da cobrança (yyyy-MM-dd HH:mm:ss).
endCreatedAt	String	Data/hora final de criação da cobrança (yyyy-MM-dd HH:mm:ss).
pageSize	Int	Quantidade de registros por página.
page	Int	Número da página.

Valores possíveis

• status: ['SCHEDULED', 'LATE', 'PAID', 'CANCELED', 'PAID_MANUALLY', 'ABANDONED', 'REFUND', 'FAILED', 'CHARGEBACK', 'DISPUTE', 'PRE_AUTHORIZED']

• paymentMethod: ['PIX', 'BANK_SLIP', 'CREDIT_CARD', 'CREDIT_CARD_EARLY_BUYER', 'CREDIT_CARD_EARLY_SELLER', 'DEBIT_CARD', 'CREDIT_CARD_EARLY_MIXED', 'GOOGLE_PAY', 'APPLE_PAY']

---

Exemplo de Requisição

curl --location 'https://app.barte.com/v3/charges?status=FAILED&paymentMethod=CREDIT_CARD&startCreatedAt=2025-01-10%2000%3A00%3A01&endCreatedAt=2025-08-14%2023%3A59%3A59&pageSize=20&page=1' \
--header 'X-Token-Api: {{ X-Token-Api }}' \
--header 'Content-Type: application/json'

---

Exemplo de Resposta - Sucesso com registros

{
    "content": [
        {
            "uuid": "e53e1ebf-8975-4c82-aa44-32093da02bae",
            "title": "Fatura mensal do cliente",
            "expirationDate": "2025-06-19",
            "value": 135.25,
            "paymentMethod": "CREDIT_CARD",
            "status": "FAILED",
            "customer": {
                "document": "12345678912",
                "type": "CPF",
                "name": "Daniel Doces Ltda ",
                "email": "[e-mail]",
                "phone": "12345678912"
            },
            "authorizationCode": "null",
            "authorizationNsu": "null",
            "refunds": [],
            "createdAt": "2025-06-19 12:46:34",
            "paidDate": "null",
            "originalValue": 1.25,
            "installments": 1,
            "brand": "mastercard",
            "errorReason": {
              "code": "51",
              "description": "insufficient_funds"
            }
        }
    ],
    "pageable": {
        "pageNumber": 1,
        "pageSize": 20,
        "totalElements": 20
    }
}

Descrição dos campos relevantes

Campo	Tipo	Descrição
uuid	String	Identificador único da cobrança.
title	String	Título/descritivo da cobrança.
expirationDate	String	Data de vencimento (yyyy-MM-dd).
value	Float	Valor total da cobrança.
paymentMethod	String	Forma de pagamento.
status	String	Status da cobrança.
customer	Objeto	Dados do cliente pagador.
authorizationCode	String	Código de autorização.
authorizationNsu	String	Número sequencial da autorização.
refunds	Array	Lista de reembolsos.
createdAt	String	Data/hora de criação da cobrança.
paidDate	String	Data de pagamento.
originalValue	Float	Valor original da cobrança.
installments	Int	Número de parcelas.
brand	String	Bandeira do cartão, ou "".
errorReason	String	Motivo do erro, se houver.

---

Exemplo de Resposta - Nenhum registro encontrado

{
    "content": [],
    "pageable": {
        "pageNumber": 1,
        "pageSize": 20,
        "totalElements": 0
    }
}

---

Códigos de Erro

Token ausente

{
    "errors": {
        "code": "BAR-3009",
        "title": "Token de autenticação ausente",
        "description": "O header x-token-api é obrigatório para autenticação."
    }
}

Token inválido

{
    "errors": {
        "code": "BAR-3008",
        "title": "Seller não encontrado.",
        "description": "O seller ID informado não foi encontrado ou não está associado a sua company."
    }
}

Erro de validação de parâmetros

{
    "errors": {
        "code": "BAR-3011",
        "title": "Erro de validação de parâmetros",
        "description": "O valor do campo [status] não existe."
    }
}

Possíveis descrições para o erro:

• O valor do campo [status] não existe.

• O valor do campo [paymentMethod] não existe.

• startCreatedAt não pode ser posterior a endCreatedAt.

---