INTEGRAÇÕES E API
API de pagamentos: guia de integração para produto e engenharia
API de pagamentos permite que um sistema crie cobranças, consulte estados e execute operações autorizadas por código. Uma integração confiável começa no modelo de negócio: pedido, tentativa, reembolso e recebedor precisam ter estados claros antes de chamar endpoints. Contratos de payload, autenticação, idempotência e observabilidade devem ser definidos antes da entrada em produção.
Leia o contrato da API como produto
Revise recursos, campos obrigatórios, limites, versões e erros. Entenda quais operações são síncronas e quais dependem de eventos. Não baseie lógica em textos de mensagem quando existe código estável.
Autenticação e segregação
Mantenha segredos no servidor, use ambientes separados, aplique menor privilégio e registre rotação. Nunca exponha chave privada no navegador, aplicativo ou repositório.
Idempotência, eventos e estado
Envie uma chave idempotente ao criar operações suportadas e guarde o identificador retornado. Use webhooks para atualizações assíncronas e consulte a API para reconciliação quando necessário.
Da homologação à produção
- Teste sucesso e cada erro relevante.
- Valide timeout e repetição.
- Assine e registre eventos.
- Configure alertas e painéis.
- Documente runbook de incidente.
Se você quer avaliar esse desenho na sua operação, fale com um especialista da Marcha. A recomendação final depende do modelo de negócio, do fluxo financeiro e da análise cadastral e comercial.
Comece pelo domínio, não pelo endpoint
Desenhe pedido, cobrança, tentativa, recebedor, reembolso e disputa com estados próprios. Depois associe comandos e eventos da API. Isso impede que a aplicação copie cegamente estados externos que não representam o negócio.
Defina identificadores internos e externos e mantenha a relação. O sistema deve consultar uma tentativa sem depender de informação exibida no navegador.
Contrato, versões e erros
Valide tipos, limites, moedas, precisão e campos opcionais. Trate códigos HTTP e erros de negócio separadamente. Não transforme qualquer falha em recusa e não repita requisição não idempotente sem verificar o estado.
Fixe versão quando possível, acompanhe depreciações e use testes de contrato. Mudanças de payload devem falhar de maneira observável antes de afetar pedidos reais.
Entrada em produção observável
Use credenciais distintas, permissões mínimas e rotação. Registre latência, resultado, identificador e correlação sem gravar dados sensíveis. Configure alertas por aumento de erro e por pedidos sem estado final.
Prepare runbook para timeout, webhook atrasado, divergência e indisponibilidade. Faça liberação gradual e reconcilie amostras antes de ampliar volume.
Perguntas frequentes
Posso chamar a API direto do frontend?
Operações com credenciais privadas devem ocorrer no servidor.
Consulta substitui webhook?
Não completamente. Eventos reduzem atraso; consultas ajudam em reconciliação e recuperação.
O que é versionamento?
É a forma de evoluir o contrato sem quebrar integrações existentes. Acompanhe avisos e migrações.
Como tratar timeout?
Não assuma falha definitiva. Consulte ou repita com idempotência antes de criar outra cobrança.
Posso confiar apenas na resposta síncrona da API?
Não em todos os fluxos. A resposta pode ser pendente ou a conexão pode cair após o provedor processar. Combine resposta, consulta de estado e webhooks conforme a documentação. O processamento interno deve ser idempotente para que múltiplas confirmações não dupliquem a ação comercial.
O que deve entrar em um runbook de integração de pagamentos?
Inclua arquitetura, responsáveis, credenciais e rotação, endpoints críticos, códigos de erro, consultas de estado, webhooks, filas, painéis e contatos de escalonamento. Descreva como agir em timeout, duplicidade, indisponibilidade e divergência financeira. Use exemplos com identificadores fictícios e mantenha o documento ligado à versão em produção. O runbook deve ser testado em exercício, não apenas armazenado.