Uma API Pix é a interface programável que permite a um sistema criar cobranças Pix, receber a confirmação do pagamento e reconciliar o valor sem intervenção humana. Em vez de gerar um QR Code manualmente no aplicativo do banco, a aplicação faz uma requisição HTTP e recebe de volta o código Pix Copia e Cola e a imagem do QR Code dinâmico.
Como funciona uma cobrança Pix via API
O fluxo padrão tem quatro etapas e é o mesmo em praticamente todo provedor sério do mercado brasileiro:
- A aplicação autentica-se com uma credencial secreta (na Pitra, uma API Key no cabeçalho Authorization).
- A aplicação cria a cobrança informando valor, descrição e dados do cliente. O provedor devolve um identificador, o payload Copia e Cola e o QR Code.
- O pagador lê o QR Code ou cola o código no aplicativo do banco e confirma o pagamento.
- O provedor envia um webhook assinado para a aplicação avisando que a cobrança foi paga — é esse evento que libera o pedido, o acesso ou a entrega.
O passo 4 é o que separa uma integração amadora de uma profissional. Confiar apenas em consulta periódica (polling) aumenta latência e custo; o webhook entrega a confirmação em segundos.
QR Code dinâmico e Pix Copia e Cola
O QR Code dinâmico carrega valor, identificador e prazo de expiração próprios daquela cobrança. Isso permite reconciliar automaticamente: cada pagamento chega vinculado a um pedido específico. O Pix Copia e Cola é a mesma informação em texto (padrão EMV), útil em telas onde o cliente não consegue apontar a câmera — como quando ele já está no celular.
Webhook: a confirmação do pagamento
Assim que o pagamento é liquidado, o provedor faz uma requisição HTTP POST para a URL cadastrada pela loja. Uma implementação correta valida a assinatura do webhook, responde rápido (2xx) e processa o restante em segundo plano. Se a resposta falhar, o provedor deve reenviar o evento com backoff.
Segurança mínima de uma integração Pix
- Chave secreta apenas no servidor — nunca no front-end, nunca em repositório público.
- HTTPS obrigatório em todas as chamadas e no endpoint de webhook.
- Validação de assinatura HMAC em todo evento recebido.
- Idempotência nas criações de cobrança, para que um retry de rede não gere cobrança duplicada.
- Registro de logs sem dados sensíveis do pagador.
O que avaliar antes de escolher uma API Pix
| Critério | Por que importa |
|---|---|
| Tempo de resposta | Cobrança lenta derruba conversão: o cliente desiste antes do QR Code aparecer. |
| Webhook assinado | Sem assinatura, qualquer um pode simular um pagamento aprovado. |
| Idempotência | Evita cobrança duplicada em retry de rede. |
| Documentação e SDK | Reduz o tempo de integração de dias para horas. |
| Ambiente de testes | Permite validar o fluxo inteiro sem mover dinheiro real. |
| Observabilidade | Status público e logs de entrega de webhook facilitam o suporte. |
Como a Pitra resolve isso
A Pitra expõe uma API REST com autenticação por Bearer token, criação de cobrança Pix com QR Code dinâmico e Copia e Cola, webhooks assinados com HMAC, idempotência por chave, ambiente de testes, SDK oficial para Node.js/TypeScript e especificação OpenAPI para importar no Postman ou gerar clientes.
Perguntas frequentes
- Preciso de CNPJ para usar uma API Pix?
- Depende do provedor e da conta de recebimento. Na Pitra, o cadastro é feito com os dados da loja e a conta de recebimento é vinculada durante a configuração.
- Quanto tempo leva para integrar uma API Pix?
- Com documentação e SDK, uma integração básica de cobrança e webhook costuma levar poucas horas. O que consome tempo é o tratamento de erros, idempotência e reconciliação.
- A API Pix funciona 24 horas por dia?
- Sim. O Pix opera 24 horas por dia, todos os dias, inclusive fins de semana e feriados.