Overslaan en naar hoofdcontent gaan
Terug naar boven

Sendcloud APIs - FAQ

Louise Thomasson
  • Bijgewerkt

Onderwerp: In dit artikel beantwoorden we de meest gestelde vragen met betrekking tot aangepaste webshopintegraties met behulp van de Sendcloud API’s.

Wat zijn de rate limits?

Verzoeken aan onze API zijn beperkt per Sendcloud-account. Als je meerdere API-sleutels per Sendcloud-account hebt, wordt het budget gedeeld tussen deze sleutels.

Rate limits

Onze API heeft rate limits die het aantal verzoeken beperken dat per minuut kan worden gedaan. Houd er rekening mee dat er verschillende rate limits gelden voor verzendgerelateerde endpoints.

  • Veilige verzoeken (GET): 1000 verzoeken per minuut
  • Onveilige verzoeken (POST/PATCH/PUT/DELETE): 100 verzoeken per minuut.

Maximale burst

Endpoints die als onveilig worden beschouwd, hebben een vastgestelde burst-allowance, wat het maximale aantal gelijktijdige verzoeken is dat de API kan verwerken. Dit maakt een tijdelijke verhoging van het aantal verzoeken mogelijk om korte periodes van hoge verkeersbelasting op te vangen zonder de algemene rate limits te overschrijden.

  • Onveilige verzoeken (POST/PATCH/PUT/DELETE): 15 verzoeken per seconde.
Om onderbrekingen te voorkomen en optimaal gebruik van de API te behouden, is het essentieel om binnen de API rate limits te blijven. Als de limiet wordt overschreden, ontvang je een HTTP 429 (Too Many Requests) reactie.

Lees meer over rate limiting in onze developersdocumentatie.

Dit kan worden gewijzigd naar goeddunken van Sendcloud.

Ik wil labels direct aanmaken wanneer ik een zending via de API aanmaak. Hoe kan ik dat doen?

Om zendingen en verzendlabels in één enkele API-aanroep aan te maken, gebruik je het synchrone endpoint van de Shipments of Ship an Order API. Het label wordt automatisch teruggegeven in de response in het veld data.parcels.label_file. Dit is alleen beschikbaar voor Single Collo-zendingen (zendingen die uit één pakket bestaan).

Hoe kan ik idempotentie behouden voor bestellingen/zendingen die ik importeer of aanmaak in Sendcloud?

In de context van API’s verwijst idempotentie naar het feit dat meerdere verzoeken hetzelfde effect hebben als één enkel verzoek. Dit voorkomt gebruikersfouten en, in het geval van de Sendcloud API’s, duplicatie van bestellingen in ons systeem. Er zijn vier endpoints die proberen idempotent te zijn:

  • Alle POST shipments-endpoints
    Gebruik het veld external_reference_id  om idempotentie te behouden. 

Kan ik verzendregels gebruiken wanneer ik zendingen via de API aanmaak?

Verzendregels worden toegepast op zendingen die je via de API aanmaakt, zolang je zendingen aanmaakt via de Create a shipment with rules and/or defaults synchrone of asynchrone endpoints. We raden aan om de verzendoptie “Ongefrankeerde brief” ("shipping_option_code": "sendcloud:letter") te gebruiken om je zendingen aan te maken als je wilt dat verzendregels correct worden toegepast. Hiermee kun je het verplichte ship_with-object omzeilen en worden eventuele regels die je hebt geconfigureerd en die van invloed zijn op de selectie van de verzendoptie correct toegepast op je pakket. 

Kan ik de API testen zonder kosten in rekening gebracht te krijgen voor de labels die ik aanmaak? 

Je kunt de Sendcloud-verzendoptie “Ongefrankeerde brief” ("shipping_option_code": "sendcloud:letter") gebruiken om je zendingen aan te maken. Hiermee kun je de API testen zonder het risico dat er kosten in rekening worden gebracht voor labels die je aanmaakt.

Houd er rekening mee dat het niet mogelijk is om deze verzendoptie te gebruiken om retourlabels aan te maken. Om retourlabels te testen, gebruik je een verzendoptie die annuleringsverzoeken vanuit Sendcloud ondersteunt en annuleer het label vóór 23:59 op de dag van aanmaak. Bekijk onze documentatie over testlabels voor meer informatie. 

Ik ontvang de foutmelding “User is not allowed to announce”. Wat gaat er mis?

Zorg ervoor dat je alle stappen voor de basisaccountinstellingen hebt gevolgd en een automatische incassobetalingsmethode hebt geactiveerd. Zie: Welkom bij Sendcloud. 

Kan ik al mijn verzendopties via de API zien wanneer ik een direct vervoerderscontract koppel?

Ja - als je je eigen vervoerderscontract hebt gekoppeld, kun je je eigen verzendopties samen met de Sendcloud-verzendopties ophalen door een verzoek te doen naar het Shipping options API-endpoint. Houd er rekening mee dat de prijzen van je contract niet worden opgehaald, tenzij je je eigen vervoerdersprijzen hebt geüpload. 

