Sendcloud APIs - FAQ

Doel: Veelgestelde vragen met betrekking tot custom-shop integraties met behulp van Sendcloud API's. 

Wat zijn de rate limits?

Rate limits

Onze API heeft een rate limit die het aantal requests beperken die er per minuut kunnen worden gedaan. Houd er rekening mee dat er verschillende rate limits zijn voor Verzending-gerelateerde endpoints.

• Veilige requests (GET): 1000 requests per minuut
• Onveilige requests (POST/PATCH/PUT/DELETE): 100 requests per minuut
• Verzendingsgerelateerde veilige requests (GET): 420 requests per minuut
• Verzendingsgerelateerde onveilige requests (POST/PATCH/PUT/DELETE): 100 requests per minuut.

Maximum burst

Endpoints die als onveilig worden beschouwd hebben een ingestelde burst limit, wat het maximale aantal gelijktijdige requests is dat de API aankan. Het staat een tijdelijke verhoging van de aanvraagsnelheid toe om korte periodes van veel verkeer te accommoderen, zonder de algemene rate limit te overschrijden.

• Onveilige requests (POST/PATCH/PUT/DELETE): 15 requests per seconde
• Verzendings-gerelateerde onveilige requests (POST/PATCH/PUT/DELETE): 15 requests per seconde

Lees meer over het beperken van de snelheid in onze DEVELOPERS DOCUMENTATION.

Dit kan worden gewijzigd naar goeddunken van Sendcloud.

Hoe kan ik efficiënt gebruik maken van Sendcloud's API?

Er zijn verschillende manieren om efficiënt gebruik te maken van onze API. Je kunt bijvoorbeeld pakketten in bulk aanmaken, nieuw bijgewerkte pakketten ophalen met de updated_after  parameter of gebruik maken van webhooks om updates direct naar je systeem te krijgen.

Doe bulkaankondigingen parallel aan onze API, in kleinere batches. Voor het aankondigen van 100 pakketten zou je 5 x batches van 20 calls parallel aan onze API kunnen doen.

Ik wil direct labels aanmaken als ik een zending aanmaak via de API. Hoe doe ik dit?

Om zendingen en verzendlabels in één enkele API call aan te maken, vul je bij het request_label veld 'true' in. (Dit betreft de Create parcel request.) Het proces wordt in meer in detail uitgelegd in onze documentatie. 

Hoe kan ik idempotency handhaven voor orders/zendingen die ik importeer of aanmaak in Sendcloud?

In de context van API's verwijst idempotency naar wanneer het doen van meerdere verzoeken hetzelfde effect heeft als één enkel verzoek. Dit is om gebruikersfouten te voorkomen - en in het geval van Sendcloud API's - dubbele orders in ons systeem. Er zijn twee endpoints die proberen idempotent te zijn:

• Een parcel bewerken
  Gebruik het external_reference veld om idempotency te behouden. 

• Een lijst met zendingen maken/bewerken
  Dit is een upsert endpoint, wat betekent dat als een zending blijkt te bestaan binnen de Sendcloud database, de zending wordt geüpdatet. Als er geen match is, wordt hij aangemaakt. Je moet een combinatie gebruiken van external_order_id en external_shipment_id om idempotency te behouden. Alleen zendingen waarvan de updated_at (ISO 8601 DateTime) timestamp is veranderd worden bijgewerkt. We raden aan om een combinatie van deze velden te gebruiken voor een robuuste integratie. 

Waarom is sender_address een verplicht veld bij het aanmaken van labels via de API?

Vervoerders eisen dat op elk verzendlabel een afzenderadres staat, om aan te geven waar een pakket vandaan komt. Als er geen afzenderadres is opgegeven via de API, dan zal je standaard adres (zoals opgeslagen in je Sendcloud account) gebruikt worden om het label af te drukken. In onze documentatie leggen we in meer detail uit hoe je een Sender address ID verkrijgt en de relatie tussen afzendadressen, labels en brands.

