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

💳 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:

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

Autenticação

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

Header obrigatório:

Authorization: Bearer <seu_token_jwt>

Importante

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

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.

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..."
}

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

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"
}

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"
}

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);

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"
}

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..."
}

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"
}

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..."
}

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"
  }
]

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://bff-app-arrecadacao-hml.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://bff-app-arrecadacao-hml.credsystem.com.br/arrecadacao-app/api/v1/boleto/extrato/331480840' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Boas Práticas

Polling de Status: Ao consultar o status do pagamento PIX, use intervalos de 3-5 segundos entre as chamadas
Timeout: Configure timeouts adequados (recomendado: 30 segundos)
Cache de PDFs: Considere fazer cache dos PDFs baixados para evitar requisições desnecessárias
Validação: Sempre valide os valores antes de gerar QR Codes ou boletos
Segurança: Nunca exponha tokens de autenticação em logs ou no frontend
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.

Suporte

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

Visão Geral​

Autenticação​

Pagamentos via PIX​

1. Gerar QR Code PIX para Extrato​

2. Gerar QR Code PIX para Carnê​

3. Consultar Status do Pagamento PIX​

4. Consultar Comprovante PIX​

Pagamentos via Boleto​

1. Consultar Linha Digitável do Extrato​

2. Baixar PDF do Boleto (Extrato)​

3. Consultar Linha Digitável de Parcela do Carnê​

4. Baixar PDF de Parcela do Carnê​

5. Gerar Boleto Personalizado​

Fatura​

Baixar PDF da Fatura​

Consulta de Lojas​

Listar Lojas Habilitadas​

Fluxo Completo de Pagamento PIX​

Passo 1: Gerar QR Code​

Passo 2: Exibir QR Code para o Cliente​

Passo 3: Verificar Status do Pagamento​

Passo 4: Obter Comprovante (Opcional)​

Códigos de Resposta HTTP​

Tratamento de Erros​

Exemplos de Integração​

Exemplo com cURL (PIX)​

Exemplo com cURL (Boleto)​

Boas Práticas​

Ambiente de Produção​

Suporte​

Visão Geral

Autenticação

Pagamentos via PIX

1. Gerar QR Code PIX para Extrato

2. Gerar QR Code PIX para Carnê

3. Consultar Status do Pagamento PIX

4. Consultar Comprovante PIX

Pagamentos via Boleto

1. Consultar Linha Digitável do Extrato

2. Baixar PDF do Boleto (Extrato)

3. Consultar Linha Digitável de Parcela do Carnê

4. Baixar PDF de Parcela do Carnê

5. Gerar Boleto Personalizado

Fatura

Baixar PDF da Fatura

Consulta de Lojas

Listar Lojas Habilitadas

Fluxo Completo de Pagamento PIX

Passo 1: Gerar QR Code

Passo 2: Exibir QR Code para o Cliente

Passo 3: Verificar Status do Pagamento

Passo 4: Obter Comprovante (Opcional)

Códigos de Resposta HTTP

Tratamento de Erros

Exemplos de Integração

Exemplo com cURL (PIX)

Exemplo com cURL (Boleto)

Boas Práticas

Ambiente de Produção

Suporte