Connectar SEUR amb Odoo: què demana l'API, què falla i quan compensa

Sí, SEUR es connecta amb Odoo, i per al cas base sense desenvolupament a mida: el mòdul delivery_seur_atlas del repositori OCA l10n-spain, AGPL-3, per a Odoo 15 a 19. Parla amb l'API Atlas per REST, crea l'expedició en validar l'albarà, adjunta l'etiqueta al picking i escriu el codi d'enviament a carrier_tracking_ref. El que ningú explica és quines credencials demana, què passa amb el multibulto i el reembossament, i per què el seguiment de vegades no torna.

Es pot connectar SEUR amb Odoo?

Sí. El mòdul afegeix «Seur Atlas» a la llista de proveïdors del mètode d'enviament i, a partir d'aquí, SEUR és un transportista més dins d'Inventari. Depèn de tres mòduls OCA de delivery-carrier (delivery_package_number, delivery_price_method i delivery_state) i sense els tres no s'instal·la.

La pregunta útil no és si es pot, sinó què cobreix. Cobreix alta d'expedició, etiqueta, número de seguiment a l'albarà, enllaç de rastreig, anul·lació i històric d'estats. No cobreix tarifes, reembossament ni mesures reals de paquet. La resta de l'article és el detall d'aquestes dues llistes.

Què cal abans de tocar Odoo

Contracte amb SEUR i credencials d'Atlas, que no surten d'un panell d'autoservei: el README del mòdul diu que les demanis a la teva oficina de SEUR. Són sis camps i convé tenir-los tots sis abans d'obrir el mètode d'enviament.

Usuari i contrasenya per una banda, client_id i client_secret per l'altra: quatre secrets, no dos. El mòdul els demana amb els noms d'Odoo (usuari, contrasenya, client, secret), que no tenen per què coincidir amb els del contracte: convé mapar-los abans d'omplir res.

Dos detalls que surten cars. L'entorn del mètode d'enviament decideix si es crida a apipre o a api, i no és una casella: és el botó de la capçalera que alterna entre Test Environment i Production Environment. Si es queda en proves, expedeixes contra apipre i aquestes etiquetes no valen. I el timeout per defecte és de 5 segons, canviable amb el paràmetre seur_atlas_timeout; amb latència es queda curt i el magatzem veu un error que no ho és.

Què es genera en validar i en quin format surt l'etiqueta

En prémer Validar, el mòdul envia l'expedició, rep un shipmentCode, l'escriu al camp de seguiment del picking i descarrega les etiquetes, que queden com a adjunts de l'albarà. Cap portal a part: l'únic que s'interposa és l'assistent de bultos, i només quan l'albarà no porta paquets fets.

• Format: PDF, ZPL o A4 troquelat.
• Plantilla: NORMAL, CUSTOM_REFERENCE, Z4_ONE_BODY, Z4_TWO_BODIES o GEOLABEL. Canvia el disseny, no el format del fitxer.
• Sortida: el fitxer, un enllaç de descàrrega o els dos. Amb «enllaç» no et arriba l'etiqueta, et arriba una URL.
• QR AZTEC: hi ha casella, però el mateix camp avisa que només val per a recollides ECB.

El detall que crema: el ZPL no es desa com a PDF ni com a .zpl, sinó com a adjunt .txt en ISO-8859-15, a propòsit, perquè SEUR envia l'etiqueta amb la instrucció ^CI10. Si la teva cua d'impressió el reconverteix a UTF-8, els accents del destinatari surten trencats: el fitxer és correcte, l'intermediari l'espatlla.

Multibulto: el cas que trenca les integracions ingenues

El mòdul envia una llista de bultos construïda a partir de number_of_packages, l'enter que aporta delivery_package_number i que un assistent demana en validar. El problema és el que hi ha dins de cada bulto.

• El pes es reparteix a parts iguals: el pes de l'enviament dividit pel nombre de bultos. Dos bultos de 2 i 18 kg es declaren com a 10 i 10.
• Les mesures van a 1×1×1. Literalment, al codi, amb un TODO al costat que ho reconeix. Amb això, les mesures que rep SEUR no són les del bulto real: qualsevol càlcul seu que depengui del volum parteix d'una dada que el mòdul s'ha inventat.
• Si el nombre de bultos és zero, la llista surt buida. El camp té 0 per defecte: si el tipus d'operació no pregunta per bultos, o algú valida des de codi, s'envia una expedició sense bultos.

I la tornada, que és on fa mal a suport: la resposta que el mateix test del mòdul reprodueix porta tres coses (shipmentCode, ecbs i parcelNumbers) i el codi només llegeix la primera. Si un client reclama un bulto de sis, qui l'atén no en té el número. Les etiquetes sí que tornen una per bulto: cadascuna amb el seu codi de bulto, que és el que dona nom a l'adjunt, i un camp pack del tipus «1/6» que el mòdul ni mira.

