Cómo integrar la API de SEUR en tu TMS

Si tu equipo sigue generando etiquetas de SEUR a mano desde el portal Pro+ o depende de un plugin de PrestaShop pensado para una tienda online pequeña, este tutorial te lleva paso a paso desde el alta en la plataforma de desarrollo hasta el primer envío en producción. El objetivo es integrar la API SEUR en tu TMS para que las etiquetas, recogidas y eventos de tracking entren directamente en tu sistema de gestión de transporte, sin exportar Excel ni copiar números de expedición a mano.

Por qué SEUR necesita otra integración además del plugin de tu ecommerce

Porque un plugin de Shopify o PrestaShop está diseñado para pedidos B2C de baja complejidad, no para el volumen y la lógica de negocio de un cargador industrial. SEUR ofrece una serie de soluciones para integrar tu tienda online con sus servicios, pensadas para que los clientes disfruten de una experiencia de envío, seguimiento y devolución satisfactoria. Eso funciona bien para una tienda con 200 pedidos al día. No funciona cuando necesitas que el sistema de creación de envío hable directamente con tu ERP, aplique tus reglas de transportista por código postal o alimente el mismo cuadro de mando donde ya controlas tus rutas de carga completa.

SEUR es la mayor red de paquetería privada de España por volumen y pertenece al grupo GeoPost, lo que le da salida directa a la red europea de DPD. SEUR is a GeoPost carrier and the dominant private parcel network in Spain by volume, and through GeoPost sus envíos se extienden a destinos europeos vía la red internacional de DPD. Esa conectividad importa poco si tu integración se queda en un plugin: la API pública (conocida internamente como servicio PIC, probada en la plataforma SDS) es la vía para que un TMS multitransportista trate a SEUR igual que trata a tu operador de FTL o al resto de paqueteros nacionales.

Qué necesitas antes de tocar una sola línea de código

Antes de abrir Postman necesitas tres cosas en orden: contrato comercial activo, credenciales técnicas separadas para pruebas y producción, y claridad sobre quién en tu organización aprueba el paso a real. Sin esto, el desarrollo se detiene en la primera llamada.

• Cuenta comercial activa con SEUR, con tu código de cliente o franquicia asignado por tu gestor comercial.
• Credenciales técnicas: usuario, contraseña, VAT, franquicia, SEURID, CI y CCC. Estos siete valores son los que exige el propio conector de referencia para autenticar cualquier llamada, tal y como documenta el proyecto python-seur en GitHub: la conexión se instancia con username, password, vat, franchise, seurid, ci y ccc antes de poder crear o consultar un envío.
• Acceso propio a la plataforma de pruebas SDS (sds.seur.io), con un usuario de desarrollador validado por SEUR antes de poder operar.
• Un entorno de preproducción claramente separado del de producción, porque ambos usan hosts distintos y credenciales distintas.
• Un colega de compras o IT que confirme el volumen mensual real de envíos con SEUR, porque ese número es el que decide si te conviene esta integración directa o una plataforma multitransportista que ya trae SEUR precableado.

Si tu empresa ya trabaja con cinco o seis transportistas de paquetería además de SEUR, vale la pena leer primero la sección final de este artículo antes de invertir semanas de desarrollo carrier por carrier.

Los 7 pasos para conectar la API PIC de SEUR a tu TMS

El proceso completo, desde el registro hasta el primer envío piloto en real, se resuelve en siete pasos concretos. Ninguno es opcional si quieres una integración estable.

