---
title: "Integraties: orders importeren in Qargo"
description: "Orders importeren in Qargo via de API of partnerintegraties, met uitleg over mapping, validatie en probleemoplossing."
url: https://help.qargo.com/nl/articles/450378-integraties-orders-importeren-in-qargo
locale: nl
updated: 2026-02-12
---

# Integraties: orders importeren in Qargo

## Inleiding {#h_dd2958ae7f}

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

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

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:

-   [Gegevensimport: ordergegevens importeren](https://help.qargo.com/nl/articles/418636-data-import-importing-order-data)
-   [PalletLine-orderimport](https://help.qargo.com/nl/articles/143830-pn-palletline-order-import-export#h_34e1be7ccf)

### Importeren via integratiepartners {#h_6e0d048f1b}

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

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

:::callout{tone="info"}
**🧰 Technische documentatie van de Qargo API is [hier](https://api.qargo.com/docs) beschikbaar.**
:::

* * *

### Checklist voor gegevensmapping {#h_1e6174b22f}

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

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

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

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

:::callout{tone="info"}
**_Verplicht veld ontbreekt: customer\_id_**

-   Symptoom

    -   Fout: Verplicht veld ontbreekt: customer\_id
-   Oorzaak

    -   De bron heeft geen gemapte klant meegegeven of een onbekende waarde opgegeven.
-   Oplossing

    -   Nagaan of de klant in de master-gegevens van Qargo bestaat en of de mapping de juiste externe sleutel gebruikt.
    -   Voor partners: de mapping van de connector bijwerken.
    -   Voor de API: customer\_id of een herleidbare external\_customer\_ref meesturen.
:::

:::callout{tone="info"}
**_Ongeldig datum-tijdformaat voor pickup\_window.start_**

-   Symptoom

    -   Fout: Ongeldige datum-tijd. ISO 8601 met tijdzone verwacht
-   Oorzaak

    -   Datum-tijd verstuurd zonder tijdzone of in een niet-ISO-formaat.
-   Oplossing

    -   ISO 8601-strings versturen, bijvoorbeeld 2025-03-12T08:00:00+01:00.
    -   Formaten in het bronsysteem valideren vóór verzending.
:::

:::callout{tone="info"}
**_Onbekende locatie: consignee\_address_**

-   Symptoom

    -   Fout: Validatie van locatie mislukt voor ontvanger
-   Oorzaak

    -   Onvolledig of dubbelzinnig adres, of een verwijzing naar een opgeslagen locatie die niet bestaat.
-   Oplossing

    -   Het volledige adres opgeven, inclusief landcode.
    -   Bij gebruik van locatiereferenties eerst de master-gegevens synchroniseren.
:::

:::callout{tone="info"}
**_Niet-ondersteunde add-oncode: LIFTGATE\_PREMIUM_**

-   Symptoom

    -   Fout: Add-oncode niet herkend
-   Oorzaak

    -   De bron gebruikt een servicecode die niet in Qargo is geconfigureerd.
-   Oplossing

    -   De code toevoegen of mappen naar een ondersteunde add-on in Qargo.
    -   Codes in de connector normaliseren vóór verzending.
:::

:::callout{tone="info"}
**_Dubbele order gedetecteerd met external\_id=ABC-123_**

-   Symptoom

    -   Fout: Dubbele order
-   Oorzaak

    -   De idempotentie- of ontdubbelingscontrole heeft een herhaalde aanmaak gemarkeerd.
-   Oplossing

    -   Bij een bewuste nieuwe poging dezelfde idempotentiesleutel hergebruiken en het vorige resultaat controleren.
    -   Bij een echt duplicaat de external\_id wijzigen of de aanmaak omzetten naar een update.
:::

:::callout{tone="info"}
**_Documentbijlage afgewezen: bestandstype niet toegestaan_**

-   Symptoom

    -   Fout: Bestandstype niet ondersteund
-   Oorzaak

    -   Het type bijlage staat niet op de lijst met toegestane types.
-   Oplossing

    -   Omzetten naar een ondersteund formaat, meestal PDF of afbeeldingstypes die voor de werkomgeving zijn geconfigureerd.
    -   Ervoor zorgen dat de integratie MIME-types correct verstuurt.\
        ​
:::

:::callout{tone="info"}
**_API 429 Too Many Requests_**

-   Symptoom

    -   HTTP 429-antwoorden en headers voor snelheidsbeperking.
-   Oorzaak

    -   Piekverkeer overschrijdt de limieten.
-   Oplossing

    -   Exponentiële backoff toepassen en retry-after-headers respecteren.
    -   Batchgroottes spreiden en imports buiten de piekuren plannen.
:::

:::callout{tone="info"}
**_Melding "Fouten oplossen?" op het scherm Orderimport_**

-   Symptoom

    -   De gebruiker ziet tijdens de controle een banner of inline meldingen.
-   Oorzaak

    -   Een of meer geïmporteerde orders hebben validatieproblemen waarvoor input van een operator nodig is.
-   Oplossing

    -   De order openen, de gemarkeerde velden nakijken en de waarden corrigeren.
    -   Als hetzelfde probleem terugkomt, de mappingregels aan de bron bijwerken.
:::

### Voorinvullingen voor orders (geconfigureerd door de Qargo admin) {#h_3ac5923fbb}

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

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

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

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

### Veelgestelde vragen: voorinvullingen {#h_c3aa0333a8}

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

::video{src="/media/video/25c8b24b68d9-2025-11-17_11-49-48-1-.mp4"}

:::callout{tone="note"}
💬 Om deze functie in te schakelen, contact opnemen met Qargo Support of de accountmanager.
:::

* * *

### Aanbevolen werkwijzen om problemen te voorkomen {#h_c79fd5b2a4}

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


## Gerelateerde artikelen

- [INTEGRATIES - Qargo API - wat, waarom en hoe](https://help.qargo.com/nl/articles/865547-integraties-qargo-api-wat-waarom-en-hoe.md)
- [Orderimport: orderroutering op basis van sjablonen – wat, waarom en hoe](https://help.qargo.com/nl/articles/681640-orderimport-orderroutering-op-basis-van-sjablonen-wat-waarom-en-hoe.md)
- [Gegevensimport: locatiegegevens importeren](https://help.qargo.com/nl/articles/413082-gegevensimport-locatiegegevens-importeren.md)
- [Gegevensimport: wat, waarom, hoe](https://help.qargo.com/nl/articles/169976-gegevensimport-wat-waarom-hoe.md)
- [Orders: een order aanmaken](https://help.qargo.com/nl/articles/133885-orders-een-order-aanmaken.md)
