💳 App de Arrecadação

Este guia apresenta o passo a passo para integração com o serviço de arrecadação, permitindo pagamentos via PIX e Boleto, além de consulta de lojas.

🎯 Visão Geral

O serviço de arrecadação oferece funcionalidades para:

• PIX: Geração de QR Codes para extrato e carnê, consulta de status e comprovantes
• Boleto: Consulta de linhas digitáveis, geração de PDFs e boletos personalizados
• Fatura: Download de PDF de faturas
• Lojas: Listagem de estabelecimentos habilitados para arrecadação

URLs Base:

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

📚 Recursos Adicionais

• 🔧 Guia de Troubleshooting - Solução de problemas e erros comuns
• 📖 Especificação OpenAPI — Referência técnica completa (schemas, tipos, exemplos)

---

🔐 Autenticação

Esta API utiliza Red Hat SSO (Keycloak) com o fluxo Password Grant (usuário e senha).

Todos os endpoints requerem autenticação via Bearer Token (JWT) no header:

Authorization: Bearer <seu_access_token>

Propriedade	Valor
Sistema	Red Hat SSO (Keycloak)
Fluxo OAuth2	Password Grant
Tipo	Autenticação com usuário final (CPF + senha)
Tokens	Access Token + Refresh Token

Atenção

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

🔑 Como obter o token?

O token é gerado no fluxo de Login dos APPs. O access_token retornado deve ser enviado em todas as chamadas da área logada.

---

📱 Pagamentos via PIX

1️⃣ Gerar QR Code PIX para Extrato

Gera um QR Code PIX para pagamento de um extrato específico.

Endpoint: POST /pix/extrato/gerarQRCode

Body:

{
  "extrato": {
    "numeroExtrato": 295615140,
    "valorPago": 156.25,
    "valorTotal": 156.25
  }
}

Resposta de Sucesso (200):

{
  "chave": 500014617,
  "pixCopiaECola": "00020101021226820014BR.GOV.BCB.PIX2560api.itau/pix/qr/v2/cobv/...",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhE..."
}

Campos da Resposta:

• chave: Identificador único da transação PIX (use para consultar status)
• pixCopiaECola: Código copia e cola do PIX
• qrCodeBase64: Imagem do QR Code em formato Base64

Dica

Salve a chave retornada! Você precisará dela para consultar o status e comprovante do pagamento.

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Gerar QR Code PIX - Extrato para detalhes de erros e soluções.

2️⃣ Gerar QR Code PIX para Carnê

Gera QR Code para pagamento de parcelas de carnê via PIX.

Endpoint: POST /pix/carne/gerarQRCode

Body:

{
  "carne": {
    "valorTotal": 108.08,
    "parcelas": [
      {
        "loja": 260,
        "contrato": 629665805,
        "numParcela": 8
      }
    ]
  }
}

Resposta de Sucesso (200):

