APIs REST para integraciones entre ERP, ecommerce y pasarelas

Conectar un ERP con un ecommerce y una pasarela de pago requiere más que “hacer un endpoint”. Requiere contratos claros, autenticación robusta, manejo de errores predecible y webhooks idempotentes. Sin eso, cada integración nueva se convierte en deuda técnica.

Este artículo describe el diseño de APIs REST para integraciones servidor-a-servidor entre ERP, tiendas online y pasarelas como Yappy, BAC o Paguelo Fácil.

Principios de diseño

• Contratos explícitos: cada endpoint documenta request, response y códigos de error.
• Idempotencia: reintentar un POST no duplica pedidos ni cobros.
• Versionado: cambios breaking van a /v2/, no se parchean en silencio.
• Autenticación mínima: scopes por recurso, nunca credenciales en query strings.
• Observabilidad: correlation ID en cada request para rastrear flujos cross-system.

Estructura de recursos

Patrón recomendado para ecommerce + ERP:

Autenticación servidor a servidor

• API keys con scopes mínimos (solo lectura de stock, solo escritura de pedidos).
• HMAC en webhooks: el receptor valida firma con secret compartido.
• OAuth2 client credentials cuando el proveedor lo exige (SAP, algunos ERP cloud).
• Rotación de keys documentada; nunca en repos ni en imágenes Docker.

Webhooks vs polling

Webhooks para eventos de negocio: pago confirmado, stock actualizado, envío despachado. El emisor notifica; el receptor valida firma, persiste y responde 200.

Polling solo como respaldo o cuando el sistema externo no soporta callbacks. Siempre con backoff exponencial y límite de reintentos.

Manejo de errores

Respuestas consistentes facilitan la integración:

            {
  "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 (no existe), 409 (conflicto/idempotencia), 429 (rate limit), 500 (error interno).
• Nunca exponer stack traces ni queries SQL en producción.
• correlation_id en header y body para soporte cross-system.

Resiliencia cuando el ERP está caído

1. El ecommerce crea el pedido localmente con estado pending_sync.
2. Un job en cola intenta sincronizar con el ERP con reintentos y backoff.
3. Si falla tras N intentos, va a dead-letter queue y alerta al equipo.
4. El cliente ve confirmación del pedido; la sincronización se reconcilia después.

Versionado sin romper clientes

• /v1/ en URL o header Accept-Version: 1.
• OpenAPI/Swagger publicado y actualizado con cada release.
• Política de deprecación: aviso 90 días antes de retirar un endpoint.
• Tests de contrato (Pact o similar) entre consumidor y proveedor.

Checklist de integración

1. Contrato documentado (OpenAPI) con ejemplos de request/response.
2. Autenticación con scopes mínimos y rotación de keys.
3. Idempotencia en POST de creación (header Idempotency-Key).
4. Webhooks con validación HMAC y reintentos del emisor.
5. Colas para sincronización async con dead-letter.
6. Logs con correlation ID, sin PII ni secretos.
7. Rate limiting en endpoints públicos.
8. Ambientes separados (sandbox/prod) con credenciales distintas.

Conecta con integraciones, pagos en Panamá y protección de APIs .