Kan ik mijn eigen prijzen uit mijn directe vervoerderscontracten zien wanneer ik de API gebruik om tarieven te controleren en methoden te vergelijken?

Ja, als je je eigen prijzen naar je Sendcloud-account hebt geüpload door de stappen in dit artikel te volgen. 

Ik ontvang de foutmelding “No shipping option could be found for[…]” wanneer ik probeer een zending via de API aan te maken. Wat gaat er mis?

Waarschijnlijk verwijst de shipping_option_codedie je gebruikt naar een verzendoptie die verzending naar of van het opgegeven adres niet ondersteunt, bijvoorbeeld wanneer je een nationale methode gebruikt voor een internationale zending. Het kan ook zijn dat je een retourverzendoptie probeert te gebruiken voor een uitgaande zending, of andersom. Je kunt het Shipping options-endpoint gebruiken om een verzendoptie te vinden die geschikt is voor je zending op basis van de parameters die je in het verzoek definieert.

Ondersteunt de API het importeren van notities of opmerkingenvelden in bestellingen?

Ja. Dit kan bijvoorbeeld worden gebruikt om notities aan bestellingen toe te voegen, zoals “Verpak dit artikel als cadeau voordat je het verzendt”. Deze verschijnen ook op pakbonnen of picklijsten als je Pack & Go gebruikt. 

Ik heb een rapport via de API aangemaakt, maar mijn CSV-bestand is leeg. Wat gaat er mis?

Let op de direction-filter wanneer je het verzoek aan het reporting-endpoint aanmaakt. Als je de direction instelt op incoming, zie je alleen retourpakketten. Als je geen inkomende retourpakketten hebt, is het rapport leeg.

Daarnaast moet je de integration ID in je verzoek specificeren. Het is niet mogelijk om een rapport voor al je integraties aan te maken, dus zorg ervoor dat je de juiste ID opgeeft om je uitgaande of inkomende pakketten per integratie te zien. 

Hoe kan ik mijn integration_id vinden?

Je kunt je integration_idvinden via het Retrieve a list of integrations-endpoint, of in je Sendcloud-panel (Instellingen > Integraties > zoek je integratie in de lijst > Bewerken). De integration ID wordt weergegeven aan het einde van de URL, bijvoorbeeld: 'https://app.sendcloud.com/v2/settings/integrations/api/95977'

Hoe kan ik mijn sender_address_id vinden? 

Via het Retrieve a list of sender addresses-endpoint, of in je Sendcloud-panel (Instellingen > Adressen > Bewerken van een adres). De ID wordt weergegeven aan het einde van de URL, bijvoorbeeld: 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'

Hoe kan ik mijn brand_id vinden?

Via het Retrieve configured brands endpoint, of in je Sendcloud-panel (Instellingen > Merken > Bewerken van een merk). De ID wordt weergegeven aan het einde van de URL, bijvoorbeeld: 'https://app.sendcloud.com/v2/settings/brands/86054'

Ik ontvang de foutmelding “Service point delivery is not enabled for this integration.” Wat gaat er mis?

Je moet servicepuntlevering inschakelen in het Sendcloud-panel via Instellingen > Integraties > API > Bewerken > Vink het vakje aan om servicepuntlevering te activeren. Dit wordt hier uitgebreider beschreven hier. 

Huisnummers worden dubbel weergegeven op mijn verzendlabels wanneer ik pakketten via de API aanmaak. Wat gaat er mis?

Het meest gebruikte adresformaat is als volgt:

  • address : Stadhuisplein
  • house_number: 10

Een andere veelgebruikte methode is:

  • address: Stadhuisplein 10

Kan ik multi-piece (multicollo) zendingen via de API aanmaken?

Ja, dat kan—dit wordt uitgebreider beschreven in onze documentatie. 

Kan ik hetzelfde merk toewijzen aan meerdere afzenderadressen?

Ja, je kunt hetzelfde merk toewijzen aan sommige of al je afzenderadressen.

Kan ik meerdere merken toewijzen aan hetzelfde afzenderadres?

Er kan slechts één merk per afzenderadres worden toegewezen. De oplossing hiervoor is om een duplicaat van het afzenderadres aan te maken en aan elk adres een ander merk toe te wijzen. Slechts één adres kan als standaardadres worden ingesteld, dus we raden aan om het duplicaat een herkenbare naam te geven zodat je het gemakkelijk kunt identificeren in het panel. 

Kan ik internationale zendingen via de API aanmaken?

Ja, absoluut. Je douanedocumenten worden automatisch gegenereerd, mits de verplichte velden (zie hieronder) correct zijn gespecificeerd per product in de zending. Dit wordt uitgebreider uitgelegd in onze documentatie: Internationaal verzenden

Welke velden zijn verplicht voor internationale verzending?

  • customs_invoice_number
  • customs_shipment_type
  • country_state(Alleen verplicht voor Australië, Canada, Italië en de VS.)
  • parcel_items
    • origin_country (ISO 2) 
    • hs_code

Gerelateerde artikelen en bronnen

→ Sendcloud API Quick Start Guide

→ Sendcloud API Reference

→ Sendcloud Developer Portal

→ Servicepunten voor API-integraties