Etiquetes i seguiment automàtics a Odoo: del picking validat al correu del client

En validar un albarà amb transportista, Odoo automatitza quatre coses: la crida a l'API, l'etiqueta PDF adjunta a l'albarà, el número de seguiment a carrier_tracking_ref i el correu o SMS al client amb aquest número. No automatitza la recollida física ni la veritat del pes i els bultos. Aquí va el flux amb el model d'Odoo de cada pas i el codi dels nostres connectors de Correos Express i MRW, que fem servir al nostre propi magatzem. Sense Odoo al darrere, el mateix és a integrar l'API d'un transportista en una web pròpia.

Què cal abans

• Contracte i credencials de l'entorn correcte. Correos Express separa test (www.test.cexpr.es) i producció (www.cexpr.es); MRW usa el servei web Sagec amb franquícia, abonat, departament, usuari i contrasenya. Tots dos porten un botó de prova de connexió (action_cex_test_connection i action_mrw_test_connection) per verificar-ho abans del primer enviament real.
• Adreça normalitzada. Nom, carrer, població, CP de cinc dígits a Espanya i telèfon d'almenys nou dígits, en remitent i destinatari: la llista literal de _cex_validate_shipment_inputs.
• Pes i bultos a l'albarà. Els mòduls llegeixen els paquets (package_level_ids / package_ids) o, si no n'hi ha, un bulto amb shipping_weight o weight. Pes zero no surt.
• Tipus d'operació amb «Imprimir etiqueta». A Odoo 19 la crida automàtica en validar només passa amb print_label activat. És la causa més comuna de «he validat i no ha passat res».

El flux pas a pas, amb el model d'Odoo a cada pas

1. Validar (stock.picking._action_done). Odoo 19 crida _send_confirmation_email, que stock_delivery sobreescriu: amb transportista rate_and_ship, sense tracking encara i tipus d'operació que imprimeix etiqueta, executa send_to_shipper() abans de compondre el correu.
2. Cridar l'API (delivery.carrier.send_shipping). Odoo despatxa a cex_send_shipping o mrw_send_shipping: JSON contra apiRestGrabacionEnviok8s/json a Correos Express, SOAP TransmEnvio contra sagec.mrw.es a MRW. Si ja hi havia número d'enviament, es retorna l'existent.
3. Desar l'etiqueta (ir.attachment). El PDF s'adjunta a l'albarà com a Etiqueta_CEX_<número>.pdf o Etiqueta_MRW_<número>.pdf i es publica al chatter. Amb diversos bultos, Correos Express en retorna diverses amb sufix _01, _02…
4. Escriure el tracking (carrier_tracking_ref). send_to_shipper pren tracking_number de la resposta, l'escriu al camp estàndard i publica «Paquete enviado al transportista … con número de rastreo …». Els mòduls desen a més el seu número propi.
5. Avisar el client (mail.template / sms.template). stock envia «Shipping: Send by Email» si la companyia té activada la confirmació per correu, i stock_sms l'SMS. Totes dues inclouen el tracking només si carrier_tracking_ref ja està emplenat.

Validar abans de cridar: què es comprova i què retorna el transportista si no

El transportista valida, però tard i amb missatges per al seu equip. Els mòduls comproven primer a Odoo i només criden si no hi ha errors; si n'hi ha, un únic UserError amb tots. Si tot i així rebutja, la resposta es classifica per paraules clau i es tradueix a una frase per a l'operari; l'administrador veu el detall tècnic.

Reintents: una fallada silenciosa és pitjor que una de visible

Un 503 en plena preparació de comandes no és estrany. Deixar l'albarà a mitges és la pitjor resposta; empassar-se l'error, la segona. Els mòduls en fan una tercera: decidir si la fallada és transitòria i reintentar amb espera creixent.

