Integraciones con servicios externos para las funciones que no se resuelven internamente: facturación electrónica legal, procesamiento de pagos y logística de envíos.
¿Qué es?
APIs de terceros que el backend consume. No son propiedad de la empresa, pero resultan esenciales para cumplir obligaciones legales y operativas. Evolucionan de forma independiente y requieren credenciales (claves de API, certificados digitales).
Servicios incluidos
SUNAT (facturación): API de comprobantes electrónicos, obligatoria en Perú para toda venta. Devuelve el XML y el CDR de respuesta.
Pasarela de pagos: Procesa tarjetas de crédito y débito y devuelve la confirmación o el rechazo, asumiendo el cumplimiento PCI.
Courier (Olva): Genera guías de envío, rastrea paquetes y estima costos; sincroniza el estado con la base de datos.
Correo transaccional (SendGrid o AWS SES): Envía confirmaciones de compra, comprobantes y avisos de envío.
Funciones principales
SUNAT: Se envía el detalle del pedido y se recibe el comprobante validado con su serie y correlativo.
Pasarela de pagos: Se envía el monto y el token de la tarjeta y se recibe el resultado y el identificador de transacción para auditoría.
Courier: Se registra el envío con la dirección y se recibe el número de seguimiento; los webhooks notifican los cambios de estado.
Correo: Se envía la plantilla y el destinatario y se recibe el identificador del mensaje; puede fallar por rebote o filtrado.
Limitaciones y restricciones
Disponibilidad: Si SUNAT cae, no es posible facturar; si la pasarela cae, no es posible cobrar. Son puntos críticos de fallo.
Costos: Cada transacción de pago conlleva una comisión; SUNAT y el courier facturan por uso.
Límites de tasa: Cada servicio impone cuotas de peticiones por intervalo que conviene respetar.
Cambios de API: Una modificación del proveedor puede romper la integración y exige una actualización ágil.
Datos sensibles: No se almacenan los datos completos de la tarjeta (solo el token); su custodia se delega en el proveedor.
Propósito del componente
Externalizar funciones complejas y reguladas. Integrar una pasarela de pagos resulta más eficiente que construir una propia, y el uso de SUNAT es obligatorio para operar legalmente. En conjunto, reducen la carga operativa de la empresa.
Stack tecnológico recomendado
Pasarela de pagosSUNAT SOLOlva APISendGrid APIWebhooksReintentos
Por qué: Estos servicios no se construyen, se consumen; el valor está en integrarlos correctamente: gestión de fallos, reintentos y webhooks para los estados asíncronos.
Información técnica adicional
Autenticación: Cada servicio emplea sus propias claves de API, almacenadas en variables de entorno y nunca en el código.
Idempotencia: Las llamadas deben ser idempotentes para que un reintento no duplique la acción (por ejemplo, no emitir el comprobante dos veces).
Webhooks: SUNAT y el courier notifican eventos; deben implementarse receptores que validen la autenticidad de cada notificación.
Gestión de errores: Cada servicio falla de forma distinta (códigos específicos, rechazos por formato); requiere un tratamiento granular.
Plan de contingencia: Ante la caída de la pasarela, ofrecer transferencia bancaria; ante la del courier, gestión manual.
Métricas importantes
Tasa de éxito: Porcentaje de pagos aprobados; objetivo superior al 98%; por debajo del 95% indica un problema grave.
Latencia de terceros: Tiempo de respuesta; por encima de 5 s, mostrar "procesando" y esperar el callback.
Disponibilidad: Monitorizar el tiempo operativo de cada servicio en un panel visible para el equipo.
Costos: Consolidados mensualmente; la comisión de pagos debería mantenerse por debajo del 3% de los ingresos.
Los servicios externos son socios críticos: no se controla su disponibilidad, pero se depende de ellos. Conviene prever planes de contingencia para cuando fallen y monitorizarlos con el mismo rigor que los componentes propios.