Skip to main content
Qargo

INTEGRATIES - Qargo API - wat, waarom en hoe

Qargo koppelen aan externe systemen voor orders, trip-updates, master-gegevens en boekhouding, inclusief API-configuratie, inloggegevens, testen en probleemoplossing.

Inhoudsopgave
  1. Inleiding
  2. Vereisten
  3. Integratietypes
  4. Toepassingen
  5. Terminologie
  6. Een API-koppeling instellen
  7. De order-API testen
  8. Configuratie orderimport
  9. Controleren of een orderimport gelukt is
  10. Boekhoud-API en Facturerende Entiteiten
  11. Probleemoplossing
  12. Veelgestelde vragen
  13. Gerelateerde documentatie

Inleiding

Wat is de Qargo API?

  • Een set koppelingen waarmee andere systemen gegevens naar Qargo kunnen sturen en gegevens van Qargo kunnen ontvangen.
  • De API omvat orderinvoer en statussen, de uitvoering van trips met onderaannemers, synchronisatie van master-gegevens en boekhouding.

Waarom gebruiken?

  • Dubbele invoer verdwijnt tussen Qargo en de andere systemen waarmee een transportbedrijf werkt, zoals klantsystemen, systemen van onderaannemers, boekhoudpakketten en vloot- of HR-tools.
  • De gegevens blijven in beide systemen actueel, zonder handmatige imports.

Hoe werkt het?

  • Qargo kent een integrator-ID toe aan de partij die de koppeling bouwt.
  • Een super admin maakt een API-client aan voor de juiste rol en deelt de inloggegevens op een veilige manier.
  • Qargo voltooit de nodige configuratie op het account. Daarna wordt de integratie getest en live gezet.

Vereisten

  • Super admin-rechten in Qargo.
  • Een integrator-ID uitgegeven door Qargo (zie Stap 1 hieronder).
  • Voor de rol Klant: Toegang klantenportaal ingeschakeld voor de betreffende klant.
  • Voor boekhoudclients die facturen boeken: een boekhoud-API-integratie die is ingesteld en gekoppeld aan de juiste Facturerende Entiteit.

Integratietypes

Er zijn drie integratietypes. Het type bepaalt hoe de integratie wordt ingesteld.

  • Tenant: een directe koppeling tussen Qargo en een systeem van een derde partij dat het transportbedrijf gebruikt, bijvoorbeeld een boekhoudpakket.
  • Klant: een koppeling vanuit het eigen systeem van een klant naar Qargo, bijvoorbeeld om orders via het klantenportaal in te dienen.
  • Onderaannemer: een koppeling vanuit het eigen systeem van een onderaannemer naar Qargo, bijvoorbeeld om trip-updates vanuit de eigen TMS terug naar Qargo te sturen.

Toepassingen

  • Een klant wil orders rechtstreeks vanuit het eigen systeem naar Qargo sturen, in plaats van ze in het klantenportaal in te typen.
  • Een onderaannemer wil trip-toewijzingen ontvangen en stop-updates en POD’s vanuit de eigen TMS terugsturen.
  • Een nieuwe chauffeur of een nieuw voertuig dat in een extern vloot- of HR-systeem wordt toegevoegd, moet automatisch bij de resources in Qargo verschijnen.
  • De financiële afdeling wil dat facturen en creditnota’s naar het boekhoudpakket doorstromen en dat betaalstatussen naar Qargo worden teruggestuurd.
  • Een groep met meerdere juridische entiteiten wil dat het boekhoudsysteem van elke entiteit alleen de eigen facturen boekt.

Terminologie