Kan ik verzendregels gebruiken bij het aanmaken van zendingen via de API?

Verzendregels zijn van toepassing op zendingen die je aanmaakt via het panel, zolang het veld apply_shipping_rules true is. We raden je aan de verzendmethode "Unstamped letter" te gebruiken om je zendingen aan te maken, als je wilt dat de verzendregels correct worden toegepast. Hierdoor kun je de vereiste shipping_method velden omzeilen en worden alle regels die je hebt ingesteld - die van invloed zijn op de selectie van de verzendmethode - correct toegepast op je zending. 

Kan ik de API testen zonder in rekening te worden gebracht voor de labels die ik maak?

Je kunt de Sendcloud verzendmethode "Unstamped letter" gebruiken om je zendingen aan te maken. Hierdoor kun je de API testen zonder het risico te lopen dat je in rekening wordt gebracht voor alle labels die je maakt.

Let op: het is niet mogelijk om deze methode te gebruiken om het aanmaken van retourlabels te testen. Om retourlabels te testen, gebruik je een verzendmethode die annuleringsverzoeken van Sendcloud ondersteunt en annuleer je het label voor 23:59 uur op de dag van aanmaak. Zie onze documentatie over testlabels voor meer informatie. 

Ik krijg de foutmelding "User is not allowed to announce". Wat gaat er fout?

Zorg ervoor dat je alle stappen hebt gevolgd die horen bij de basis instellingen van je account en dat je een automatische incasso hebt geactiveerd. Zie: Aan de slag met Sendcloud. 

Kan ik al mijn verzendmethoden zien via de API als ik een direct carrier contract heb toegevoegd aan mijn Sendcloud account?

Ja, als je je eigen carrier contract hebt aangesloten, kun je je eigen methoden naast de Sendcloud methoden zien door een GET request te doen aan het 'Retrieve a list of shipping methods' endpoint. Let op dat je contractprijzen niet worden opgehaald, tenzij je je eigen contract prijzen hebt geüpload. 

Kan ik verzendprijzen zien en vergelijken via API als ik een eigen contract heb toegevoegd aan mijn Sendcloud account?

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

Ik krijg de foutmelding "Invalid shipment ID" als ik probeer een zending aan te maken via de API. Wat gaat er mis?

Waarschijnlijk verwijst de shipping_method_id die je gebruikt naar een methode die geen verzending van of naar het opgegeven adres ondersteunt. Bijvoorbeeld: als je een nationale methode gebruikt voor een internationale zending. Het kan ook zijn dat je een retourmethode probeert te gebruiken voor een uitgaande zending, of andersom. Je kunt de endpoint 'Shipping products' gebruiken om een methode te vinden die geschikt is voor je zending, op basis van de parameters die je in het verzoek definieert.

Let er tenslotte op dat de Shipping method name nog steeds betrekking heeft op de methode die je wilt gebruiken. Shipping method names in onze database zijn vluchtig en mogen niet langer dan een uur in de cache staan. 

Ik heb met succes een zending request gemaakt, maar de zending verschijnt niet in mijn Sendcloud account. Wat gaat er mis?

Waarschijnlijk bevatte de request geen waarde voor het boolean veld request_label.

• Als dit veld true is, wordt het label afgedrukt naast het verzoek om een zending aan te maken en verschijnt de zending in het tabblad 'Gecreëerde labels' in Sendcloud.
• Als de waarde false is, wordt het zending object aangemaakt, maar verschijnt de order in het overzicht met 'Inkomende orders' - wachtend op verwerking.
• Als je geen waarde hebt toegevoegd, dan kun je de Update a parcel endpoint gebruiken om het veld te veranderen request_label in true of false.  Je kunt de unieke parcel ID (die je nodig hebt in je request) vinden via het Retrieve all parcels endpoint. 

Ondersteunt de API het importeren van notities of opmerkingen velden in orders?

Ja, dit kan bijvoorbeeld worden gebruikt om notities aan orders toe te voegen, zoals "Gelieve geschenkverpakking voor verzending". Deze verschijnen ook op pakbonnen of picklijsten als je Pack & Go gebruikt.

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

