Pular para o conteúdo principal
ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

📄 Consulta de Faturas e Transações

Este guia apresenta os endpoints para consultar faturas e suas transações detalhadas (débitos e créditos) na API de Arrecadação Lojista.

🎯 Visão Geral

Os endpoints de faturas permitem que você:

  • 📋 Consulte faturas do cliente
  • 🔍 Consulte detalhes de uma fatura em específica para obter informações para pagamento, como QR Code PIX, linha digitável e etc.
  • 💳 Liste transações de uma fatura em específica para obter informaoes de débitos e créditos.

URLs Base:

  • Homologação: https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2
  • Produção: https://api.credsystem.com.br/arrecadacao-lojista/api/v2

🔐 Autenticação

Todos os endpoints requerem autenticação via Bearer Token (JWT).

Header obrigatório:

Authorization: Bearer <seu_token_jwt>
Atenção

Tokens inválidos ou expirados retornarão erro 401 Unauthorized.


📚 Endpoints Disponíveis

1️⃣ Consultar Faturas do Cliente

Retorna a lista de faturas vinculadas ao cliente.

Endpoint: GET /faturas

Parâmetros de consulta:

  • codigoEstabelecimento (string, obrigatório) – Código da loja que está consultando.
  • cpfCliente (string, opcional) – CPF sem formatação.
  • numeroCartao (string, opcional) – Número do cartão com 12 a 19 dígitos.
Importante

Informe pelo menos um identificador do cliente (cpfCliente ou numeroCartao). Quando ambos forem enviados, o backend prioriza validações com o número do cartão.

Exemplos de requisição:

curl -X GET "https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/faturas?codigoEstabelecimento=12345&cpfCliente=12345678901" \
-H "Authorization: Bearer SEU_TOKEN_JWT"

Exemplo de resposta (200 Success):

{
"status": 200,
"mensagem": "Consulta retornado com sucesso.",
"extrato": [
{
"numeroExtrato": 123341123,
"dataProcessamento": "2023-10-28T00:00:00.000Z",
"dataVencimento": "2023-11-10T00:00:00.000Z",
"valorMinimo": 18.38,
"valorSaldoAtual": 0,
"valorTotalCredito": 71.43,
"valorTotalDebito": 71.43,
"valorTotalFechamento": -69.93,
"valorSaldoAnterior": 0,
"descricaoSituacao": "Liquidado"
}
]
}
Problemas com este endpoint?

Consulte o 🔧 Guia - Faturas (GET) para validar mensagens de erro e combinações de parâmetros.


2️⃣ Consultar Faturas detalhadas

Obtém uma fatura específica em PDF, além de linha digitável, QR Code e código PIX Copia e Cola.

Endpoint: GET /faturas/extrato/{numeroExtrato}/vencimento/{dataVencimento}

Parâmetros:

  • numeroExtrato (inteiro, obrigatório) – Número do extrato retornado na consulta de faturas.
  • dataVencimento (string, obrigatório) – Data do vencimento (YYYY-MM-DD).
  • codigoEstabelecimento (string, obrigatório).
  • cpfCliente (string, obrigatório).
Atenção

Garanta que numeroExtrato e dataVencimento correspondam ao registro retornado pela listagem anterior. Inconsistências geram erro

Exemplos de requisição:

curl -X GET "https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/faturas/extrato/789012/vencimento/2025-12-05?codigoEstabelecimento=12345&cpfCliente=12345678901" \
-H "Authorization: Bearer SEU_TOKEN_JWT"

Exemplo de resposta (200 Success):