Term Definitie
API Een manier waarop twee systemen automatisch gegevens uitwisselen.
Tenant Het Qargo-account zelf, dus het transportbedrijf dat Qargo gebruikt.
Integratietype Voor wie de koppeling wordt ingesteld: de tenant, een van de klanten of een van de onderaannemers.
API-client Een set inloggegevens (een client-ID en een secret) waarmee een extern systeem voor één rol verbinding kan maken met Qargo.
Rol Het type toegang van een API-client: Orderbeheer, Klant, Beheer master-gegevens of Boekhouding.
Integrator-ID Een uniek ID van Qargo dat aangeeft wie de integratie bouwt, zodat bij een probleem de juiste persoon kan worden gecontacteerd.
Secret De privésleutel die één keer wordt getoond wanneer een API-client wordt aangemaakt. Achteraf is die niet meer te bekijken.
Master-gegevens Kernrecords zoals klanten, onderaannemers, chauffeurs en voertuigen.
Facturerende Entiteit Het juridische of interne bedrijf in de groep dat een factuur uitreikt.
POD Leveringsbewijs (proof of delivery): het ondertekende document of de foto die een levering bevestigt.
Orderexport Een endpoint dat alle gegevens van een bestaande order teruggeeft, te gebruiken als sjabloon voor het opbouwen van nieuwe orderverzoeken.
Configuratie orderimport Instellingen op accountniveau, beheerd door Qargo, die bepalen hoe orders die via de API binnenkomen in Qargo terechtkomen.
API-controle De eerste stap van een orderimport. Qargo controleert of het bericht correct is opgebouwd (validatie van de payload).
Qargo-import De tweede stap van een orderimport. Qargo past de gegevens toe op het account (validatie in de tenant).

Een API-koppeling instellen

Stap 1: de integratie en een integrator-ID aanvragen

  1. E-mailen naar success@qargo.com om de integratieaanvraag te starten.

  2. De volgende gegevens opgeven:

    • Integratiepartner: bedrijfsgegevens, plus de naam en het e-mailadres van de hoofdcontactpersoon met wie Qargo zal samenwerken. Als een derde partij of externe integrator de koppeling bouwt, de gegevens van die partij opgeven in plaats van die van de houder van het Qargo-account.
    • Type en omvang: het benodigde integratietype (bijvoorbeeld orderinvoer) en de verwachte functionaliteit. Zie Gerelateerde documentatie aan het einde van dit artikel.
    • Specifieke vereisten: eventuele specifieke functionele vereisten.
  3. Wachten tot een Integrations Delivery Manager (IDM) contact opneemt. Qargo geeft daarna het integrator-ID uit.

Stap 2: een API-client toevoegen voor de vereiste rol

  1. Navigeren naar Configuratie > Instellingen organisatie > Gebruikers en naar onderaan de pagina scrollen.
  2. Op ‘API-client toevoegen’ klikken.

  1. De benodigde rol selecteren:

Stap 3: de clientgegevens invullen

  • Integrator-ID: altijd verplicht. Het ID invullen dat van Qargo werd ontvangen.

  • Bedrijf: alleen verplicht voor de rol Klant.

‼️ Stap 4: de secret kopiëren vóór het opslaan‼️

Stap 5: de inloggegevens veilig delen

De client-ID en de secret op een veilige manier delen met de partij die de integratie bouwt.

Stap 6: Qargo op de hoogte brengen

Qargo op de hoogte brengen zodra de clients zijn ingesteld. Soms is extra configuratie op accountniveau nodig voordat het testen start, bijvoorbeeld de mapping van de orderimport voor de order-API, of de configuratie van de boekhoud-API.


De order-API testen

De eenvoudigste manier om te starten is enkele typische testorders handmatig in Qargo aan te maken en die daarna als sjabloon te gebruiken voor het opbouwen van API-verzoeken.

Een sjabloon ophalen met Orderexport

  1. Een testorder in Qargo openen en de order_id uit de URL kopiëren (het deel na orders/).

  2. Het endpoint Orderexport aanroepen:
    GET<https://api.qargo.com/v1/orders/order/{order_id}/export>

  3. De teruggestuurde gegevens bekijken. Door een echte Qargo-order te vergelijken met de gegevensstructuur ervan, is te zien hoe elk veld moet worden ingevuld.

Een nieuwe order aanmaken

  1. Automatisch gegenereerde velden zoals barcodes verwijderen.
  2. De code van de importconfiguratie toevoegen (standaard is dit API).
  3. Unieke identificatoren wijzigen, zoals het klantreferentienummer en order_identifier.
  4. De order uploaden: POST <https://api.qargo.com/v1/orders/order/upload>

