Integrar l'API d'un transportista en una web pròpia: les quatre crides que importen i els errors que es repeteixen

Hem publicat connectors de MRW, SEUR, Correos Express, DHL, GLS, UPS i CTT per a Odoo, i hem integrat transportistes en webs que no porten Odoo al darrere, com eclipseando.com. Les API canvien de nom i de format, però la feina és sempre la mateixa: quatre crides, tres o quatre errors que es repeteixen i una decisió d'arquitectura que convé prendre abans d'escriure la primera línia. Aquest article és la versió per a una web pròpia; si la teva botiga porta Odoo, la major part ja està resolta als connectors de transportista.

Abans de programar: l'alta i l'entorn de proves

Cap transportista et dona accés a la seva API per omplir un formulari al web. Cal un contracte de transport amb un comercial, i d'aquí surten les credencials: un codi de client o abonat, un usuari i una contrasenya o clau, i de vegades un codi de franquícia o d'agència. Demana-les des del primer dia i demana també l'entorn de proves, que no tots tenen i no tots es comporten com la producció. Algunes API continuen sent SOAP amb XML (és el cas històric de diversos transportistes espanyols); altres són REST amb JSON. No canvia el que cal fer, canvia el que costa llegir la documentació.

Les quatre crides

Crear l'enviament: la meitat de la feina és netejar l'adreça

La crida de creació és on es concentren els rebuigs. Cada transportista té la seva idea de què és una adreça vàlida: longitud màxima del carrer, codi postal de cinc dígits exactes, província com a codi i no com a text, telèfon obligatori i sense prefix, i en diversos, res fora d'ASCII al nom. El que funciona és normalitzar abans de cridar: separar carrer i número, retallar els camps al màxim que admet cada API, substituir els accents quan l'API no els accepta, i validar que el codi postal existeixi per a aquell país. I guardar sempre la petició i la resposta completes, en XML o JSON, al costat de la comanda. Quan un paquet es perd tres setmanes després, aquesta traça és l'única prova del que es va enviar.

Seguiment: sondeig amb seny, o webhook si n'hi ha

Pocs transportistes avisen per webhook; a la majoria cal preguntar-los. La manera correcta és una tasca programada que consulta només les expedicions obertes, amb un interval raonable (cada hora sol bastar, més sovint el dia del lliurament), que s'atura quan l'estat és final i que respecta els límits de l'API. Els codis d'esdeveniment es tradueixen a un conjunt petit d'estats propis: acceptat, en trànsit, en repartiment, lliurat, incidència, retornat. Cinc o sis, no quaranta. I cada canvi d'estat dispara l'avís al client, que és per al que es fa tot això.

Quan no tens l'API perquè qui envia és el teu proveïdor

És més freqüent del que sembla: vens tu, però el paquet el prepara i l'envia un proveïdor amb el seu propi contracte de transport. No tens credencials, no pots crear l'enviament ni consultar l'expedició. El que sí que tens, gairebé sempre, són els correus que el transportista envia a l'adreça de contacte per cada moviment. A eclipseando.com ho vam resoldre així amb GLS: una tasca llegeix la bústia cada deu minuts, reconeix els quatre tipus de correu (en camí, en repartiment, en punt de recollida amb data límit, destinatari absent), treu el número d'expedició i la comanda a la qual pertany, i converteix cadascun en un estat i un avís al comprador. Els dos últims són els urgents: un paquet en un punt de recollida torna al remitent si ningú va a buscar-lo, i un client que no sap que hi és no hi va.

Els errors que veiem en producció

• Provar només contra el sandbox. Diversos transportistes tenen un entorn de proves que accepta el que la producció rebutja. La prova que val és un enviament real a la teva pròpia oficina.
• Crear l'enviament en confirmar la comanda al web. Es crea en preparar el paquet. Si es crea abans, cada cancel·lació és una expedició fantasma que de vegades es factura.
• No guardar la petició i la resposta. Sense l'XML o el JSON complets al costat de la comanda, una reclamació és la teva paraula contra la del transportista.
• Un sol número de seguiment per comanda. Funciona fins a la primera comanda amb dos bultos o dos proveïdors. El seguiment es modela per enviament.
• Certificats i xifratge antics. Algunes API continuen en TLS amb xifratges que les llibreries modernes rebutgen per defecte. Es detecta el primer dia, no el de la posada en marxa.

Amb Odoo al darrere, gairebé res d'això es programa

Si la botiga porta Odoo, les quatre crides ja estan escrites als connectors que publiquem a l'App Store d'Odoo, provats a Odoo 19, 18 i 17 sobre Odoo.sh real: l'etiqueta surt en validar l'albarà, el seguiment es consulta per cron i s'escriu a l'albarà, el manifest es tanca des del propi Odoo i l'avís al client surt per correu o SMS amb la plantilla que vulguis. La web només ha de llegir l'estat de l'albarà. Per això, quan algú ens demana integrar un transportista en una web i ja té Odoo, la resposta sol ser connectar la web a l'ERP, no tornar a escriure la integració.

Preguntes freqüents

Enllaços útils dins de FlexigoTech

El que fem sobre això