Skip to main content
Qargo

Integraties: orders importeren in Qargo

Orders importeren in Qargo via de API of partnerintegraties, met uitleg over mapping, validatie en probleemoplossing.

Inhoudsopgave
  1. Inleiding
  2. Terminologie
  3. Probleemoplossing

Inleiding

Qargo ondersteunt meerdere manieren om orders op grote schaal in het platform te brengen. Dit artikel legt de belangrijkste begrippen en de voornaamste importroutes van de meeste klanten uit: integratiepartners en de publieke API van Qargo. Daarnaast staan er links naar artikelen over manuele imports en workflows voor palletnetwerken. Tot slot volgt een gids voor probleemoplossing met veelvoorkomende fouten en hoe die op te lossen.

Terminologie

Begrip Beschrijving
Order Een record van een trip of zending in Qargo. Orders kunnen een of meer stops en bijbehorende documenten bevatten.
Import Het proces waarbij orders in Qargo worden aangemaakt of bijgewerkt door gestructureerde gegevens vanuit een extern systeem te versturen.
Bronsysteem Het systeem waarvan de gegevens afkomstig zijn, bijvoorbeeld een TMS, ERP, WMS of marktplaats.
Mapping De omzetting van velden uit het bronsysteem naar het orderschema van Qargo.
DTO (Data Transfer Object) De gestructureerde payload waarmee ordergegevens via integraties, EDI of API naar Qargo worden overgebracht.
Validatie De controles van Qargo die nagaan of binnenkomende gegevens volledig, correct opgemaakt en in overeenstemming met de bedrijfsregels zijn.
Bevestiging Het antwoord dat naar de afzender wordt teruggestuurd en aangeeft of het verzoek gelukt is, gedeeltelijk gelukt is met waarschuwingen, of mislukt is met fouten.
Idempotentiesleutel Een unieke identificatie die de client genereert en met een verzoek meestuurt, meestal in de HTTP-header. Daarmee kan een verzoek veilig opnieuw worden verstuurd zonder onbedoelde neveneffecten, zoals duplicaten.

Overzicht van de importroutes

Qargo ondersteunt verschillende importmethoden. Dit artikel richt zich op de drie meest gebruikte geautomatiseerde routes.

  • Integratiepartners (kant-en-klare connectoren)
  • EDI-partners (documentstromen volgens de industriestandaard)
  • Qargo API (rechtstreekse programmatische integratie)

Meer over manuele bestandsuploads en specifieke stromen voor palletnetwerken:

Importeren via integratiepartners

Ideaal voor organisaties die populaire ERP’s, WMS’en of logistieke platformen gebruiken die al een door Qargo gecertificeerde connector hebben.

  • Werking

    • De partnerconnector exporteert ordergegevens volgens een schema of bij een evenement.
    • De connector mapt het schema van de partner naar de order-DTO van Qargo.
    • De gegevens worden naar Qargo verstuurd via een beveiligd kanaal dat de connector bepaalt.
    • Qargo valideert en verwerkt de gegevens, en stuurt bevestigingen en foutdetails terug.
  • Typische mogelijkheden

    • Voorinstellingen voor veldmapping, beheerd door de partner
    • Incrementele updates bij orderwijzigingen
    • Ondersteuning voor bijlagen wanneer de partner documenten deelt
    • Automatische nieuwe pogingen en afhandeling van dead letters
  • Wat geconfigureerd moet worden

    • Inloggegevens of API-sleutels van Qargo of de partner
    • Optioneel: overschrijvingen van velden en regels voor de normalisatie van waarden
    • Standaardgedrag bij ontbrekende optionele velden
    • Meldingsvoorkeuren voor mislukte imports
  • Wanneer kiezen

    • Voor de snelste weg naar go-live met zo weinig mogelijk maatwerkcode
    • Als de partner Qargo of een sterk vergelijkbaar schema al ondersteunt

Importeren via de Qargo API

Ideaal voor teams die volledige controle en onmiddellijke feedback willen, of wanneer er geen partnerconnector beschikbaar is.

  • Endpointmodel

    • Order aanmaken
    • Order bijwerken
    • Documenten en referenties toevoegen
    • Orders opvragen en zoeken ter bevestiging
  • Richtlijnen voor de payload

    • ISO 8601 gebruiken voor datum-tijdwaarden met tijdzoneverschuiving
    • Consistente eenheden gebruiken voor gewichten, volumes en aantallen
    • Stabiele externe ID’s meesturen voor idempotentie en ontdubbeling
    • Waar mogelijk volledige adresblokken versturen, inclusief landcodes
  • Patronen voor betrouwbaarheid

    • Idempotentiesleutels gebruiken om bij netwerkfouten veilig opnieuw te proberen
    • Exponentiële backoff toepassen voor 429- en tijdelijke 5xx-antwoorden
    • Validatiefouten loggen en zichtbaar maken voor de operations-teams
  • Beveiliging

    • API-sleutels met beperkte scope of OAuth gebruiken, zoals voorzien
    • Inloggegevens regelmatig vernieuwen en geen geheimen hardcoderen
  • Wanneer kiezen

    • Als het bronsysteem in eigen beheer is en snel kan worden uitgebouwd
    • Als fijnmazige controle nodig is over de vorm van de payload, het tijdstip van verzending en nieuwe pogingen

Checklist voor gegevensmapping

Vóór de go-live controleren of de volgende punten tussen het bronsysteem en Qargo op elkaar zijn afgestemd:

Partijen Rollen voor klant, verzender, ontvanger, betaler en contactpersoon consistent gemapt.
Locaties Namen, adressen, landcodes en optioneel geolocatie; dubbelzinnige vrije tekst vermijden.
Datums en tijden Tijdvensters voor ophaling, levering en klaarstaan in ISO 8601 met expliciete tijdzones.
Details van de goederen Itemregels, colli, pallets, afmetingen, markeringen voor gevaarlijke goederen.
Bijkomende diensten en add-ons Toeslagen en opties voor serviceniveaus gemapt naar het add-onmodel van Qargo.
Referenties Ordernummers van de klant, inkooporders en referenties van handelspartners.
Documenten Bijlagen voor CMR, POD, labels en douanedocumenten, indien beschikbaar.

Operationele controles

Ontdubbeling Een stabiele externe ID meesturen. Qargo kan duplicaten afwijzen of een upsert uitvoeren, afhankelijk van de configuratie.
Gedeeltelijke updates Bepalen of updates volledige objecten vervangen of alleen specifieke velden aanpassen.
Statusafhandeling Afspreken welke evenementen via de import kunnen worden ingesteld en welke door operations worden aangestuurd.
Overgangsstrategie Een periode bepalen waarin het oude en het nieuwe systeem tegelijk kunnen draaien, en vastleggen hoe dubbele boekingen worden vermeden.

Aanbevolen werkwijzen om problemen te voorkomen

  • Valideren vóór verzending
    In het bronsysteem een voorafgaande controle uitvoeren op verplichte velden, datum-tijdformaten en eenheden.

  • Codes standaardiseren
    Een opzoektabel bijhouden voor services, uitrustingstypes en bijkomende diensten die naar Qargo-codes verwijst.

  • Idempotentie gebruiken
    Bij het aanmaken altijd idempotentiesleutels meesturen. De mapping van sleutel naar order-ID loggen.

  • Monitoren en waarschuwen
    Meldingen instellen voor mislukte imports en foutlogs integreren in de monitoringtools.

  • De mapping documenteren
    Een actueel mappingdocument bijhouden, zodat toekomstige wijzigingen de imports niet verstoren.

  • Ervoor zorgen dat alle gegevens, vooral datums, een geldig formaat hebben.

  • Unieke identificaties gebruiken voor nieuwe orders om een verkeerde classificatie te voorkomen.

  • Importbestanden regelmatig valideren op typfouten of inconsistenties in de gegevens.

Probleemoplossing

Hieronder staan veelvoorkomende fouten bij orderimports, hun waarschijnlijke oorzaken en de oplossing. De fouttekst kan licht verschillen, afhankelijk van de importroute.

Voorinvullingen voor orders (geconfigureerd door de Qargo admin)

Als vooraf ingevulde ordergegevens onjuist lijken of niet zijn zoals verwacht, kan dat te maken hebben met de mapping van de orderimport.

  • Velden die in de mapping van de orderimport zijn opgenomen, hebben voorrang op alle andere standaardwaarden elders in het platform, bijvoorbeeld voorinvullingen vanuit het klantprofiel.
  • Waar andere opties zijn gedefinieerd met meerdere selecteerbare opties (bv. extra’s), worden de waarden uit de orderimport toegevoegd, samen met de opties die al geselecteerd zijn.

Veelgestelde vragen: voorinvullingen

V. Hoe krijgen bepaalde voorinvullingen voorrang als ze uit verschillende bronnen voor hetzelfde doelveld kunnen komen?
Voorbeeld: tijdvensters voor start en einde. Voorinvullingen kunnen worden gedefinieerd op:

  • Transportdienst
  • Klant
  • Locatie
  • Tijdvenster

A. De meest specifieke voorinvulling wordt toegepast. In het voorbeeld hierboven volgt de logica hoe gedetailleerd de selecties zijn: eerst wordt de transportdienst geselecteerd, daarna de klant en de locaties, gevolgd door het tijdvenster voor de stop. In dit geval wordt de voorinvulling dus genomen van de laatste selectie (tijdvenster), omdat die als de meest specifieke optie geldt

V. Kunnen de openingsuren van de locatie vooraf worden ingevuld, of moeten die voor elke geïmporteerde order manueel worden ingevoerd? Is er een snelle manier om de tijden over te nemen waarop de locaties beschikbaar zijn voor ophaling of levering?

A. Ja, de openingsuren van locaties kunnen bij het importeren van orders vooraf worden ingevuld en in de instellingen voor het tijdvenster van de stop worden opgenomen. Zo is duidelijk zichtbaar wanneer de stopactie kan worden voltooid, als er geen specifieke afspraak of specifiek tijdvenster vereist is. Er is een functie-instelling die kan worden ingeschakeld en die bij orderimports automatisch de openingsuren gebruikt die op de locatie zijn gedefinieerd.


Aanbevolen werkwijzen om problemen te voorkomen

  • Valideren vóór verzending
    In het bronsysteem een voorafgaande controle uitvoeren op verplichte velden, datum-tijdformaten en eenheden.

  • Codes standaardiseren
    Een opzoektabel bijhouden voor services, uitrustingstypes en bijkomende diensten die naar Qargo-codes verwijst.

  • Idempotentie gebruiken
    Bij het aanmaken altijd idempotentiesleutels meesturen. De mapping van sleutel naar order-ID loggen.

  • Monitoren en waarschuwen
    Meldingen instellen voor mislukte imports en foutlogs integreren in de monitoringtools.

  • De mapping documenteren
    Een actueel mappingdocument bijhouden, zodat toekomstige wijzigingen de imports niet verstoren.