{
  "chave": 500014622,
  "pixCopiaECola": "00020101021226820014BR.GOV.BCB.PIX...",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhE..."
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Gerar QR Code PIX - Carnê para detalhes de erros e soluções.

3️⃣ Consultar Status do Pagamento PIX

Verifica o status de processamento de um pagamento PIX.

Endpoint: GET /pix/status/{chave}

Parâmetros:

• chave: Chave retornada na geração do QR Code

Exemplo: GET /pix/status/b5a0ebcf-81b4-4410-a05f-ef9c1430fd47

Resposta de Sucesso (200):

{
  "status": "EM_PROCESSAMENTO"
}

Possíveis Status:

• EM_PROCESSAMENTO: Pagamento em processamento
• REALIZADO: Pagamento confirmado
• Outros status conforme definido pela API

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Status PIX para detalhes de erros e soluções.

4️⃣ Consultar Comprovante PIX

Busca a data e hora do pagamento de um comprovante PIX.

Endpoint: GET /pix/comprovante/{chaveComprovante}

Parâmetros:

• chaveComprovante: Chave do comprovante PIX

Exemplo: GET /pix/comprovante/500014617

Resposta de Sucesso (200):

{
  "dataHoraPagamento": "07/10/2024 10:27:04"
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Comprovante PIX para detalhes de erros e soluções.

🧾u Pagamentos via Boleto

1️⃣ Consultar Linha Digitável do Extrato

Obtém a linha digitável de um boleto a partir do ID do extrato.

Endpoint: GET /boleto/extrato/{idExtrato}

Parâmetros:

• idExtrato: Identificador do extrato

Exemplo: GET /boleto/extrato/331480840

Resposta de Sucesso (200):

{
  "linhaDigitavel": "34191092487995406585451455740000040000000000000"
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Consultar Boleto Extrato para detalhes de erros e soluções.

2️⃣ Baixar PDF do Boleto (Extrato)

Obtém o arquivo PDF do boleto em formato Base64.

Endpoint: GET /boleto/extrato/{idExtrato}/pdf

Parâmetros:

• idExtrato: Identificador do extrato

Exemplo: GET /boleto/extrato/329941003/pdf

Resposta de Sucesso (200):

{
  "pdfBase64": "JVBERi0xLjYKJeLjz9MKNSAwIG91a1ABPC9TdMJOeXBlL0ZvcmdWm1sdGVy..."
}

Como usar o PDF

Para exibir ou fazer download do PDF, você precisa decodificar o Base64 e criar um arquivo PDF. Em JavaScript, você pode usar:

const pdfData = atob(response.pdfBase64);
const blob = new Blob([pdfData], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Boleto Extrato PDF para detalhes de erros e soluções.

3️⃣ Consultar Linha Digitável de Parcela do Carnê

Obtém a linha digitável de uma parcela específica de um carnê.

Endpoint: GET /boleto/carne/{contrato}/parcela/{parcela}

Parâmetros:

• contrato: Identificador do contrato
• parcela: Número da parcela

Exemplo: GET /boleto/carne/703601310/parcela/1

Resposta de Sucesso (200):

{
  "linhaDigitavel": "03399.05465 29100.414357 64122.801018 2 99890000001961"
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Boleto Carnê - Parcela para detalhes de erros e soluções.

4️⃣ Baixar PDF de Parcela do Carnê

Obtém o PDF de uma parcela específica do carnê.

Endpoint: GET /boleto/carne/{contrato}/parcela/{parcela}/pdf

Parâmetros:

• contrato: Identificador do contrato
• parcela: Número da parcela

Exemplo: GET /boleto/carne/703601310/parcela/1/pdf

Resposta de Sucesso (200):

{
  "pdfBase64": "JVBERi0xLjYKJeLjz9MKNSAwIG91a1ABPC9TdMJOeXBlL0ZvcmdWm1sdGVy..."
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Boleto Carnê - Parcela PDF para detalhes de erros e soluções.

5️⃣ Gerar Boleto Personalizado

Gera a linha digitável de um boleto personalizado com data e valor específicos.

Endpoint: GET /boleto/personalizado

Parâmetros Query:

• dataPagamento: Data do pagamento (formato: YYYY-MM-DD)
• valor: Valor do boleto

Exemplo: GET /boleto/personalizado?dataPagamento=2023-12-01&valor=700

Resposta de Sucesso (200):

{
  "linhaDigitavel": "233452354353454454353245"
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Boleto Personalizado para detalhes de erros e soluções.

📄 Fatura

Baixar PDF da Fatura

Obtém o PDF da fatura do cliente autenticado.

Endpoint: GET /fatura/pdf

Parâmetros Query:

• vencimento: Data de vencimento (formato: YYYY-MM-DD)

Exemplo: GET /fatura/pdf?vencimento=2021-05-15

Resposta de Sucesso (200):

{
  "pdfBase64": "JVBERi0xLjYKJeLjz9MKNSAwIG91a1ABPC9TdMJOeXBlL0ZvcmdWm1sdGVy..."
}

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Fatura PDF para detalhes de erros e soluções.

🏪 Consulta de Lojas

Listar Lojas Habilitadas

Retorna a lista de lojas habilitadas para arrecadação.

Endpoint: GET /lojas

Parâmetros Query (opcional):

• codigoTipoRecebimento: Filtra por tipo de recebimento
  • 0: Todos
  • 1: Private Label
  • 3: Ambos (Private & Mais)

Exemplo: GET /lojas?codigoTipoRecebimento=0

Resposta de Sucesso (200):

[
  {
    "codigoEstabelecimento": "21810",
    "nomeFantasia": "21810 - ESKALA 123 (ANAPOLIS)* 21810",
    "cnpj": "45067147002342",
    "bairro": "SETOR CENTRAL",
    "razaoSocial": "LOJAS ESKALA COM. TECIDOS E CONF. LTDA",
    "endereco": "R. ENG. PORTELA, 139",
    "cidade": "ANAPOLIS",
    "nomeParceria": "ESKALA"
  },
  {
    "codigoEstabelecimento": "29587",
    "nomeFantasia": "314 (BELO HORIZONTE IV)* 29587",
    "cnpj": "00914151001470",
    "bairro": "CENTRO",
    "razaoSocial": "MENDES RIGONATTI & CIA LTDA",
    "endereco": "RUA DOS CAETES 347",
    "cidade": "BELO HORIZONTE",
    "nomeParceria": "ESKALA"
  }
]

Problemas com este endpoint?

Consulte o 🔧 Troubleshooting - Listar Lojas para detalhes de erros e soluções.

Fluxo Completo de Pagamento PIX

Aqui está um exemplo de fluxo completo para pagamento via PIX:

Passo 1: Gerar QR Code

POST /pix/extrato/gerarQRCode
{
  "extrato": {
    "numeroExtrato": 295615140,
    "valorPago": 156.25,
    "valorTotal": 156.25
  }
}

Passo 2: Exibir QR Code para o Cliente

Use o qrCodeBase64 ou pixCopiaECola retornado para exibir ao cliente.

Passo 3: Verificar Status do Pagamento

GET /pix/status/{chave}

Faça chamadas periódicas até que o status seja REALIZADO.

Passo 4: Obter Comprovante (Opcional)

GET /pix/comprovante/{chaveComprovante}

Códigos de Resposta HTTP

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

Tratamento de Erros

As respostas de erro seguem o seguinte formato:

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

Exemplos de Integração

Exemplo com cURL (PIX)

curl -X 'POST' \
  'https://apihml.credsystem.com.br/arrecadacao-app/api/v1/pix/extrato/gerarQRCode' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "extrato": {
      "numeroExtrato": 295615140,
      "valorPago": 156.25,
      "valorTotal": 156.25
    }
  }'

Exemplo com cURL (Boleto)

curl -X 'GET' \
  'https://apihml.credsystem.com.br/arrecadacao-app/api/v1/boleto/extrato/331480840' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Boas Práticas

1. Polling de Status: Ao consultar o status do pagamento PIX, use intervalos de 3-5 segundos entre as chamadas
2. Timeout: Configure timeouts adequados (recomendado: 30 segundos)
3. Cache de PDFs: Considere fazer cache dos PDFs baixados para evitar requisições desnecessárias
4. Validação: Sempre valide os valores antes de gerar QR Codes ou boletos
5. Segurança: Nunca exponha tokens de autenticação em logs ou no frontend
6. Tratamento de Erros: Implemente tratamento robusto para todos os códigos de erro HTTP

Ambiente de Produção

Atenção

A URL base apresentada neste documento é do ambiente de homologação. Para produção, utilize a URL fornecida pela equipe técnica.

🎓 Recursos Adicionais

• 🔧 Guia de Troubleshooting — Solução de problemas e erros comuns
• 📄 Referência OpenAPI — Especificação técnica completa

Suporte

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