Contra reembossament: quin camp el porta i què passa si falta

Resposta curta: cap. L'enviament que s'envia a SEUR no porta import de reembossament. L'únic semblant és un camp charges fixat a «P» al codi, que diu qui paga el port: «P» l'empresa, «D» el destinatari. No hi ha casella per canviar-lo i el comentari del codi ho admet. Això és el port, no el reembossament.

Què passa si falta: l'expedició surt sense reembossament, el repartidor lliura sense cobrar i t'assabentes tard, per l'històric d'esdeveniments. El mòdul tradueix els codis de SEUR que envolten el reembossament (LI534 «comprovar si és reembossament», LI541 «sense efectiu al lliurament», LI552 «no accepten reembossament»), així que els esdeveniments arriben; l'import és el que no s'envia mai. Si vens així, això és desenvolupament, no configuració.

Per què el tracking no sempre torna a Odoo

Tres motius, tots al codi, i cap és «l'API va malament».

1. És un cron diari, no temps real

delivery_state instal·la una acció planificada, «Update deliveries states», amb interval d'un dia. Recorre els albarans en estat Fet l'estat de transportista dels quals no sigui ja lliurat, anul·lat o «sense més actualitzacions». Si esperes veure l'estat deu minuts després d'expedir, no passarà: o baixes l'interval, o prems el botó a l'albarà. Qui parla de «tracking en temps real» no ha mirat el cron.

2. Pregunta per la teva referència, no pel codi de SEUR

La consulta va amb tipus de referència REFERENCE i, com a referència, el nom de l'albarà (WH/OUT/00042), no el codi d'expedició que va retornar SEUR. Si l'expedició es va donar d'alta fora d'Odoo, es va crear al portal amb una altra referència o l'albarà es va reanomenar, SEUR no retorna res i el mòdul surt en silenci: ni estat, ni error, ni avís. Sembla que funciona. A més, el codi de compte es parteix pel guió per treure compte i unitat de negoci: sense guió, la crida ni es fa.

3. L'estat que intenta escriure ja no existeix

Aquest és el bo. El mòdul tradueix 403 codis d'esdeveniment de SEUR als estats de delivery_state. D'aquests, 101 apunten al valor incidence, igual que el valor per defecte per a qualsevol codi desconegut. I incidence ja no és a aquesta llista: la branca 15.0 de delivery_state el tenia, la 16.0 el va reanomenar a incident i hi continua a la 19.0, mentre que el mòdul de SEUR no ho va canviar a cap de les seves cinc branques. Un camp de selecció d'Odoo no accepta un valor que no sigui a la seva llista: aixeca un ValueError. Hi ha un codi, LI730, que a més apunta a la cadena literal «SEE MESSAGE», que tampoc és un valor vàlid.

Traduït a magatzem: mentre tot va bé, el tracking torna. Tan bon punt un enviament entra en incidència (absent, adreça desconeguda, retingut a duana) o arriba un codi que el mòdul no coneix, l'actualització d'aquest albarà cau. Des del cron, l'error es desa en un camp del picking i s'avisa al canal d'administració, on no mira ningú; des del botó, et salta a la cara. És el patró exacte de la queixa: «el tracking va… fins que hi ha un problema». I no salta a les proves perquè l'únic test del mòdul simula un codi que mapa a «en trànsit».

Quan compensa integrar i quan no

No és qüestió de mida d'empresa, sinó d'on és la feina repetida. El criteri que fem servir:

• Encara no compensa per sota d'una desena d'enviaments al dia amb un sol servei, un bulto i sense reembossament: el manteniment es menjaria l'estalvi.
• Comença a compensar tan bon punt algú retranscriu adreces al portal: cada retranscripció és un lliurament fallit en potència, i un lliurament fallit es paga dues vegades en ports.
• Compensa clarament amb més d'un servei SEUR que cal encertar, multibulto habitual, suport responent «on és?» fora d'Odoo, o port facturat que vols a la comanda i no en un full de càlcul.

I el que cal pressupostar encara que el mòdul sigui lliure: apedaçar el mapeig d'estats, afegir el reembossament, enviar mesures reals de paquet si algun dia vols tarifes i baixar el cron. És un punt de partida honest, no un producte acabat.

Si has arribat volent decidir entre SEUR i un altre transportista, aquesta comparació no toca aquí: es decideix per operativa i contracte, no per API. Està separada a logística a Odoo i a mòdul natiu enfront d'OCA.

Preguntes freqüents

Enllaços útils

El que fem sobre això