APIs REST para integrações entre ERP, ecommerce e gateways

Conectar um ERP com ecommerce e um gateway de pagamento exige mais do que “fazer um endpoint”. Exige contratos claros, autenticação robusta, tratamento de erros previsível e webhooks idempotentes. Sem isso, cada integração nova vira dívida técnica.

Este artigo descreve o design de APIs REST para integrações servidor a servidor entre ERP, lojas online e gateways como Yappy, BAC ou Paguelo Fácil.

Princípios de design

• Contratos explícitos: cada endpoint documenta request, response e códigos de erro.
• Idempotência: reenviar um POST não duplica pedidos nem cobranças.
• Versionamento: breaking changes vão para /v2/, sem patches silenciosos.
• Autenticação mínima: scopes por recurso, nunca credenciais em query strings.
• Observabilidade: correlation ID em cada request para rastrear fluxos cross-system.

Estrutura de recursos

Padrão recomendado para ecommerce + ERP:

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 assinatura com secret compartilhado.
• OAuth2 client credentials quando o provedor exige (SAP, alguns ERPs cloud).
• Rotação de keys documentada; nunca em repos nem em imagens Docker.

Webhooks vs polling

Webhooks para eventos de negócio: pagamento confirmado, estoque atualizado, envio despachado. O emissor notifica; o receptor valida assinatura, persiste e responde 200.

Polling só como fallback ou quando o sistema externo não suporta callbacks. Sempre com backoff exponencial e limite de reintentos.

Tratamento de erros

Respostas consistentes facilitam a integração:

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

• Códigos HTTP semânticos: 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 queries SQL em produção.
• correlation_id em header e body para suporte cross-system.

Resiliência quando o ERP está fora do ar

1. O ecommerce cria o pedido localmente com status pending_sync.
2. Um job em fila tenta sincronizar com o ERP com reintentos e backoff.
3. Se falhar após N tentativas, vai para dead-letter queue e alerta a equipe.
4. O cliente vê confirmação do pedido; a sincronização é reconciliada depois.

Versionamento sem quebrar clientes

• /v1/ na URL ou header Accept-Version: 1.
• OpenAPI/Swagger publicado e atualizado a cada release.
• Política de depreciação: aviso 90 dias antes de remover um endpoint.
• Testes de contrato (Pact ou similar) entre consumidor e provedor.

Checklist de integração

1. Contrato documentado (OpenAPI) com exemplos de request/response.
2. Autenticação com scopes mínimos e rotação de keys.
3. Idempotência em POST de criação (header Idempotency-Key).
4. Webhooks com validação HMAC e reintentos 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. Ambientes separados (sandbox/prod) com credenciais distintas.

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