API Pix: conciliação financeira em tempo real na prática
Aprenda a estruturar a conciliação financeira automatizada via API Pix, utilizando End-to-End ID, webhooks idempotentes e arquitetura resiliente.
A adoção do Pix como método de pagamento predominante no Brasil transferiu para a engenharia de software e para as equipes de tesouraria um desafio de alta complexidade: a conciliação financeira em tempo real sob regimes de alto volume transacional (TPV). Em operações com dezenas de milhares de liquidações por hora, métodos manuais ou rotinas assíncronas em lote (batch) geram gargalos de conciliação, assimetrias contábeis e atrasos na liberação de produtos ou serviços.
Integrar a infraestrutura de pagamento diretamente ao Sistema de Pagamentos Instantâneos (SPI) e ao Diretório de Identificadores de Contas Transacionais (DICT) via API Pix resolve esse atrito, desde que a arquitetura técnica contemple resiliência, idempotência e tratamento correto de eventos webhook.
O gargalo da conciliação tradicional frente ao Pix
Modelos tradicionais de liquidação, como TED e boleto bancário, historicamente operavam com janelas fixas de processamento e arquivos de remessa e retorno (formato CNAB). Esse fluxo permitia que a conciliação ocorresse no final do dia útil (D+0 ou D+1), com tempo hábil para intervenções manuais.
No Pix, a liquidação pelo SPI é final, irrevogável e ocorre em segundos, 24 horas por dia, 7 dias por semana. Quando uma empresa tenta operar o Pix em escala mantendo processos de conciliação baseados em extratos bancários periódicos (OFX ou relatórios de D+1), surgem problemas críticos:
- Divergência de status transacional: Pedidos em e-commerce ou plataformas SaaS permanecem retidos aguardando confirmação bancária, degradando a experiência do cliente final.
- Sobrecarga operacional: Equipes de backoffice precisam cruzar comprovantes enviados por clientes com extratos de contas correntes empresariais.
- Risco de duplicidade e falhas de crédito: Sem identificadores únicos e idempotência, transações reprocessadas podem gerar crédito duplicado em carteiras virtuais (wallets) ou subcontas.
A superação desse cenário exige que a camada de software assuma a gestão do ciclo de vida da transação em tempo real.
Pilares técnicos para automação via API Pix
Para que a automação de recebimentos e pagamentos funcione sem intervenção humana, a API Pix deve ser integrada com foco em quatro componentes fundamentais de arquitetura:
1. End-to-End ID como chave primária de auditoria
Cada transação no arranjo Pix recebe um identificador único universal denominado End-to-End ID (E2E ID), gerado conforme padrões estabelecidos pelo Banco Central do Brasil (BCB). Este identificador possui 32 caracteres alfanuméricos e referencia a transação desde o Provedor de Serviços de Pagamento (PSP) pagador, passando pelo SPI, até o PSP recebedor.
Estrutura do E2E ID:
[E/D] + [ISPB do PSP (8 dígitos)] + [Data/Hora UTC (YYYYMMDDHHMM)] + [Sequencial alfanumérico (11 dígitos)]
Exemplo: E00038166202310241430a1b2c3d4e5f
Sistemas de ERP e conciliação devem indexar o E2E ID como chave única em seus bancos de dados operacionais. Isso elimina ambiguidades em casos de múltiplos pagamentos com o mesmo valor e mesma data.
2. Idempotência e tratamento de Webhooks
A notificação do pagamento efetuado ocorre por meio de webhooks disparados pelo PSP diretamente para os servidores da empresa. No entanto, em redes distribuídas, falhas temporárias de rede (timeouts, erros 5xx) podem acionar políticas de retentativa (retry) por parte da API.
Para evitar que uma mesma notificação processe o mesmo crédito duas vezes:
- A aplicação receptora deve implementar controle de idempotência, utilizando o E2E ID ou o
txid(identificador da cobrança) como chave de trava lógica (lock). - Se uma mensagem de confirmação com um identificador já processado for recebida, a API deve responder com código HTTP
200 OKimediatamente, sem reexecutar regras de negócio internas.
3. QR Code Dinâmico com txid exclusivo
Diferente do QR Code estático, que permite múltiplos pagamentos com o mesmo código e dificulta a correlação automática, o QR Code Dinâmico vincula cada intenção de pagamento a um txid exclusivo.
Ao gerar uma cobrança imediata via API:
- A cobrança recebe metadados de validade, regras de juros, multas ou descontos se aplicável.
- O payload retornado inclui a linha digitável (Pix Copia e Cola) e a string em Base64 para renderização visual do QR Code.
- A baixa da cobrança no banco de dados da empresa é sincronizada instantaneamente assim que o webhook correspondente é validado.
Fluxo arquitetural: Da emissão à liquidação
Abaixo, detalhamos o ciclo de vida completo de uma liquidação automatizada via API Pix integrada à infraestrutura corporativa:
| Etapa | Componente Responsável | Ação Técnica |
|---|---|---|
| 1. Criação da Cobrança | ERP / Backend da Empresa | Dispara POST /v2/cob com payload JSON contendo valor, tempo de expiração e dados do pagador. |
| 2. Registro no PSP | API Pix (PSP Conectado ao SPI) | Registra a cobrança, gera o txid e assina os dados do payload. |
| 3. Apresentação | Frontend / Checkout | Exibe o QR Code dinâmico ou string Pix Copia e Cola ao usuário final. |
| 4. Pagamento e Liquidação | SPI (Banco Central) | Liquida os fundos na conta de liquidação do PSP recebedor em milissegundos. |
| 5. Callback | Webhook do PSP | Dispara evento POST assinado via TLS mútuo (mTLS) contendo o E2E ID e status CONCLUIDA. |
| 6. Conciliação Automática | Backend da Empresa | Valida assinatura do webhook, aplica trava de idempotência e atualiza o ledger contábil. |
Resiliência e contingência: Polling de segurança e reconciliação em lote
Embora os webhooks em tempo real representem o canal primário de ingestão de status, uma infraestrutura de tesouraria de nível corporativo não deve depender exclusivamente de um canal de mensageria assíncrono.
Para mitigar riscos de instabilidade na entrega de callbacks, a engenharia financeira deve implementar uma estratégia em duas frentes:
- Worker de Polling para Cobranças Pendentes: Um serviço em segundo plano que consulta, via requisições
GET /v2/cob/{txid}, as transações que ultrapassaram a janela esperada de pagamento sem confirmação de callback, assegurando a atualização de status antes da expiração da cobrança. - Reconciliação Extrato x Ledger: Ao término de janelas operacionais (por exemplo, a cada hora ou ao fechamento do dia), o sistema deve consumir o endpoint de extrato consolidado da API Pix para confrontar a totalização dos saldos em conta com os lançamentos efetuados no razão (general ledger).
Tratamento do Mecanismo Especial de Devolução (MED)
Um ponto crítico frequentemente negligenciado em projetos de conciliação é a automação de estornos e do Mecanismo Especial de Devolução (MED), instituído pela Resolução BCB nº 103.
Quando ocorre uma notificação de contestação por suspeita de fraude ou falha operacional:
- A API Pix notifica a empresa a respeito do bloqueio cautelar ou da solicitação de devolução.
- O sistema de conciliação precisa estar preparado para registrar transações com naturezas de débito vinculadas ao E2E ID original, alterando o status contábil da venda de forma automática.
- Manter o registro detalhado dos logs transacionais e payloads de API é essencial para responder a eventuais disputas no âmbito do MED dentro dos prazos regulatórios.
Critérios para selecionar a infraestrutura de API Pix
Empresas com alta demanda transacional devem avaliar com rigor a arquitetura do provedor de infraestrutura Pix. Aspectos como latência de resposta, suporte a mTLS, SLA de entrega de webhooks e conectividade direta com o SPI determinam o sucesso da automação.
A API Pix da BS Finance foi desenvolvida para atender operações que exigem estabilidade, alto throughput e facilidade de conciliação técnica. Com documentação aderente às especificações do Banco Central, endpoints otimizados para alto volume e webhooks com garantia de entrega, a infraestrutura permite que plataformas, marketplaces e grandes corporações operem suas tesourarias de ponta a ponta sem atritos operacionais. Consulte os especialistas de produto e compliance para estruturar a integração adequada ao seu modelo de negócio.
FAQ
Perguntas frequentes
O que é o End-to-End ID e qual sua função na conciliação?+
O End-to-End ID (E2E ID) é o código único universal de 32 caracteres gerado no âmbito do SPI para cada transação Pix. Ele permite rastrear o pagamento de ponta a ponta entre instituições, servindo como a chave primária ideal para auditoria e conciliação automatizada no ERP.
Como evitar a duplicidade de lançamentos no processamento de webhooks?+
A idempotência é garantida registrando o E2E ID ou txid no banco de dados logo na primeira confirmação. Se um webhook repetido for recebido (por retentativa do PSP), o sistema identifica a existência prévia da transação e retorna HTTP 200 sem duplicar o crédito na conta do cliente.
Por que o QR Code Dinâmico é indispensável para a conciliação em tempo real?+
O QR Code Dinâmico vincula um txid exclusivo a cada ordem de pagamento, permitindo saber exatamente qual pedido foi pago no momento da liquidação. O QR Code Estático não possui essa amarração única nativa, o que inviabiliza a automação precisa em grandes volumes.
O que acontece se a aplicação receptora falhar durante o envio do webhook?+
Em caso de indisponibilidade momentânea nos webhooks, o sistema deve contar com rotinas de contingência (polling) via consultas GET /v2/cob/{txid} e reconciliação periódica de extratos bancários fornecidos pela API Pix.
Fale com um especialista em API Pix
BaaS regulado, API Pix, contas digitais e cartões Visa em uma única integração.