---
title: "INTEGRATIES - Qargo API - wat, waarom en hoe"
description: "Qargo koppelen aan externe systemen voor orders, trip-updates, master-gegevens en boekhouding, inclusief API-configuratie, inloggegevens, testen en probleemoplossing."
url: https://help.qargo.com/nl/articles/865547-integraties-qargo-api-wat-waarom-en-hoe
locale: nl
updated: 2026-11-03
---

# INTEGRATIES - Qargo API - wat, waarom en hoe

:::callout{tone="info"}
💬 Een e-mail sturen naar [success@qargo.com](mailto:success@qargo.com) om een integratieaanvraag te starten of om vereiste configuratie te laten inschakelen.
:::

## Inleiding {#h_ac41125bec}

**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 {#h_dbbc5364d0}

-   **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 {#h_5966c3f172}

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 {#h_664a4407e6}

-   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 {#h_ef2b99bccb}

| **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 {#h_dacd260685}

### Stap 1: de integratie en een integrator-ID aanvragen {#h_7a4480cad0}

1.  **E-mailen** naar [success@qargo.com](mailto: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 {#h_e9b1ab14b3}

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

![](https://help.qargo.com/media/de2dd24867ac-image.png)

1.  De benodigde rol **selecteren**:

    -   [Boekhouding](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting): voor het boeken van facturen, zie _[Boekhoud-API en Facturerende Entiteiten](#h_8268f9d1d9)_ hieronder
    -   [Klant](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs): gebruikt wanneer een klant van het account via de API wil koppelen
    -   [Beheer master-gegevens](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
    -   [Orderbeheer](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)

### Stap 3: de clientgegevens invullen {#h_0d48e98b07}

![](https://help.qargo.com/media/a4e7de110537-image.png)

-   **Integrator-ID**: altijd verplicht. Het ID invullen dat van Qargo werd ontvangen.
-   **Bedrijf**: alleen verplicht voor de rol _Klant_.

    ![](https://help.qargo.com/media/7d9d7e88bb30-image.png)


:::callout{tone="info"}
🧰 Voor de rol _Klant_ moet **Toegang klantenportaal** voor de betreffende klant ingeschakeld zijn voordat een API-client kan worden aangemaakt.
:::

### ‼️ Stap 4: de secret kopiëren vóór het opslaan‼️ {#h_5d8948d080}

![](https://help.qargo.com/media/32a5e44416c6-image.png)

:::callout{tone="warning"}
‼️ **De _secret_ wordt maar één keer getoond.** De secret op een veilige plaats bewaren voordat op **Opslaan** wordt geklikt en het scherm **API-client toevoegen** wordt gesloten. Achteraf is de secret niet meer te bekijken en moet een nieuwe client worden aangemaakt.
:::

### Stap 5: de inloggegevens veilig delen {#h_f2132d724b}

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 {#h_293f38389d}

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 {#h_b17ab36a5e}

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 {#h_668cb7e95e}

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](https://api.qargo.com/v1/orders/order/%7Border_id%7D/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.

![](https://help.qargo.com/media/efbd7ced6dec-image.png)

### Een nieuwe order aanmaken {#h_50d96770f0}

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](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.

![](https://help.qargo.com/media/84ea7382b342-image.png)

* * *

## Configuratie orderimport {#h_8f2bedce55}

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.

:::callout{tone="info"}
📚 Meer details over mapping en fouten staan in [INTEGRATIES - Orders importeren in Qargo](https://help.qargo.com/nl/articles/450378-integrations-importing-orders-into-qargo).
:::

| **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. |

:::callout{tone="info"}
📚 Tijdens het testen is _Orders automatisch aanmaken_ vaak uitgeschakeld. Zo blijven API-testorders gescheiden van de orders die andere teams handmatig aanmaken.

📚 Orders die de API-controle doorstaan maar in Qargo mislukken, komen altijd op het tabblad **Orderimports** terecht. Daar kan een key user of admin de fout bekijken en oplossen.

📚 **Voorbeeld:** veel bedrijven aanvaarden updates automatisch tot een order is ingepland. Hiervoor _Wijzigingen automatisch toepassen_ inschakelen en vanaf de status _Ingepland_ uitschakelen.

![](https://help.qargo.com/media/937c3caabb24-image.png)
:::

:::callout{tone="note"}
‼️ **Uitzondering voor de klant-API.** Voor de rol _Klant_ volgen updates en annuleringen de regels van het klantenportaal, niet de configuratie van de orderimport. Als klanten orders niet kunnen bewerken in het klantenportaal, kunnen ze die ook niet automatisch via de API bewerken. Updates kunnen nog wel worden verstuurd, maar elke update moet worden goedgekeurd in het scherm voor orderimports.
:::

* * *

## Controleren of een orderimport gelukt is {#h_0cf7fd7820}

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 {#h_0fb2e846b9}

-   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 {#h_a8ead373e6}

-   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 {#h_754ec40674}

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.

:::callout{tone="note"}
📚 De _API-controle_ en de _Qargo-import_ zijn afzonderlijke stappen. Dezelfde order kan voor de eerste slagen en voor de tweede mislukken.
:::

#### Voorbeelden: resultaten van API-controle en Qargo-import {#h_c4e435ac7f}

##### API mislukt (= API-validatie mislukt) {#h_c093b0fa78}

![](https://help.qargo.com/media/d9450d5977b3-image.png)

##### API geslaagd {#h_7c0daf9eb8}

![](https://help.qargo.com/media/081d0524a663-image.png)

##### API-status upsert-fout (= import in UI mislukt) {#h_eb776ba8b1}

![](https://help.qargo.com/media/16f5cd91fc4a-image.png)

##### Foutscherm orderimport (= import in UI mislukt) {#h_29828d88b6}

![](https://help.qargo.com/media/970394050278-order-imports-list-green.png)

##### Orderimport corrigeren (UI) {#h_47c23c97a3}

![](https://help.qargo.com/media/f547d77c2c75-fix-order-data-form-green.png)

##### Orderimport corrigeren (API) {#h_9219b01e67}

![](https://help.qargo.com/media/8d93863219cb-image.png)

* * *

## Boekhoud-API en Facturerende Entiteiten {#h_8268f9d1d9}

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 {#h_eb25d542bf}

-   **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.

![](https://help.qargo.com/media/49d0bede7085-image.png)

### Gevolgen voor externe integraties {#h_666d05b4a7}

-   **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.

:::callout{tone="note"}
‼️ Boekhoudclients die in _Instellingen organisatie_ zijn aangemaakt, kunnen geen facturen boeken. Clients die facturen boeken altijd aanmaken op de instellingenpagina _Integratie boekhoud-API_.

![](https://help.qargo.com/media/2ccec67f2cc8-image.png)
:::

* * *

## Probleemoplossing {#h_e26ff07754}

| **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 {#h_07de834c15}

**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](mailto: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 {#h_cc6c5591eb}

**API-referentiedocumentatie ([api.qargo.com](http://api.qargo.com))**

-   [Qargo TMS API - Tenant: order](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Order)
-   [Qargo TMS API - specificatie klant](https://api.qargo.com/customer21704fc3a2dc66a58d59414b/docs)
-   [Qargo TMS API - specificatie onderaannemer](https://api.qargo.com/dispatch164648e0838e990ed2d2b195/docs)
-   [Qargo TMS API - synchronisatie master-gegevens](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Master-data-sync)
-   [Qargo TMS API - boekhouding](https://api.qargo.com/ca849acf3cb543a1975722a2882b7712/docs#tag/Use-case-Accounting)


## Gerelateerde artikelen

- [FAQ: Wat is de ondersteuning voor Facturerende Entiteiten in de boekhoud-API en wat betekent dit voor externe integraties?](https://help.qargo.com/nl/articles/482772-faq-wat-is-de-ondersteuning-voor-facturerende-entiteiten-in-de-boekhoud-api.md)
- [INTEGRATIES - Een AI-assistent via MCP met Qargo verbinden - Handleiding](https://help.qargo.com/nl/articles/799560-integraties-een-ai-assistent-via-mcp-met-qargo-verbinden-handleiding.md)
- [INTEGRATIES - Claude: via MCP verbinden met Qargo - stappenplan](https://help.qargo.com/nl/articles/799799-integraties-claude-via-mcp-verbinden-met-qargo-stappenplan.md)
- [FAQ – Qargo API: beschikbare opties](https://help.qargo.com/nl/articles/320484-faq-qargo-api-beschikbare-opties.md)
- [Integraties: wat, waarom en hoe](https://help.qargo.com/nl/articles/348704-integraties-wat-waarom-en-hoe.md)
