ℹ️ 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.

📄 Extrato e Faturas

Guia completo para consultar extratos, faturas e transações do cartão de crédito dos seus clientes.

Introdução

Este serviço permite que você acesse informações completas sobre as faturas do cartão de crédito, incluindo:

📋 Consulta de faturas (passadas, atual e futuras)
💳 Detalhamento de transações
💰 Opções de parcelamento de fatura
🧾 Verificação de possibilidade de pagamento

URLs Base:

Produção: https://api.credsystem.com.br/extrato-app/api/v1
Homologação: https://apihml.credsystem.com.br/extrato-app/api/v1

Autenticação

Todas as requisições precisam incluir o token de autenticação no header:

Authorization: Bearer <seu_token_jwt>

Atenção

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

Consultando Faturas

1. Consultar Fatura Atual

A fatura atual é aquela que está em aberto no momento.

Endpoint: GET /faturas/atual

Exemplo de Request:

GET /extrato-app/api/v1/faturas/atual HTTP/1.1
Host: bff-app-extrato-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "numeroExtrato": 331869059,
  "dataProcessamento": "2024-11-28",
  "dataVencimento": "2024-12-10",
  "flagSituacao": " ",
  "numeroEmissao": 1,
  "valorMinimo": 33.96,
  "valorSaldoAtual": -169.81,
  "valorTotalCredito": 0.00,
  "valorTotalDebito": 169.81,
  "valorTotalFechamento": -169.81,
  "valorSaldoAnterior": 0.00,
  "descricaoSituacao": "Em aberto",
  "possuiBoleto": true,
  "dataFechamento": "2024-11-28",
  "valorTotalAPagar": 169.81
}

Campos da Resposta:

numeroExtrato: Identificador único da fatura
dataVencimento: Data limite para pagamento
valorMinimo: Valor mínimo permitido para pagamento
valorTotalAPagar: Valor total da fatura
valorTotalDebito: Total de gastos do período
valorTotalCredito: Total de créditos (estornos, contestações)
possuiBoleto: Se existe boleto disponível para pagamento

Situações da Fatura:

" " (vazio): Em Aberto
"A": Em Atraso
"L": Liquidada/Paga

Importante

Use o numeroExtrato para consultas detalhadas e parcelamento.

2. Consultar Faturas Passadas

Retorna histórico de faturas já fechadas. A quantidade retornada pode ser configurada via Backoffice.

Endpoint: GET /faturas/passadas

Resposta de Sucesso (200):

[
  {
    "numeroExtrato": 331775197,
    "dataProcessamento": "2024-10-28",
    "dataQuitacao": "2024-11-08",
    "dataUltimoPagamento": "2024-11-08",
    "dataVencimento": "2024-11-10",
    "flagSituacao": "L",
    "numeroEmissao": 1,
    "valorMinimo": 75.56,
    "valorSaldoAtual": 0.00,
    "valorTotalCredito": 0.00,
    "valorTotalDebito": 377.80,
    "valorTotalFechamento": 377.80,
    "valorSaldoAnterior": 0.00,
    "descricaoSituacao": "Liquidado",
    "possuiBoleto": false,
    "dataFechamento": "2024-10-28",
    "valorTotalAPagar": 377.80
  }
]

Campos Adicionais:

dataQuitacao: Data em que a fatura foi paga
dataUltimoPagamento: Data do último pagamento recebido
dataProcessamento: Data em que a fatura foi processada

Histórico Completo

Use este endpoint para exibir o histórico de faturas pagas do cliente.

3. Consultar Faturas Futuras

Retorna as próximas faturas que ainda não fecharam. Útil para mostrar gastos futuros.

Endpoint: GET /faturas/futuras

Resposta de Sucesso (200):

[
  {
    "numeroExtrato": 331869060,
    "dataVencimento": "2025-01-10",
    "flagSituacao": " ",
    "numeroEmissao": 1,
    "valorMinimo": 0.00,
    "valorSaldoAtual": -50.00,
    "valorTotalCredito": 0.00,
    "valorTotalDebito": 50.00,
    "valorTotalFechamento": -50.00,
    "valorSaldoAnterior": 0.00,
    "descricaoSituacao": "Em aberto",
    "possuiBoleto": false,
    "dataFechamento": "2024-12-28",
    "valorTotalAPagar": 50.00
  }
]

