Como conectar ERP, ecommerce e pagamentos com APIs REST que aguentam o tranco

Quando a loja online, o ERP e o gateway de pagamento falam línguas diferentes, o negócio sente: pedidos duplicados, estoque desatualizado ou cobranças que ninguém explica. O problema não é “falta um endpoint”; é falta de um contrato claro entre sistemas.

Este artigo explica como desenhar APIs REST para integrações servidor a servidor — com analogias simples, passos concretos e o detalhe técnico que um time precisa para construir sem acumular dívida. Aplica-se a ERP, ecommerce e gateways como Yappy, BAC ou Paguelo Fácil.

Por que importa para o negócio

Uma integração frágil se comporta como um telefone com sinal ruim: às vezes a mensagem chega, às vezes duplica, às vezes some. Cada falha custa suporte, contabilidade manual e confiança do cliente.

• Pedidos: o cliente pagou, mas o ERP não vê → atraso no envio.
• Estoque: vende-se o que já acabou → cancelamentos e má reputação.
• Pagamentos: duas cobranças por uma tentativa → reclamações e chargebacks.
• Suporte: sem um ID compartilhado entre sistemas, ninguém sabe o que falhou.

Conceitos-chave (em claro e em técnico)

Pense na API como o guichê de um banco: há um formulário (request), uma resposta assinada (response) e regras para não cobrar duas vezes o mesmo documento (idempotência).

• Contrato: o que se envia, o que se recebe e quais erros existem. Em técnico: OpenAPI com exemplos.
• Idempotência: reenviar não duplica. Em técnico: header Idempotency-Key em POST de criação.
• Versionamento: mudanças grandes não quebram clientes antigos. Em técnico: /v1/ vs /v2/.
• Autenticação mínima: cada sistema só faz o necessário. Em técnico: API keys com scopes.
• Correlation ID: um número de rastreio que viaja por todos os sistemas. Facilita suporte e logs.

Estrutura de recursos recomendada

Padrão habitual para ecommerce + ERP + pagamentos:

Guia prático: do zero a uma integração estável

1. Autenticação servidor a servidor

• API keys com scopes mínimos (somente leitura de estoque, somente escrita de pedidos).
• HMAC em webhooks: o receptor valida a assinatura com um secret compartilhado.
• OAuth2 client credentials quando o provedor exige (SAP, alguns ERPs cloud).
• Rotação documentada; nunca keys em repos, query strings nem imagens Docker.

2. Webhooks vs polling

Webhook é um aviso: “o pagamento foi confirmado”. O emissor chama; o receptor valida a assinatura, guarda o evento e responde 200. É o canal preferido para eventos de negócio.

Polling é perguntar de tempos em tempos: “já há novidades?”. Use só como fallback ou se o sistema externo não suportar callbacks. Sempre com backoff exponencial e limite de retentativas.

3. Erros previsíveis

Uma resposta consistente permite que o outro sistema decida: retentar, alertar ou abortar?

            {
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order 12345 does not exist",
    "correlation_id": "abc-123"
  }
}
          

• Códigos HTTP claros: 400 (input inválido), 401 (auth), 404 (não existe), 409 (conflito/idempotência), 429 (rate limit), 500 (erro interno).
• Nunca expor stack traces nem SQL em produção.
• Incluir correlation_id em header e body para suporte cross-system.

4. Quando o ERP está fora do ar

1. O ecommerce cria o pedido local com status pending_sync.
2. Um job na fila tenta sincronizar com retentativas e backoff.
3. Se falhar após N tentativas, vai para dead-letter queue e alerta a equipe.
4. O cliente já viu a confirmação; a sincronização é reconciliada depois.

Erros comuns

• Desenhar “um endpoint por tela” sem um modelo de recursos estável.
• Marcar pedidos como pagos só porque o usuário chegou a uma URL de sucesso.
• Reenviar POST sem idempotência e duplicar cobranças ou pedidos.
• Mudar o contrato em /v1/ sem aviso (breaking change silencioso).
• Logs sem correlation ID: suporte às cegas entre sistemas.
• Credenciais compartilhadas “para tudo” em vez de scopes mínimos.

Checklist de integração

1. Contrato OpenAPI com exemplos de request/response e erros.
2. Autenticação com scopes mínimos e rotação de keys.
3. Idempotência em POST de criação (Idempotency-Key).
4. Webhooks com validação HMAC e retentativas do emissor.
5. Filas para sincronização async com dead-letter.
6. Logs com correlation ID, sem PII nem secrets.
7. Rate limiting em endpoints públicos.
8. Sandbox e produção separados, com credenciais distintas.
9. Política de depreciação (ex.: 90 dias) antes de retirar um endpoint.
10. Testes de contrato entre consumidor e provedor quando há várias equipes.

Conecte com integrações, pagamentos no Panamá e proteção de APIs .