Especificación de integración API
Integración: Pedidos de la tienda online a contabilidad
Versión: 1.0
Redactado por: Hamza Idrissi
Fecha: 5 de abril de 2029
1. Propósito
Enviar cada pedido pagado de la tienda online al sistema de contabilidad como factura de venta, para que finanzas no tenga que volver a introducirlo.
2. Sistemas
- Envía datos: Tienda online (API v2)
- Recibe datos: Sistema de contabilidad (API REST)
3. Flujo de datos
1. Un cliente paga un pedido.
2. La tienda envía un webhook al servicio de integración.
3. El servicio convierte el pedido en una factura y llama a la API de contabilidad.
4. El sistema de contabilidad devuelve un número de factura, que el servicio guarda en el pedido.
4. Endpoints y mensajes
| Método y ruta | Qué hace | Campos principales | Qué devuelve |
|---|---|---|---|
| POST /invoices | Crear una factura | Cuerpo: cliente, líneas, impuestos, total | Devuelve: id y número de factura |
| GET /customers?email= | Buscar un cliente | Devuelve: id de cliente o vacío | |
| POST /customers | Crear un cliente | Cuerpo: nombre, email, dirección |
5. Mapeo de campos
order.total_paid → invoice.total
order.billing_email → customer.email
order.items[].sku → line.product_code
6. Autenticación y seguridad
OAuth 2.0 con credenciales de cliente. Los tokens duran una hora. Los secretos se guardan en el almacén de secretos, nunca en el código. Todas las llamadas usan HTTPS. Los webhooks van firmados y se verifica la firma.
Los datos personales solo se envían cuando es necesario, no se escriben en los registros y están cubiertos por las condiciones de privacidad de ambos sistemas.
7. Errores y reintentos
Reintentar ante 429 y 5xx hasta 5 veces con retardos crecientes. No reintentar errores 4xx; registrarlos y avisar a finanzas. Cada factura tiene una clave única para que un reintento no pueda crear un duplicado.
8. Límites y volúmenes
La API de contabilidad permite 60 llamadas por minuto. Se esperan 400 pedidos al día, hasta 2.000 en días de ofertas.
9. Pruebas
Usar el entorno de pruebas de contabilidad. Probar un pedido normal, un pedido con descuento, un reembolso, un cliente que ya existe y una caída de la API.
10. Responsables y soporte
Responsable: equipo de comercio electrónico. Soporte: Hamza Idrissi. Escalado: servicio de soporte del proveedor de contabilidad.
11. Cambios y versionado
Cualquiera de las partes avisa con 30 días de antelación de un cambio incompatible.