Dica

Faturas futuras mostram compras já realizadas que cairão na próxima fatura ou nas seguintes.

4. Listar Todas as Faturas

Retorna a lista completa de faturas (passadas, atual e futuras).

Endpoint: GET /faturas

Resposta de Sucesso (200):

[
  {
    "dataProcessamento": "2023-10-28",
    "dataQuitacao": "2023-11-08",
    "dataUltimoPagamento": "2023-11-08",
    "dataVencimento": "2023-11-10",
    "flagSituacao": "L",
    "numeroEmissao": 1,
    "valorMinimo": 75.56,
    "valorSaldoAtual": 0,
    "valorTotalCredito": 377.8,
    "valorTotalDebito": 377.8,
    "valorTotalFechamento": -377.8,
    "valorSaldoAnterior": 0,
    "descricaoSituacao": "Liquidado",
    "isPossuiBoleto": false,
    "dataFechamento": "2023-10-28",
    "valorTotalAPagar": 377.8,
    "status": "PASSADA"
  },
  {
    "dataProcessamento": "2024-11-28",
    "dataQuitacao": "",
    "dataUltimoPagamento": "",
    "dataVencimento": "2024-12-10",
    "flagSituacao": " ",
    "numeroEmissao": 1,
    "valorMinimo": 33.96,
    "valorSaldoAtual": -169.81,
    "valorTotalCredito": 0,
    "valorTotalDebito": 169.81,
    "valorTotalFechamento": -169.81,
    "valorSaldoAnterior": 0,
    "descricaoSituacao": "Em atraso",
    "isPossuiBoleto": true,
    "dataFechamento": "2024-11-28",
    "valorTotalAPagar": 169.81,
    "status": "ATUAL"
  }
]

Status Possíveis:

PASSADA: Fatura já fechada
ATUAL: Fatura em aberto atual
PROXIMA: Próxima fatura
FECHADA: Fatura já processada

Detalhes da Fatura

Consultar Transações da Fatura

Veja todas as transações (compras, estornos, encargos) de uma fatura específica.

Endpoint: GET /faturas/detalhes

Parâmetros Query (obrigatórios):

idCartao: ID do cartão
vencimento: Data de vencimento no formato yyyy-mm-dd

Exemplo:

GET /faturas/detalhes?idCartao=36964187&vencimento=2024-12-10 HTTP/1.1
Host: bff-app-extrato-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

[
  {
    "categoria": {
      "descricao": "Alimentação",
      "icone": "alimentacao_icon.png",
      "idCategoria": 5
    },
    "data": "2024-11-15T00:00:00.000Z",
    "idTransacao": 1878998580,
    "lancamento": "Compra",
    "nome": "RESTAURANTE DO CHEF",
    "tipoTransacao": "COMPRA",
    "tipoLancamento": "DEBITO",
    "titular": true,
    "valor": "R$ 89,90"
  },
  {
    "categoria": {
      "descricao": "Servicos",
      "icone": "servicos_icon.png",
      "idCategoria": 13
    },
    "data": "2024-11-03T00:00:00.000Z",
    "idTransacao": 18,
    "lancamento": "Encargos Contratuais",
    "nome": "ENCARGOS MENSAIS",
    "tipoTransacao": "ENCARGO",
    "tipoLancamento": "DEBITO",
    "titular": true,
    "valor": "R$ 4,09"
  }
]

Campos da Transação:

categoria: Categoria da transação com ícone
data: Data da transação
idTransacao: ID único da transação
lancamento: Descrição do lançamento
nome: Nome do estabelecimento
tipoTransacao: Tipo (COMPRA, ENCARGO, ESTORNO, etc.)
tipoLancamento: DEBITO ou CREDITO
titular: Se a compra foi feita pelo titular ou adicional
valor: Valor formatado em reais

Tipos de Transação:

COMPRA: Compra realizada
ENCARGO: Juros, taxas, encargos
ESTORNO: Devolução de compra
PAGAMENTO: Pagamento recebido
AJUSTE: Ajustes diversos

Detalhes de Transação

Consultar Informações Completas

Obtenha detalhes de uma transação específica, incluindo dados do estabelecimento.

Endpoint: GET /transacao/{idTransacao}

Exemplo:

GET /transacao/1878998580 HTTP/1.1
Host: bff-app-extrato-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "parcelaAtual": 4,
  "totalParcela": 4,
  "totalRestante": 0,
  "valorCompra": "R$ 429,87",
  "nomeEstabelecimento": "Park Maceio",
  "endereco": "Av Comendador Gustavo Paiva 5945",
  "bairro": "Cruz Das Almas",
  "cidade": "Maceio",
  "estado": "AL",
  "cep": "57038-000"
}

Informações Retornadas:

parcelaAtual: Número da parcela atual
totalParcela: Total de parcelas da compra
totalRestante: Parcelas restantes
valorCompra: Valor total da compra original
Dados completos do estabelecimento (endereço, cidade, estado, CEP)

Uso Prático

Use estas informações para exibir detalhes da compra quando o cliente clicar em uma transação.

Parcelamento de Fatura

Consultar Opções de Parcelamento

Veja as opções disponíveis para parcelar uma fatura.

Endpoint: GET /faturas/{numeroExtrato}/parcelamento

Exemplo:

GET /faturas/331775197/parcelamento HTTP/1.1
Host: bff-app-extrato-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

[
  {
    "qtdParcelas": 4,
    "valorParcela": 26.93,
    "tipoParcelamento": 8
  },
  {
    "qtdParcelas": 5,
    "valorParcela": 22.71,
    "tipoParcelamento": 8
  },
  {
    "qtdParcelas": 6,
    "valorParcela": 19.94,
    "tipoParcelamento": 8
  }
]

Campos:

qtdParcelas: Quantidade de parcelas disponível
valorParcela: Valor de cada parcela
tipoParcelamento: Código do tipo de parcelamento

Importante

As opções de parcelamento variam conforme configuração do emissor e valor da fatura.

Verificação de Pagamento

Verificar se Fatura Permite Pagamento

Antes de permitir que o cliente pague, verifique se a fatura está pagável.

Endpoint: GET /faturas/permitePagamento/{numeroExtrato}

Exemplo:

GET /faturas/permitePagamento/331869059 HTTP/1.1
Host: bff-app-extrato-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json

Resposta de Sucesso (200):

{
  "permitePagamento": true
}

Valores Possíveis:

true: Fatura pode ser paga
false: Fatura não permite pagamento (já paga, cancelada, etc.)

Boa Prática

Sempre verifique antes de exibir opções de pagamento ao cliente.

Códigos de Resposta

Código	Status	Descrição
200	✅ Sucesso	Requisição processada com sucesso
204	∅ Sem conteúdo	Sem dados para retornar (ex: sem faturas)
400	⚠️ Bad Request	Parâmetros inválidos
401	⛔ Unauthorized	Token inválido ou expirado
500	💥 Internal Error	Erro interno do servidor

Tratamento de Erros

{
  "error": {
    "message": "Descrição do erro",
    "code": 400
  }
}

Fluxo Recomendado

1. Consultar Fatura Atual
   ↓
2. Exibir Resumo (valor total, vencimento, situação)
   ↓
3. Cliente clica em "Ver Detalhes"
   ↓
4. Consultar Transações da Fatura
   ↓
5. Exibir lista de compras/lançamentos
   ↓
6. Cliente clica em uma transação específica
   ↓
7. Consultar Detalhes da Transação
   ↓
8. Exibir informações completas do estabelecimento e parcelas

Fluxo de Pagamento

1. Consultar Fatura Atual
   ↓
2. Verificar se Permite Pagamento
   ↓
3. SE permite:
   ├─ Consultar Opções de Parcelamento
   ├─ Exibir valor total, mínimo e opções
   └─ Permitir que cliente escolha forma de pagamento
   ↓
4. SE não permite:
   └─ Informar que fatura não está disponível para pagamento

Boas Práticas

1. Performance

Cache a fatura atual localmente
Atualize apenas quando necessário
Use paginação para histórico longo

2. UX/Interface

Destaque a data de vencimento
Use cores para status (verde=pago, vermelho=atrasado, amarelo=aberto)
Agrupe transações por categoria
Mostre gráficos de gastos por categoria

3. Validações

Sempre verifique permitePagamento antes de processar
Valide formato de datas (yyyy-mm-dd)
Trate casos de 204 No Content (cliente sem faturas)

