Cómo conectar ERP, ecommerce y pagos con APIs REST que no se rompen

Cuando la tienda online, el ERP y la pasarela de pago hablan idiomas distintos, el negocio lo siente: pedidos duplicados, stock desactualizado o cobros que nadie puede explicar. El problema no es “falta un endpoint”; es falta de un contrato claro entre sistemas.

Este artículo explica cómo diseñar APIs REST para integraciones servidor-a-servidor — con analogías simples, pasos concretos y el detalle técnico que un equipo necesita para construir sin acumular deuda. Aplica a ERP, ecommerce y pasarelas como Yappy, BAC o Paguelo Fácil.

Por qué importa para el negocio

Una integración frágil se comporta como un teléfono con mala señal: a veces llega el mensaje, a veces se duplica, a veces se pierde. Cada fallo cuesta soporte, contabilidad manual y confianza del cliente.

• Pedidos: el cliente pagó, pero el ERP no lo ve → retrasos de envío.
• Inventario: se vende lo que ya no hay → cancelaciones y mala reputación.
• Pagos: dos cobros por un solo intento → reclamos y chargebacks.
• Soporte: sin un ID compartido entre sistemas, nadie sabe qué falló.

Conceptos clave (en claro y en técnico)

Piensa en la API como una ventanilla de banco: hay un formulario (request), una respuesta firmada (response) y reglas para no cobrar dos veces el mismo documento (idempotencia).

• Contrato: qué se envía, qué se recibe y qué errores existen. En técnico: OpenAPI con ejemplos.
• Idempotencia: reintentar no duplica. En técnico: header Idempotency-Key en POST de creación.
• Versionado: cambios grandes no rompen clientes viejos. En técnico: /v1/ vs /v2/.
• Autenticación mínima: cada sistema solo puede hacer lo necesario. En técnico: API keys con scopes.
• Correlation ID: un número de seguimiento que viaja por todos los sistemas. Facilita soporte y logs.

Estructura de recursos recomendada

Patrón habitual para ecommerce + ERP + pagos:

Guía práctica: de cero a integración estable

1. 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 la firma con un secret compartido.
• OAuth2 client credentials cuando el proveedor lo exige (SAP, algunos ERP cloud).
• Rotación documentada; nunca keys en repos, query strings ni imágenes Docker.

2. Webhooks vs polling

Webhook es un aviso: “el pago se confirmó”. El emisor llama; el receptor valida firma, guarda el evento y responde 200. Es el canal preferido para eventos de negocio.

Polling es preguntar cada cierto tiempo: “¿ya hay novedades?”. Úsalo solo como respaldo o si el sistema externo no soporta callbacks. Siempre con backoff exponencial y límite de reintentos.

3. Errores predecibles

Una respuesta consistente permite que el otro sistema decida: ¿reintento, alerta o aborto?

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

4. Cuando el ERP está caído

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

Errores comunes

• Diseñar “un endpoint por pantalla” sin modelo de recursos estable.
• Marcar pedidos como pagados solo porque el usuario llegó a una URL de éxito.
• Reintentar POST sin idempotencia y duplicar cobros o pedidos.
• Cambiar el contrato en /v1/ sin aviso (breaking change silencioso).
• Logs sin correlation ID: soporte a ciegas entre sistemas.
• Credenciales compartidas “para todo” en lugar de scopes mínimos.

Checklist de integración

1. Contrato OpenAPI con ejemplos de request/response y errores.
2. Autenticación con scopes mínimos y rotación de keys.
3. Idempotencia en POST de creación (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. Sandbox y producción separados, con credenciales distintas.
9. Política de deprecación (p. ej. 90 días) antes de retirar un endpoint.
10. Tests de contrato entre consumidor y proveedor cuando hay varios equipos.

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