De API van een vervoerder koppelen aan je eigen website: de vier aanroepen die tellen en de fouten die zich herhalen

We hebben connectoren gepubliceerd voor MRW, SEUR, Correos Express, DHL, GLS, UPS en CTT voor Odoo, en we hebben vervoerders gekoppeld aan websites zonder Odoo erachter, zoals eclipseando.com. De API's verschillen in naam en formaat, maar het werk is altijd hetzelfde: vier aanroepen, drie of vier fouten die zich herhalen en één architectuurbeslissing die je het best neemt voordat je de eerste regel schrijft. Dit artikel is de versie voor een eigen website; draait je webshop op Odoo, dan is het grootste deel al opgelost in de vervoerderconnectoren.

Voordat je gaat programmeren: aanmelding en testomgeving

Geen enkele vervoerder geeft je toegang tot zijn API door een formulier op de website in te vullen. Je hebt een transportcontract nodig via een accountmanager, en daaruit komen de inloggegevens: een klant- of abonneenummer, een gebruiker en een wachtwoord of sleutel, en soms een franchise- of agentuurcode. Vraag ze vanaf dag één, en vraag ook om de testomgeving, die niet iedereen heeft en die zich niet bij iedereen als productie gedraagt. Sommige API's zijn nog SOAP met XML (historisch het geval bij meerdere Spaanse vervoerders); andere zijn REST met JSON. Wat er moet gebeuren verandert niet, alleen hoeveel moeite het kost om de documentatie te lezen.

De vier aanroepen

De zending aanmaken: het halve werk is het adres opschonen

Bij de aanmaakaanroep stapelen de afwijzingen zich op. Elke vervoerder heeft zijn eigen idee van een geldig adres: maximale lengte van de straat, postcode van precies vijf cijfers, provincie als code en niet als tekst, telefoonnummer verplicht en zonder landnummer, en bij meerdere niets buiten ASCII in de naam. Wat werkt is normaliseren vóór de aanroep: straat en nummer scheiden, velden inkorten tot het maximum van elke API, accenten vervangen waar de API ze niet accepteert, en controleren of de postcode bestaat voor dat land. En altijd het volledige verzoek en antwoord bewaren, in XML of JSON, bij de bestelling. Als een pakket drie weken later zoekraakt, is dat spoor het enige bewijs van wat er is verstuurd.

Tracking: slim pollen, of een webhook als die er is

Weinig vervoerders melden via webhook; de meeste moet je bevragen. De juiste aanpak is een geplande taak die alleen open zendingen opvraagt, met een redelijk interval (elk uur is meestal genoeg, vaker op de dag van levering), die stopt zodra de status definitief is en die de limieten van de API respecteert. De gebeurteniscodes vertaal je naar een kleine set eigen statussen: geaccepteerd, onderweg, in bezorging, afgeleverd, incident, geretourneerd. Vijf of zes, geen veertig. En elke statuswijziging activeert de melding aan de klant, waar dit alles voor dient.

Als je geen API hebt omdat je leverancier de verzender is

Het komt vaker voor dan je denkt: jij verkoopt, maar een leverancier met een eigen transportcontract maakt het pakket klaar en verstuurt het. Je hebt geen inloggegevens, je kunt de zending niet aanmaken en niet opvragen. Wat je bijna altijd wel hebt, zijn de e-mails die de vervoerder bij elke beweging naar het contactadres stuurt. Bij eclipseando.com losten we het zo op met GLS: een taak leest elke tien minuten de mailbox, herkent de vier soorten e-mail (onderweg, in bezorging, in een afhaalpunt met uiterste datum, ontvanger afwezig), haalt het zendingnummer en de bijbehorende bestelling eruit en maakt van elk een status en een melding aan de koper. De laatste twee zijn de dringende: een pakket in een afhaalpunt gaat terug naar de afzender als niemand het ophaalt, en een klant die niet weet dat het daar ligt, gaat er niet heen.

De fouten die we in productie zien

• Alleen tegen de sandbox testen. Meerdere vervoerders hebben een testomgeving die accepteert wat productie afwijst. De test die telt is een echte zending naar je eigen kantoor.
• De zending aanmaken bij het bevestigen van de bestelling op de website. Je maakt hem aan wanneer het pakket wordt klaargemaakt. Doe je het eerder, dan is elke annulering een spookzending die soms toch wordt gefactureerd.
• Het verzoek en het antwoord niet bewaren. Zonder de volledige XML of JSON bij de bestelling staat bij een claim jouw woord tegenover dat van de vervoerder.
• Eén trackingnummer per bestelling. Werkt tot de eerste bestelling met twee colli of twee leveranciers. Tracking modelleer je per zending.
• Oude certificaten en versleuteling. Sommige API's draaien nog op TLS met versleuteling die moderne bibliotheken standaard afwijzen. Dat ontdek je op dag één, niet op de dag van livegang.

Met Odoo erachter hoef je bijna niets hiervan te programmeren

Draait de webshop op Odoo, dan zijn de vier aanroepen al geschreven in de connectoren die we in de App Store van Odoo publiceren, getest op Odoo 19, 18 en 17 op echte Odoo.sh: het label komt eruit bij het valideren van de levering, de tracking wordt via een geplande actie opgevraagd en op de levering geschreven, het manifest sluit je vanuit Odoo zelf af en de melding aan de klant gaat per e-mail of sms met de sjabloon die je wilt. De website hoeft alleen de status van de levering te lezen. Daarom is het antwoord meestal om de website aan de ERP te koppelen, en de integratie niet opnieuw te schrijven, wanneer iemand ons vraagt een vervoerder in een website te integreren en al Odoo heeft.

Veelgestelde vragen

Nuttige links binnen FlexigoTech

Wat wij hierover doen