• Transitori a Correos Express és HTTP 408, 409, 423, 425, 429, 500, 502, 503 o 504, o un missatge amb «timeout», «vuelva a intentarlo», «service unavailable» o «error interno»; MRW usa una llista més curta: 408, 429, 500, 502, 503 i 504. La resta és error de dades: es marca i es mostra.
• A l'albarà queden cex_retry_pending, cex_retry_count, cex_retry_next_attempt, cex_last_error_message i cex_last_attempt_at (a MRW, prefix mrw_), i al chatter «CEX temporalmente no disponible. Reintento automático #1 programado para …».
• Un cron cada 5 minuts recull els pendents sense número d'enviament amb l'hora acomplerta, de 50 en 50, i els passa pel mateix codi del primer intent.
• Espera: 5, 15, 30, 60, 120 i 240 minuts a Correos Express; 5, 15, 30, 60, 180 i 360 a MRW. Sis intents per defecte, configurable. En esgotar-los, «Se alcanzó el máximo de reintentos automáticos»: aquí cal una persona.
• Qui se n'assabenta: l'operari, a l'error i al chatter. Odoo 19 afegeix la seva xarxa: si en un lot ja es va processar un albarà al transportista, el següent error no reverteix el lot; es converteix en una activitat d'avís.

El fragment que fixa l'espera, al mòdul de Correos Express:

# flexigobe_correos_express/models/delivery_carrier.py (v19.0.3.0.19)
CEX_RETRY_BACKOFF_MINUTES = [5, 15, 30, 60, 120, 240]

def _cex_retry_delay_minutes(self, attempt_no):
    self.ensure_one()
    idx = max(int(attempt_no or 1) - 1, 0)
    if idx >= len(CEX_RETRY_BACKOFF_MINUTES):
        idx = len(CEX_RETRY_BACKOFF_MINUTES) - 1
    return CEX_RETRY_BACKOFF_MINUTES[idx]

El correu al client: quan es dispara i què porta

Es dispara en validar, no en crear l'albarà. La plantilla estàndard («Shipping: Send by Email», a Inventari → Configuració → Confirmació de correu electrònic) diu «Nos alegra informarle de que su pedido ha sido enviado» i, si hi ha carrier_tracking_ref, afegeix la referència amb enllaç a carrier_tracking_url; l'SMS de stock_sms afegeix el número de comanda (object.origin) i la referència en text pla, sense enllaç. Com que stock_delivery crida send_to_shipper abans de super()._send_confirmation_email(), el tracking ja existeix en compondre el correu. Si l'enviament ha quedat en cua de reintent, el correu surt sense tracking.

L'enllaç el construeix cada mòdul: https://s.correosexpress.com/SeguimientoSinCP/search?n=<tracking> a Correos Express i https://www.mrw.es/seguimiento_envios/MRW_historico_nacional.asp?enviament=<número> a MRW. Tracking sense enllaç vol dir que encara no hi ha referència.

Cas: els dos mòduls propis i en què es diferencien

Comparteixen arquitectura i es mantenen per a Odoo 19, 18 i 17. Les API difereixen, i es nota en l'etiqueta, l'anul·lació i el que no fan.

Cap dels dos gestiona avui el contra reemborsament, i ens ho pregunten molt. Més a Correos Express a Odoo i MRW a Odoo; si encara estàs triant, quin transportista encaixa amb un ecommerce a Odoo.

Com comprovar que funciona

No amb el sandbox: amb un albarà real validat i aquestes quatre evidències, les de les captures.

1. Un adjunt Etiqueta_CEX_…pdf o Etiqueta_MRW_…pdf amb codi de barres llegible. El de MRW mira la capçalera del binari (%PDF-, ^XA, <?xml, <html) i, si no és una etiqueta imprimible, no la desa: ho diu al chatter.
2. carrier_tracking_ref emplenat i «Etiqueta OK» amb el número d'enviament.
3. Al chatter: «Paquete enviado al transportista…», «Etiqueta … generada correctamente» amb el PDF, i l'SMS o correu al client si estan activats.
4. Camps de reintent a zero. Si no, l'enviament no ha arribat al transportista tot i que l'albarà estigui validat.

Amb un transportista sense mòdul publicat, mateix flux i un altre adaptador: dins del servei de logística a Odoo i, per a consultores, com a enginyeria per a consultories. La regla dels nostres serveis és la mateixa: l'etiqueta surt de l'albarà, el tracking torna a l'albarà i ningú copia res.

Preguntes freqüents

Enllaços útils dins de FlexigoTech

El que fem sobre això