1. Registro y activación en SDS. Solicita el alta en sds.seur.io. SEUR valida al usuario desde su plataforma interna antes de conceder acceso: hasta que SEUR no valide el usuario desde la plataforma IM, no se tendrá acceso a la plataforma SDS. Recibirás dos correos de confirmación; sin el segundo, la cuenta queda a medias y las llamadas devuelven error de autenticación.
2. Alta de la clave API y obtención del token. Desde SDS obtienes tu Client ID y Client Secret. El propio manual recomienda importar la colección en Postman para generar la primera petición de autenticación: se importa la petición en formato raw text, se completa la importación y Postman genera la llamada al servicio web de autenticación con todos los parámetros necesarios, que se envía para obtener el Bearer token. Activa únicamente los métodos de entrega que realmente usas (nacional, internacional, Frío) para evitar ruido en las respuestas.
3. Configuración del tipo de envío "SEUR" en tu TMS. Da de alta un nuevo transportista con nombre comercial, código simbólico interno y el campo "Integrar con" apuntando al conector API en lugar de a un fichero plano o EDI, que es como probablemente tienes configurados tus transportistas de carga completa.
4. Mapeo de campos obligatorios del servicio de creación de envío. El servicio de picking exige, como mínimo, servicio, product, total_bultos, referencia_expedicion, ref_bulto y los datos de destinatario. El conector de referencia en python-seur ilustra bien el detalle exigido: cliente_cpostal, cliente_pais, cliente_email, cliente_telefono y cliente_atencion son campos que la API espera para completar el envío. Mapea cada uno contra el campo equivalente de tu pedido en SAP, Oracle o Dynamics antes de probar nada.
5. Llamada de prueba en preproducción. El entorno de pruebas usa un host propio (el manual apunta, por ejemplo, al servicio https://servicios.apipre.seur.io/pic/v1/pickups para la creación de recogidas). Genera un envío de prueba y confirma que la etiqueta sale en PDF o ZPL sin errores. El conector de referencia soporta ambos formatos activando context['printer'] = 'ZEBRA' para ZPL o context['pdf'] = True para obtener el PDF.
6. Activación de la trazabilidad. Conecta el servicio de tracking para que cada evento (recogida, tránsito, entrega, incidencia) llegue a tu TMS y no obligue a nadie a mirar el portal web de SEUR. Este es el paso que más valor aporta a un director de logística: visibilidad automática sin trabajo manual diario.
7. Migración a producción y envío piloto. Cambia credenciales y host al entorno real, y valida con un piloto controlado, no con toda tu operación de golpe. Un fallo de campo obligatorio en producción cuesta mucho más que en pruebas, porque ya hay mercancía física en la calle.

Cómo saber que la integración funciona

La integración funciona cuando puedes cerrar el ciclo completo sin intervención manual: crear, imprimir y rastrear. Antes de dar por cerrado el proyecto, verifica estos cuatro puntos.

• La etiqueta se genera sin errores y con el número de expedición devuelto directamente por la API, no copiado de un correo.
• El evento de recogida aparece tanto en el propio sistema de SEUR como en tu TMS, con la misma marca de tiempo.
• El estado del pedido cambia automáticamente en tu ERP cuando SEUR reporta entrega, sin que nadie tenga que refrescar una pantalla.
• Un envío con dirección incompleta o peso fuera de rango devuelve un error legible, no un timeout silencioso.

El fallo más común: mezclar entornos de prueba y producción

El error que más tiempo hace perder a los equipos de IT es probar credenciales de preproducción contra el endpoint de producción, o viceversa. La API responde con errores de autenticación que parecen un problema de código cuando en realidad son un problema de entorno. Antes de escalar el ticket a soporte de SEUR, comprueba tres cosas: que el host de la llamada corresponde al entorno activo, que el Client ID y Client Secret son los del mismo entorno, y que campos obligatorios como clave_portes o total_kilos no llegan vacíos cuando el servicio los exige. Otro detalle que se pasa por alto: el servicio de picking está pensado para paquetería, no para carga general. Los envíos deben ser monobulto y no pueden superar los 30 kilos de peso, así que si tu operación mezcla paquetería con palets, necesitarás una lógica de enrutado previa en el TMS que decida qué va por SEUR y qué va por tu transportista de carga completa.

Cuándo integrar carrier por carrier deja de tener sentido

Tiene sentido construir esta integración directa cuando SEUR es tu único paquetero relevante. El problema aparece en cuanto sumas GLS, Correos Express, MRW o DHL Express a la lista: cada uno tiene su propio manual, sus propios campos obligatorios y sus propios códigos de error, y ese trabajo hay que repetirlo entero por cada transportista nuevo.

Para operaciones de más de 10.000 envíos al mes, la recomendación suele ser evitar plataformas que cobran comisión por envío y optar por un modelo neutral: elegir plataformas neutrales como Cargoson, ProShip o nShift, tal y como recoge la comparativa de software multitransportista de Cargoson. Si tu volumen con SEUR es alto pero manejable, la integración directa que acabas de construir sigue siendo la opción más barata a largo plazo. Si SEUR es uno de siete transportistas que gestionas, cada hora de desarrollo dedicada a un conector propio es una hora que no dedicas a negociar tarifas.

Antes de tu próximo pico de envíos

Documenta las siete credenciales (usuario, contraseña, VAT, franquicia, SEURID, CI y CCC) en un gestor de secretos, no en un Excel compartido. Mantén el entorno de preproducción activo todo el año, no solo durante el desarrollo inicial, porque cada campaña de Black Friday o Navidad es el peor momento para descubrir que un campo obligatorio cambió sin aviso. Y si esta integración es la quinta o sexta que tu equipo levanta este año contra un transportista distinto, es la señal de que ha llegado el momento de evaluar un TMS con conectividad multi-transportista nativa en lugar de seguir sumando conectores uno a uno.