Hemos publicado conectores de MRW, SEUR, Correos Express, DHL, GLS, UPS y CTT para Odoo, y hemos integrado transportistas en webs que no llevan Odoo detrás, como eclipseando.com. Las API cambian de nombre y de formato, pero el trabajo es siempre el mismo: cuatro llamadas, tres o cuatro errores que se repiten y una decisión de arquitectura que conviene tomar antes de escribir la primera línea. Este artículo es la versión para una web propia; si tu tienda lleva Odoo, la mayor parte ya está resuelta en los conectores de transportista.
Idea clave: la integración no termina cuando sale la etiqueta. Termina cuando el cliente recibe el aviso de que su paquete está en camino, o parado en un punto de recogida, sin que nadie de tu equipo haya copiado nada. Si diseñas solo la etiqueta, harás el resto a mano.
Antes de programar: el alta y el entorno de pruebas
Ningún transportista te da acceso a su API por rellenar un formulario en la web. Hace falta un contrato de transporte con un comercial, y de ahí salen las credenciales: un código de cliente o abonado, un usuario y una contraseña o clave, y a veces un código de franquicia o de agencia. Pídelas desde el primer día y pide también el entorno de pruebas, que no todos tienen y no todos se comportan como producción. Algunas API siguen siendo SOAP con XML (es el caso histórico de varios transportistas españoles); otras son REST con JSON. No cambia lo que hay que hacer, cambia cuánto cuesta leer la documentación.
Las cuatro llamadas
| Llamada | Qué le mandas | Qué te devuelve | Dónde se rompe |
|---|---|---|---|
| Crear envío | Remitente, destinatario, bultos, peso, servicio, referencia de pedido. | Número de expedición y, casi siempre, la etiqueta en la misma respuesta. | Direcciones sin normalizar, códigos postales de Canarias o Baleares, teléfonos con espacios, caracteres fuera de ASCII. |
| Etiqueta | Número de expedición y formato (PDF, ZPL, tamaño). | El fichero, normalmente en base64. | Pedirla dos veces y generar dos expediciones; imprimir en A4 lo que era 10×15. |
| Seguimiento | Número de expedición. | Lista de eventos con fecha, código y texto. | Consultar cada minuto y que te corten; no traducir los códigos a estados propios. |
| Manifiesto / cierre | Fecha y expediciones del día. | Confirmación o documento de recogida. | Olvidarlo: el transportista no recoge lo que no está manifestado. |
Crear el envío: la mitad del trabajo es limpiar la dirección
La llamada de creación es donde se concentran los rechazos. Cada transportista tiene su idea de qué es una dirección válida: longitud máxima de la calle, código postal de cinco dígitos exactos, provincia como código y no como texto, teléfono obligatorio y sin prefijo, y en varios, nada fuera de ASCII en el nombre. Lo que funciona es normalizar antes de llamar: separar calle y número, recortar campos al máximo que admite cada API, sustituir tildes cuando la API no las acepta, y validar que el código postal exista para ese país. Y guardar siempre la petición y la respuesta completas, en XML o JSON, junto al pedido. Cuando un paquete se pierde tres semanas después, esa traza es la única prueba de lo que se mandó.
Seguimiento: sondeo con cabeza, o webhook si lo hay
Pocos transportistas avisan por webhook; la mayoría hay que preguntarles. La forma correcta es una tarea programada que consulta solo las expediciones abiertas, con un intervalo razonable (cada hora suele bastar, más a menudo el día de la entrega), que se detiene cuando el estado es final y que respeta los límites de la API. Los códigos de evento se traducen a un conjunto pequeño de estados propios: aceptado, en tránsito, en reparto, entregado, incidencia, devuelto. Cinco o seis, no cuarenta. Y cada cambio de estado dispara el aviso al cliente, que es para lo que se hace todo esto.
Cuando no tienes la API porque el que envía es tu proveedor
Es más frecuente de lo que parece: vendes tú, pero el paquete lo prepara y lo envía un proveedor con su propio contrato de transporte. No tienes credenciales, no puedes crear el envío ni consultar la expedición. Lo que sí tienes, casi siempre, son los correos que el transportista manda a la dirección de contacto por cada movimiento. En eclipseando.com lo resolvimos así con GLS: una tarea lee el buzón cada diez minutos, reconoce los cuatro tipos de correo (en camino, en reparto, en punto de recogida con fecha límite, destinatario ausente), saca el número de expedición y el pedido al que pertenece, y convierte cada uno en un estado y un aviso al comprador. Los dos últimos son los urgentes: un paquete en un punto de recogida vuelve al remitente si nadie va a buscarlo, y un cliente que no sabe que está allí no va.
Los errores que vemos en producción
- Probar solo contra el sandbox. Varios transportistas tienen un entorno de pruebas que acepta lo que producción rechaza. La prueba que vale es un envío real a tu propia oficina.
- Crear el envío al confirmar el pedido en la web. Se crea al preparar el paquete. Si se crea antes, cada cancelación es una expedición fantasma que a veces se factura.
- No guardar la petición y la respuesta. Sin XML o JSON completos junto al pedido, una reclamación es tu palabra contra la del transportista.
- Un solo número de seguimiento por pedido. Funciona hasta el primer pedido con dos bultos o dos proveedores. El seguimiento se modela por envío.
- Certificados y cifrado antiguos. Algunas API siguen en TLS con cifrados que las librerías modernas rechazan por defecto. Se detecta el primer día, no el de la puesta en marcha.
Con Odoo detrás, casi nada de esto se programa
Si la tienda lleva Odoo, las cuatro llamadas ya están escritas en los conectores que publicamos en el App Store, probados en Odoo 19, 18 y 17 sobre Odoo.sh real: la etiqueta sale al validar el albarán, el seguimiento se consulta por cron y se escribe en el albarán, el manifiesto se cierra desde el propio Odoo y el aviso al cliente sale por correo o SMS con la plantilla que quieras. La web solo tiene que leer el estado del albarán. Por eso, cuando alguien nos pide integrar un transportista en una web y ya tiene Odoo, la respuesta suele ser conectar la web al ERP, no volver a escribir la integración.
Preguntas frecuentes
¿Cuánto se tarda en integrar un transportista?
Depende sobre todo de dos cosas que no controlas: cuánto tarda el transportista en darte credenciales y entorno de pruebas, y si su API es REST con documentación actual o SOAP con un PDF de hace años. Las cuatro llamadas en sí son trabajo acotado; lo que alarga son las esperas y las pruebas con envíos reales.
¿Se pueden integrar varios transportistas a la vez?
Sí, y conviene diseñarlo así desde el principio: una capa propia con las cuatro operaciones (crear, etiqueta, seguimiento, manifiesto) y un adaptador por transportista debajo. Añadir el segundo cuesta una fracción del primero si el primero se hizo con esa separación.
¿Y si mi proveedor envía con su transportista y yo no tengo acceso?
Se trabaja con lo que llega: los correos del transportista o los ficheros que el proveedor devuelva. Leerlos automáticamente y convertirlos en estados y avisos no es tan limpio como una API, pero elimina la copia manual y, sobre todo, evita que un cliente no sepa que su paquete está esperando en un punto de recogida.
Enlaces útiles dentro de FlexigoTech
¿Tienes que conectar un transportista y no sabes por dónde empezar?
Dinos cuál es, si tienes ya credenciales y si hay Odoo detrás. Te decimos qué se programa, qué ya existe y qué hay que pedirle al transportista antes de empezar. Escribe a comercial@flexigobe.com o llama al +34 616 809 504.