Listar Cobranças PIX

Esta seção explica como listar todas as cobranças PIX de uma conta específica.

Visão Geral

O endpoint de listagem retorna todas as cobranças PIX criadas para uma conta, permitindo que você:

• Visualize o histórico de cobranças
• Monitore o status de múltiplas cobranças
• Acompanhe valores e descrições
• Verifique datas de criação e atualização

Endpoint

GET /account/{account_id}/charge/pix/list

Retorna a lista de todas as cobranças PIX de uma conta.

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/charge/pix/list

Headers:

Authorization: Bearer {token}

Parâmetros da URL:

• account_id (obrigatório): ID da conta

Exemplo de Requisição:

curl -X GET \
  'https://app.finexis.com.br/api/v1/gateway/account/5/charge/pix/list' \
  -H 'Authorization: Bearer {seu_token}'

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Account charges retrieved successfully",
  "data": [
    {
      "id": 1,
      "account_id": 5,
      "provider_id": 2,
      "amount": "4.000000000000000000",
      "currency": "BRL",
      "status": "pending",
      "description": null,
      "content": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/fc52d462-1f2d-4828-b7f0-e57d60c9c3fb5204000053039865802BR5909VITALCRED6005Natal61085905476062070503***6304C116",
      "external_id": "1e97ebcb-d550-4e3c-942a-16ef9cc61f62",
      "reference": "f8a5ed1f774f4ac4ad4849c5e2",
      "metadata": {
        "emv": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/fc52d462-1f2d-4828-b7f0-e57d60c9c3fb5204000053039865802BR5909VITALCRED6005Natal61085905476062070503***6304C116",
        "amount": 4,
        "description": "Sistema Prometheus - Cobrança",
        "uuid": "1e97ebcb-d550-4e3c-942a-16ef9cc61f62",
        "nonce": "nOPuuXLj4u8naSPd",
        "reference": "f8a5ed1f774f4ac4ad4849c5e2",
        "sha256": "7af064168ba9f6a149b846b703652124f4da53fc729cbe07e31a697b59f166be",
        "hash_schema": ["reference", "amount", "nonce"],
        "expires_in": 3600,
        "expires_at": "2025-11-17T17:45:34.371Z",
        "coust": 0,
        "tx_id": "f8a5ed1f774f4ac4ad4849c5e2",
        "id": 7763887,
        "status": "ACTIVE"
      },
      "created_at": "2025-11-17 17:35:34",
      "updated_at": "2025-11-17 17:35:34"
    }
  ]
}

Estrutura da Resposta

A resposta é um array de objetos, onde cada objeto representa uma cobrança com os seguintes campos:

Campo	Tipo	Descrição
id	integer	ID único da cobrança
account_id	integer	ID da conta
provider_id	integer	ID do provedor PIX
amount	string	Valor da cobrança (alta precisão)
currency	string	Moeda (geralmente "BRL")
status	string	Status da cobrança
description	string/null	Descrição da cobrança
content	string	Código EMV do QR Code
external_id	string	ID externo da cobrança
reference	string	Referência única para consultas
metadata	object	Metadados completos da cobrança
created_at	string	Data de criação
updated_at	string	Data da última atualização

Status Possíveis

Status	Descrição
pending	Cobrança pendente de pagamento
paid	Cobrança paga
expired	Cobrança expirada
cancelled	Cobrança cancelada

Casos de Uso

Este endpoint é útil para:

• Dashboard: Exibir lista de cobranças em uma interface administrativa
• Relatórios: Gerar relatórios de cobranças criadas
• Monitoramento: Acompanhar o status de múltiplas cobranças
• Histórico: Manter um histórico de todas as transações

Filtrando e Ordenando

Nota

Atualmente, o endpoint retorna todas as cobranças. Para filtrar por status ou data, você pode processar os resultados no lado do cliente.

Exemplo de filtro em JavaScript:

// Filtrar apenas cobranças pendentes
const pendingCharges = charges.filter(charge => charge.status === 'pending');

// Filtrar cobranças pagas
const paidCharges = charges.filter(charge => charge.status === 'paid');

// Ordenar por data de criação (mais recentes primeiro)
const sortedCharges = charges.sort((a, b) => 
  new Date(b.created_at) - new Date(a.created_at)
);

Próximos Passos

• Consultar Status de uma cobrança específica
• Criar Nova Cobrança
• Ver Transferências PIX