4. Segurança

Nunca exponha tokens nos logs
Implemente retry com backoff em caso de erro 500
Valide sempre o token antes de fazer requisições

Exemplos de Uso

Exemplo 1: Listar Faturas com Status Visual

# 1. Buscar todas as faturas
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/faturas' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer TOKEN'

# 2. Para cada fatura, aplicar cor baseada em flagSituacao:
# " " (vazio) = Amarelo (Em aberto)
# "A" = Vermelho (Em atraso)
# "L" = Verde (Liquidado)

Exemplo 2: Exibir Detalhes Completos

# 1. Buscar fatura atual
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/faturas/atual' \
  -H 'Authorization: Bearer TOKEN'

# 2. Com o numeroExtrato retornado, buscar transações
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/faturas/detalhes?idCartao=123&vencimento=2024-12-10' \
  -H 'Authorization: Bearer TOKEN'

# 3. Para cada transação, permitir drill-down:
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/transacao/1878998580' \
  -H 'Authorization: Bearer TOKEN'

Exemplo 3: Processo de Parcelamento

# 1. Verificar se permite pagamento
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/faturas/permitePagamento/331775197' \
  -H 'Authorization: Bearer TOKEN'

# 2. Se permitePagamento = true, buscar opções
curl -X 'GET' \
  'https://bff-app-extrato-hml.credsystem.com.br/extrato-app/api/v1/faturas/331775197/parcelamento' \
  -H 'Authorization: Bearer TOKEN'

# 3. Exibir opções para o cliente escolher

Glossário

Termo	Significado
Extrato	Número identificador único da fatura
Fechamento	Data em que a fatura foi fechada e não aceita mais lançamentos
Vencimento	Data limite para pagamento sem juros
Quitação	Data em que a fatura foi totalmente paga
Valor Mínimo	Menor valor aceito como pagamento
Saldo Anterior	Valor que veio da fatura anterior
Débito	Total de gastos/compras
Crédito	Total de estornos/devoluções
CET	Custo Efetivo Total (juros + encargos)

Dicas de Integração

Início Rápido: Comece com GET /faturas/atual para exibir a fatura principal
Histórico: Use GET /faturas/passadas para histórico simplificado
Detalhamento: Implemente drill-down com /faturas/detalhes e /transacao/{id}
Parcelamento: Sempre verifique elegibilidade antes de mostrar opções
Categorização: Use os ícones de categoria para melhor UX visual

Suporte

Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.

Introdução​

Autenticação​

Consultando Faturas​

1. Consultar Fatura Atual​

2. Consultar Faturas Passadas​

3. Consultar Faturas Futuras​

4. Listar Todas as Faturas​

Detalhes da Fatura​

Consultar Transações da Fatura​

Detalhes de Transação​

Consultar Informações Completas​

Parcelamento de Fatura​

Consultar Opções de Parcelamento​

Verificação de Pagamento​

Verificar se Fatura Permite Pagamento​

Códigos de Resposta​

Tratamento de Erros​

Fluxo Recomendado​

Fluxo de Pagamento​

Boas Práticas​

1. Performance​

2. UX/Interface​

3. Validações​

4. Segurança​

Exemplos de Uso​

Exemplo 1: Listar Faturas com Status Visual​

Exemplo 2: Exibir Detalhes Completos​

Exemplo 3: Processo de Parcelamento​

Glossário​

Dicas de Integração​

Suporte​

Introdução

Autenticação

Consultando Faturas

1. Consultar Fatura Atual

2. Consultar Faturas Passadas

3. Consultar Faturas Futuras

4. Listar Todas as Faturas

Detalhes da Fatura

Consultar Transações da Fatura

Detalhes de Transação

Consultar Informações Completas

Parcelamento de Fatura

Consultar Opções de Parcelamento

Verificação de Pagamento

Verificar se Fatura Permite Pagamento

Códigos de Resposta

Tratamento de Erros

Fluxo Recomendado

Fluxo de Pagamento

Boas Práticas

1. Performance

2. UX/Interface

3. Validações

4. Segurança

Exemplos de Uso

Exemplo 1: Listar Faturas com Status Visual

Exemplo 2: Exibir Detalhes Completos

Exemplo 3: Processo de Parcelamento

Glossário

Dicas de Integração

Suporte