Central de Ajuda

Aparência

Rotinas Pix ​

Introdução ​

O formulário de Rotinas Pix é uma ferramenta essencial para o gerenciamento de cobranças do tipo Pix de APIs de pagamento. Ele auxilia na consulta manual de status de cobranças em casos de falha no fluxo de envio de Logs de Pagamento pelo Webhook da API.

Acesso ao Formulário

Caminho: Menu Configurações > Rotinas Financeiro > Rotinas Pix

Benefícios ​

  • Atualização manual do status das cobranças do tipo Pix
  • Redução de erros manuais na verificação de pagamentos
  • Melhoria na conciliação financeira

Estrutura do formulário ​

O formulário de Rotinas Pix é composto por uma aba que contém filtros de obrigatoriedade, e tem como intuito realizar requisições às APIs Pix.

Rotinas Pix ​

Esta aba permite preencher os filtros de busca e de cadastro de carteira, a fim de comunicar o Sistema diretamente com a integração bancária. Esta comunicação gera uma requisição para a API Pix, trazendo ao Sistema os Logs de Pagamento, que são retornos de confirmação de status das cobranças presentes na instituição financeira (conforme o filtro de datas), a fim de atualizar seu status no sistema.

Em situações onde ocorre alguma instabilidade ou falha com o envio da API Pix, a consulta traz ao Sistema todos os Logs de Pagamento que não foram enviadas durante o período da falha, e após o seu processamento no Sistema, suas respectivas cobranças (Contas a Receber) terão seus status atualizados no Sistema.

Rotina de consultas via API Pix

A rotina de consultas via API Pix retorna logs de liquidação tanto para cobranças avulsas quanto para cobranças recorrentes (Pix Automático).

Campos da Aba ​

CampoDescrição
Carteira de cobrançaSeleção da carteira de cobrança Pix
Data recebimento inicialData inicial para o filtro de recebimento
Data recebimento finalData final para o filtro de recebimento
SenhaCampo para inserir a senha
Alerta!

Para a execução desta rotina de consulta se faz necessário a inserção de uma senha. Entre em contato com o Suporte Técnico para obter a senha ou requisitar o auxilio do suporte na execução da rotina.

Casos de Uso ​

Aba Logs consulta de pagamentos ​

Conceito da aba ​

A aba "Logs consulta de pagamentos" é uma nova funcionalidade adicionada em formato de grid para listar e armazenar todos os registros de requisições e respostas trocadas com as APIs Bancárias e Gateways de Pagamento durante as consultas de cobranças.

Objetivo funcional ​

O objetivo primário desta aba é otimizar o processo de diagnóstico de problemas relacionados à compensação de pagamentos. Ao registrar o tráfego de dados com as instituições financeiras, visa-se diminuir a necessidade de abertura de chamados suporte, uma vez que a análise poderá ser realizada pela própria interface do Sistema.

Integração com o fluxo atual do formulário ​

A funcionalidade de log atua de forma transparente, registrando as informações independentemente se a consulta for acionada de forma manual pela interface do sistema ou executada automaticamente por uma tarefa de rotina. Os logs são agrupados em registros de lote para evitar lentidão no formulário em bases com alto fluxo de informações.

Campos disponíveis ​

Ao selecionar um registro na grid e clicar na opção de "Visualizar", o sistema abre um novo formulário apresentando os seguintes campos:

  • ID: Identificador único do log de consulta no Sistema.
  • ID carteira de cobrança: A carteira de cobrança utilizada para realizar a consulta.
  • Status: Indica se a consulta teve sucesso ("Consulta de pagamento concluída com sucesso.") ou falha ("Erro ao realizar consulta de pagamento.").
  • Log: Descrição de status da consulta (em caso de sucesso, retornará "Consulta de pagamento concluída com sucesso").
  • Método HTTP: O verbo HTTP utilizado na requisição, como GET ou POST.
  • URL: O endpoint exato acionado durante a comunicação.
  • Cabeçalho da requisição: Os headers enviados ao banco/gateway.
  • Corpo da requisição: O body com os dados ou parâmetros da busca enviados pelo sistema.
  • Corpo da resposta: O retorno bruto entregue pela integração externa (ex: dados da compensação).
  • Status HTTP: O código de status da comunicação (ex: 200, 400, 500).
  • Data criação: Data e hora exatas da execução da rotina ou clique no botão de consulta.