De order verschijnt daarna op het tabblad Orders of op het tabblad Orderimports, afhankelijk van de configuratie van de orderimport.


Configuratie orderimport

De configuratie van de orderimport wordt op accountniveau ingesteld en kan alleen door Qargo worden gewijzigd. Deze instellingen bepalen hoe orders die via de API binnenkomen zich gedragen.

Instelling Wat het doet
Orders automatisch aanmaken Stuurt geïmporteerde orders rechtstreeks naar het tabblad Orders, of naar het tabblad Orderimports, waar ze eerst moeten worden bevestigd.
Updates inschakelen Bepaalt of updates via de API worden aanvaard.
Detectie van duplicaten inschakelen Markeert dubbele imports automatisch, zodat ze niet twee keer worden geïmporteerd.
Wijzigingen automatisch toepassen Past wijzigingen toe zonder handmatige controle. Kan worden beperkt tot een gekozen orderstatus; daarna moeten updates opnieuw handmatig worden goedgekeurd.
Annuleringen automatisch toepassen Werkt op dezelfde manier als Wijzigingen automatisch toepassen, maar voor annuleringen.

Controleren of een orderimport gelukt is

Qargo controleert een order die via de API wordt verstuurd in twee stappen. Een geslaagde stap 1 betekent niet dat de order in Qargo bestaat.

Stap Wat er gebeurt Waar het resultaat verschijnt
1. API-controle Qargo controleert of het bericht correct is opgebouwd. In het validatieantwoord dat naar het externe systeem wordt teruggestuurd.
2. Qargo-import Qargo past de gegevens toe op het account. De order wordt aangemaakt of bijgewerkt. Dit gebeurt na stap 1, op de achtergrond. In de importstatus en op de order in Qargo.

Wat de API-controle bevestigt

  • Het bericht volgt de verwachte structuur (JSON of XML).
  • Verplichte velden zijn aanwezig, met de juiste gegevenstypes en formaten.
  • Waarden zoals eenheden en ordertypes zijn toegestaan.

Wat de API-controle niet bevestigt

  • Dat de klanten, locaties, producten en resources in de order bestaan in het Qargo-account.
  • Dat de bedrijfsregels en de accountconfiguratie toestaan dat de order wordt aangemaakt of gewijzigd.
  • Dat de orderreferentie correct overeenkomt, zodat Qargo een nieuwe order aanmaakt of de juiste bestaande order bijwerkt.
  • Dat een bestaande order nog in een status staat die wijzigingen toelaat.

Een Qargo-import kan mislukken of worden afgewezen, ook als de API-controle geslaagd is.

Bevestigen dat een import geslaagd is

  1. Een positieve API-controle niet beschouwen als bevestiging dat de order bestaat.
  2. De importstatus van de order controleren. De status error betekent dat de Qargo-import mislukt is. Een handmatige correctie in Qargo is nodig.
  3. Het tabblad Orderimports of de order in Qargo openen om het resultaat te bekijken.
  4. De orderreferentie, het tijdstip en de foutmelding naar Qargo-support sturen als de import nog steeds mislukt.

Voorbeelden: resultaten van API-controle en Qargo-import

API mislukt (= API-validatie mislukt)

API geslaagd

API-status upsert-fout (= import in UI mislukt)

Foutscherm orderimport (= import in UI mislukt)

Orderimport corrigeren (UI)

Orderimport corrigeren (API)


Boekhoud-API en Facturerende Entiteiten

De boekhoud-API ondersteunt meerdere Facturerende Entiteiten. Dit zorgt voor strengere beveiliging en toegangscontrole voor groepen die vanuit meer dan één bedrijf factureren.

Wat is inbegrepen

  • Facturerende Entiteit op facturen: de factuur-endpoints bevatten een sectie billing_entity die aangeeft tot welke entiteit een factuur behoort.
  • Meerdere integraties: er kunnen meerdere boekhoud-API-integraties worden aangemaakt, elk gekoppeld aan één Facturerende Entiteit.
  • Filteren: facturen en taken kunnen op hun Facturerende Entiteit worden gefilterd.
  • Specifieke API-clients: boekhoud-API-clients worden aangemaakt op de instellingenpagina Integratie boekhoud-API. Deze clients zijn nodig voor de volledige functionaliteit.