Let op het direction filter wanneer je de request maakt naar het reporting endpoint. Als je de direction opgeeft als incoming, dan zie je alleen retourpakketten. Als je geen inkomende pakketten hebt, dan is het rapport leeg.

Ten tweede moet je de integratie-ID opgeven in je verzoek. Het is niet mogelijk om een rapport te maken voor al je integraties, dus zorg ervoor dat je de juiste de juiste ID toevoegt om je uitgaande of inkomende zendingen per integratie te zien. 

Hoe kan ik mijn integration_id vinden?

Je kunt je integration_id vinden in de Retrieve a list of integrations endpoint of vanuit je Sendcloud panel (Instellingen > Integraties > zoek je integratie in de lijst > Edit). De integration ID wordt aan het eind van de URL getoond, bijvoorbeeld: 'https://app.sendcloud.com/v2/settings/integrations/api/95977'.

Hoe kan ik mijn sender_address_id vinden? 

Via de Retrieve a list of sender addresses endpoint, of vanuit je Sendcloud panel (Instellingen > Adressen > Bewerken). De address ID wordt aan het eind van de URL getoond, bijvoorbeeld: 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'.

Hoe kan ik mijn brand_id vinden?

Via de Retrieve configured brands endpoint, of in je Sendcloud panel (Instellingen > Brands > Bewerken). De brand ID wordt aan het eind van de URL getoond, bijvoorbeeld 'https://app.sendcloud.com/v2/settings/brands/86054'.

Ik krijg de foutmelding "Service point delivery is not enabled for this integration." Wat gaat er mis?

Je moet de levering van servicepunten inschakelen in het Sendcloud panel, door te gaan naar Instellingen > Integraties > API > Bewerken > Vink het vakje aan om servicepuntlevering in te schakelen. Dit wordt hier in meer detail beschreven. 

Ik zie niet voor alle vervoerders methodes als ik een GET request maak voor een lijst van verzendmethoden.

Controleer eerst of je alle vervoerders die je wilt gebruiken hebt ingeschakeld door naar Verzenden> Vervoerders te gaan in je Sendcloud account. Gebruik het dropdown menu om meer carriers te selecteren per land waarin je een actief afzendadres hebt.

Ten tweede moet je één van je afzendadressen opgeven in je API request naar de Shipping methods endpoints, om methoden te zien voor andere landen dan het land van je standaard afzendadres. Bijvoorbeeld, als je standaard afzendadres in Nederland is, maar je wilt methoden zien voor Royal Mail (VK), dan moet je het adres ID voor je VK afzendadres opgeven, om VK verzendmethoden op te vragen. Dit wordt in detail uitgelegd in onze documentatie. 

Huisnummers staan dubbel op mijn verzendetiketten als ik pakketten aanmaak via de API. 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 meerdelige (multicollo) zendingen aanmaken via de API?

Ja, dat kan - dit wordt in meer detail beschreven in onze documentatie. 

Kan ik hetzelfde brand aan meerdere afzenderadressen toewijzen?

Ja, je kunt hetzelfde brand toewijzen aan enkele of alle afzenderadressen.

Kan ik meerdere brands aan hetzelfde afzenderadres toewijzen?

Per afzenderadres kan slechts één brand worden toegewezen. De workaround hiervoor is om een dubbel afzenderadres aan te maken en aan elk een ander brand toe te wijzen. Er kan er maar één als standaardadres worden opgegeven, dus we raden aan om het duplicaat een herkenbare naam te geven, zodat je deze gemakkelijk kunt identificeren in het panel. 

Kan ik internationale zendingen maken via de API?

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

Welke velden zijn verplicht voor internationale verzending?

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

Gerelateerde artikelen en andere middelen

→ Sendcloud API's Quick Start Guide

→ Sendcloud API Reference

→ Sendcloud Developer's Portal

→ Servicepunten voor API-integraties