Comportamento da interface ​

A aba apresenta os logs listados em uma estrutura de grid. O status da consulta é destacado por um selo de cor verde quando indica "Sucesso". Dentro da tela de visualização do registro, existe um botão dedicado para copiar instantaneamente o conteúdo completo da requisição para a área de transferência do usuário, já devidamente formatado em JSON.

Regras de negócio ​

As requisições geradas por uma rotina de consulta são consolidadas para salvar apenas um log de lote que contenha as requisições, melhorando a performance de consulta. Sempre que uma das tarefas de consulta for acionada (como "Processamento retorno Asaas API", "Consulta Pagamento Sicredi Api", etc.), o log deve ser gerado contendo um "Número da consulta" para garantir rastreabilidade das diferentes chamadas e páginas pertencentes à mesma ação.

Fluxo de uso passo a passo ​

  1. O usuário acessa o menu de Rotinas Pix.
  2. Executa normalmente a consulta preenchendo as informações e dados necessários.
  3. O sistema envia a requisição para a API bancária correspondente e recebe a resposta.
  4. O sistema grava automaticamente essas interações nos registros de log.
  5. O usuário acessa a aba "Logs consulta de pagamentos" no formulário da rotina.
  6. O usuário seleciona a linha desejada na grid e aciona o botão de Visualizar para auditar a requisição e a resposta, ou copiar o JSON da transação.

Exemplos práticos reais ​

Cenário: Um cliente do provedor entra em contato relatando que seus pagamentos finais não estão sendo compensados no sistema. O provedor roda a consulta de pagamentos e a rotina finaliza, mas a liquidação não ocorre. Uso do recurso: Em vez de abrir um chamado técnico com o suporte, o atendente acessa a aba "Logs consulta de pagamentos", clica em visualizar o log correspondente à data e verifica imediatamente o corpo da resposta da API do Gateway. Ele pode atestar rapidamente se a instabilidade ou ausência de registros está vindo diretamente da integração bancária.

Cenários de erro possíveis ​

Se a requisição retornar falha do lado do banco ou gateway, o sistema ainda criará o registro. O log será salvo com a indicação de status "Falha" (exibindo a mensagem "Erro ao realizar consulta de pagamento.") e o corpo da resposta guardará a mensagem de erro fornecida pela própria API bancária para facilitar o diagnóstico.

Observações importantes

Existem comportamentos específicos conforme a arquitetura de cada Gateway: ​
  • Sicredi (v2): A consulta irá salvar um log por dia consultado.
  • Bradesco e Efí: A consulta avalia os dados verificando boleto por boleto no sistema a partir da data de vencimento, e armazena a requisição individual para cada boleto.
  • Santander, Lytex, BTG, CelPayments, Asaas: Possuem buscas paginadas, salvando um log respectivo para cada página de registros retornada. Se houver um erro nessas integrações, apenas um único log consolidado de falha será salvo.
  • Banco do Brasil: Baseada em API cURL sem paginação moderna, retorna todos os pagamentos de uma só vez, criando apenas um log de sucesso ou de erro.
Limitações conhecidas ​
  • Iugu: Atualmente não possui a funcionalidade de consulta implementada.
  • Widepay e Banco do Brasil: Tratando-se de integrações antigas, elas não disparam exceções tradicionais, mas apenas retornam JSONs. Um cabeçalho genérico é gravado no log.
  • Sicoob API (v3): O processo retorna os pagamentos agrupados em um arquivo ZIP que exige dois passos distintos de consulta. Por ser massivo, requer atenção ao espaço em texto que consome no log.
  • Credisis: A comunicação ocorre via SOAP API utilizando formato XML em vez de JSON.

Considerações finais ​

O formulário de Rotinas Pix é uma ferramenta fundamental para manter a integridade e atualização dos dados financeiros no sistema. Ao automatizar o processo de verificação e atualização de status das cobranças, esta rotina contribui significativamente para a eficiência operacional e a precisão dos registros financeiros da empresa.

Leia Também ​

Disponibilizado por IXC S.A.

© 2025