API de envíos multipaquetería: qué debe resolver
Una API útil no solo genera PDFs: debe mantener identidad, evitar compras dobles, tolerar fallas parciales y devolver estados conciliables.
Actualizada: 2026-08-01
Puntos clave
- Cotizar y comprar deben ser operaciones separadas.
- Cada compra necesita una clave de idempotencia estable.
- Webhooks deben poder repetirse sin duplicar efectos.
- Guarda la respuesta cruda y una versión normalizada.
Flujo mínimo
- Validar origen, destino, paquete y unidades.
- Solicitar opciones y mostrar precio, servicio y estimado.
- Elegir una opción identificable, no solo un nombre.
- Comprar con una clave de idempotencia del pedido.
- Guardar folio, tracking, etiqueta y estado.
- Escuchar actualizaciones por webhook y conciliar.
Por qué la idempotencia es obligatoria
Una respuesta tardía no significa que la compra falló. Si el cliente reintenta con otra clave, puede pagar dos guías. La misma operación lógica debe reutilizar una clave estable y el servidor debe devolver el resultado previo cuando ya existe.
No uses un timestamp nuevo en cada intento. La clave debe representar el pedido o intento comercial, no la petición HTTP.
Fallas parciales y timeouts
En una cotización multipaquetería, un proveedor lento no debería borrar las opciones de los demás. Devuelve resultados parciales con advertencias estructuradas y un presupuesto total de tiempo.
En compra, el timeout es ambiguo: primero consulta el estado o reutiliza la misma idempotencia. Reintentar a ciegas es cómo se compran dos guías.
Datos y observabilidad
- IDs internos y externos separados.
- Moneda, valor y desglose del precio.
- Proveedor, servicio y opción seleccionada.
- Estado normalizado más respuesta original.
- Correlation ID por operación.
- Logs sin credenciales ni datos personales innecesarios.
Preguntas frecuentes
- ¿Debo guardar el PDF en mi sistema?
- Guarda al menos una referencia durable y una estrategia para recuperarlo. Revisa vigencia y permisos de las URLs del proveedor.
- ¿Qué debe hacer un webhook duplicado?
- Producir el mismo estado final sin crear otro movimiento, correo, guía o cargo.