Gevolgen voor externe integraties

  • Beperkt boeken: een integrator kan alleen facturen voltooien (boeken) voor de Facturerende Entiteit die aan de gebruikte inloggegevens is gekoppeld.

  • Bekijken: facturen van andere Facturerende Entiteiten blijven zichtbaar, volgens de gewone weergaverechten, maar kunnen niet worden geboekt.

  • De plaats waar inloggegevens worden aangemaakt, is belangrijk:

    • Om facturen te boeken (de status op voltooid zetten) moeten de inloggegevens worden aangemaakt op de instellingenpagina Integratie boekhoud-API en gekoppeld zijn aan de juiste Facturerende Entiteit.
    • Inloggegevens die in Instellingen organisatie zijn aangemaakt, kunnen een factuur niet op voltooid zetten en kunnen geen facturen oplijsten die nog op synchronisatie wachten.

Probleemoplossing

Probleem Oplossing
Testorders verschijnen niet op het tabblad Orders Als Orders automatisch aanmaken is uitgeschakeld, gaan imports naar het tabblad Orderimports en moeten ze daar worden bevestigd.
De API-controle is geslaagd, maar de order staat niet in Qargo De Qargo-import is mogelijk mislukt. De importstatus en het tabblad Orderimports controleren. Zie Controleren of een orderimport gelukt is.
De API-controle is geslaagd, maar de order staat niet in Qargo De Qargo-import is mogelijk mislukt. De importstatus en het tabblad Orderimports controleren. Zie Controleren of een orderimport gelukt is.
Een order die via de API is geïmporteerd, toont een fout in Qargo Fouten die de API niet blokkeren, komen op het tabblad Orderimports terecht. Een key user of admin kan ze daar bekijken en oplossen. De importstatus error betekent dat de Qargo-import mislukt is en dat een handmatige correctie nodig is.
De secret is verloren na het sluiten van het scherm De secret kan niet worden hersteld. Een nieuwe API-client aanmaken en de secret kopiëren vóór het opslaan.
Er kan geen API-client worden aangemaakt voor de rol Klant Eerst Toegang klantenportaal inschakelen voor die klant.
Een boekhoudclient kan geen facturen boeken De client aanmaken in Accounting API Integration settings en koppelen aan de juiste Facturerende Entiteit. Clients uit Organisation settings kunnen niet boeken.
Een integrator kan sommige facturen niet boeken Die facturen behoren tot een andere Facturerende Entiteit. Inloggegevens gebruiken die aan die Facturerende Entiteit zijn gekoppeld.
Dubbele orders worden steeds opnieuw geïmporteerd Qargo vragen om Detectie van duplicaten inschakelen in te schakelen.
Updates via de klant-API worden niet automatisch toegepast Dit is normaal. Updates van klanten volgen de regels van het klantenportaal en moeten worden goedgekeurd in het scherm voor orderimports.

Veelgestelde vragen

V. Biedt Qargo een API aan?
A. Ja! Qargo biedt API’s voor orderinvoer en statussen, de uitvoering van trips, synchronisatie van master-gegevens en boekhouding, voor de integratietypes Tenant, Klant en Onderaannemer.


V. Kan een API-koppeling zonder Qargo worden ingesteld?
A. Nee. Voor het instellen van een integratie zijn Super admin-rechten en ondersteuning van het Qargo-team nodig. Starten met een e-mail naar success@qargo.com.


V. Kan één boekhoudintegratie facturen boeken voor elke Facturerende Entiteit?
A. Nee. Elke boekhoud-API-client kan alleen facturen boeken voor de Facturerende Entiteit waaraan de client is gekoppeld. Facturen van andere entiteiten blijven zichtbaar, maar kunnen niet worden geboekt.


Gerelateerde documentatie

API-referentiedocumentatie (api.qargo.com)