{
"status": 200,
"mensagem": "Consulta de dados retornada com sucesso.",
"faturaBase64": "JVBERi0xLjUKJeLjz9MKMyc1BlckNvbXBvbmVudCA4Pj5zdHJlYW0KaN7tmm9MG2Ucx2...",
"qrCodeBase64": "JVBERi0xLjUKJeLjz9MKMyc1BlckNvbXBvbmVudCA4Pj5zdHJlYW0KaN7tmm9MG2Ucx2...",
"pixCopiaCola": "00020101021226820014BR.GOV.BCB.PIX2560api.banco123/pix/qr/v2/cobv/d8e434bd-3e02-445a"
}
Problemas com este endpoint?

Verifique o 🔧 Troubleshooting - Fatura Detalhada para divergências de parâmetros ou indisponibilidade.


3️⃣ Listar Transações da Fatura

Retorna os lançamentos de débito e crédito vinculados ao extrato selecionado.

Endpoint: GET /faturas/extrato/{numeroExtrato}/vencimento/{dataVencimento}/transacoes

Parâmetros:

  • numeroExtrato (inteiro, obrigatório) – Número do extrato retornado na consulta de faturas.
  • dataVencimento (string, obrigatório) – Data do vencimento (YYYY-MM-DD).
  • codigoEstabelecimento (string, obrigatório).
  • cpfCliente (string, obrigatório).

Exemplos de requisição:

curl -X GET "https://apihml.credsystem.com.br/arrecadacao-lojista/api/v2/faturas/extrato/789012/vencimento/2025-12-05/transacoes?codigoEstabelecimento=12345&cpfCliente=12345678901" \
-H "Authorization: Bearer SEU_TOKEN_JWT"

Exemplo de resposta (200 Success):

{
"status": 200,
"mensagem": "Consulta de dados retornada com sucesso.",
"debitoExtratos": [
{
"codigoCliente": 97079980,
"codigoTransacao": 1,
"dataHoraDebito": "2024-09-29T00:00:00.000Z",
"dataVencimento": "2024-11-29T00:00:00.000Z",
"numeroBin": 960339,
"numeroExtrato": 333118837,
"valorDebito": 57.94,
"codigoEstabelecimento": 29586,
"numeroContrato": 692156469,
"numeroParcela": 2,
"flagPermiteCNR": false
}
],
"creditoExtratos": [
{
"codigoCliente": 97079980,
"codigoTransacao": 1,
"dataCredito": "2024-09-29T00:00:00.000Z",
"dataVencimento": "2024-11-29T00:00:00.000Z",
"flagDesfazimento": false,
"numeroBin": 960339,
"numeroCreditoExtrato": 51123451,
"numeroExtrato": 12333221,
"valorCredito": 57.94,
}
]
}
Problemas com este endpoint?

Veja o 🔧 Troubleshooting - Transações da Fatura para validações adicionais.


💡 Dicas e Boas Práticas

✅ Recomendações

  1. Valide os dados antes de enviar - Verifique CPF, número do cartão, valores e códigos localmente antes de fazer a requisição
  2. Armazene o traceId - Use para rastrear problemas com o suporte técnico
  3. Implemente retry com backoff - Em caso de erro 503, tente novamente após alguns segundos
  4. Cache de tokens - Evite gerar novos tokens a cada requisição
  5. Valide pré-autorizações - Sempre consulte o status antes de efetivar
  6. Desfazimento no mesmo dia - Implemente controle para permitir desfazimento apenas no dia da efetivação

❌ Evite

  1. ❌ Não exponha o token JWT no frontend
  2. ❌ Não tente efetivar pré-autorizações PIX manualmente
  3. ❌ Não ignore os códigos de status HTTP
  4. ❌ Não faça polling excessivo no endpoint de status

🆘 Suporte

Contato Técnico

Em Caso de Erro

  1. Anote o traceId retornado no erro
  2. Capture a requisição completa (sem dados sensíveis)
  3. Descreva o comportamento esperado vs. obtido
  4. Envie para o email de suporte com assunto: [API Arrecadação v2] - Descrição do Problema

📄 Licença

Apache 2.0


Última atualização: 24 de Fevereiro de 2026 Versão da API: 2.0