Sendcloud APIs - FAQ

Thema: Häufig gestellte Fragen zu eigenen Shop Integrationen mit der Sendcloud API.

Was sind die Ratenlimits?

Ratenlimits

Unsere API hat Ratenlimits, die die Anzahl der Anfragen, die pro Minute gestellt werden können, begrenzen. Beachte, dass es für versandbezogene Endpunkte unterschiedliche Ratenlimits gibt.

• Sichere Anfragen (GET): 1000 Anfragen pro minute.
• Unsichere Anfragen (POST/PATCH/PUT/DELETE): 100 Anfragen pro minute.
• Versandbezogene sichere Anfragen (GET): 420 Anfragen pro minute.
• Versandbezogene unsichere Anfragen (POST/PATCH/PUT/DELETE): 100 Anfragen pro minute.

Maximaler Burst

Endpunkte, die als unsicher gelten, haben eine festgelegte Burst-Zulassung, d.h. die maximale Anzahl gleichzeitiger Anfragen, die die API verarbeiten kann. Dies ist die maximale Anzahl gleichzeitiger Anfragen, die die API bewältigen kann. Sie erlaubt eine vorübergehende Erhöhung der Anfragerate, um kurze Perioden mit hohem Datenverkehr zu bewältigen, ohne die allgemeinen Ratengrenzen zu überschreiten.

• Unsichere Anfragen (POST/PATCH/PUT/DELETE): 15 Anfragen pro Sekunde.
• Versandbezogene unsichere Anfragen (POST/PATCH/PUT/DELETE): 15 Anfragen pro Sekunde

Lies mehr über die Ratenbegrenzung in unserer Entwicklerdokumentation.

Dies kann sich nach dem Ermessen von Sendcloud ändern.

Wie kann ich Sendclouds API effizient nutzen?

Es gibt verschiedene Möglichkeiten, unsere API effizient zu nutzen. Du kannst zum Beispiel Pakete in großen Mengen erstellen, neu aktualisierte Pakete mit dem Parameter „updated_after“ abrufen oder Webhooks nutzen, um Aktualisierungen direkt in dein System zu übertragen.

Führe Massenankündigungen parallel zu unserer API in kleineren Stapeln durch. Für die Ankündigung von 100 Paketen könntest du 5 × 20 Aufrufe parallel zu unserer API durchführen.

Ich möchte direkt das Versandlabel erstellen lassen, wenn ich ein Paket über die API erstelle. Wie kann ich das tun?

Um Paket und Label in einem einzigen API-Call zu erstellen, musst du bei der Anfrage an den Create a parcel Endpoint für den Wert request_label einfach „true“ hinterlegen. Weitere Informationen dazu findest du in unserer Dokumentation.

Wie kann ich für Aufträge/Sendungen, die ich in Sendcloud importiere bzw. erstelle, Idempotenz erhalten?

Im Zusammenhang mit APIs bedeutet Idempotenz, dass mehrere Anfragen die gleiche Wirkung haben wie eine einzige Anfrage. Damit sollen Benutzerfehler und im Falle der Sendcloud-APIs die Verdoppelung von Aufträgen in unserem System verhindert werden. Es gibt zwei Endpunkte, die versuchen, idempotent zu sein:

• Update a parcel
  Nutze das external_reference Feld, um die Idempotenz beizubehalten.

• Create/Update a list of shipments
  Dies ist ein Upsert-Endpunkt, d. h. wenn eine Sendung bereits in der Sendcloud-Datenbank vorhanden ist, wird sie aktualisiert. Wenn es keine Übereinstimmung gibt, wird sie stattdessen erstellt. Du musst eine Kombination aus external_order_id und external_shipment_id verwenden, um die Idempotenz zu wahren. Es werden nur Sendungen aktualisiert, bei denen der Zeitstempel updated_at (ISO 8601 DateTime) geändert wurde. Wir empfehlen die Verwendung einer Kombination dieser Felder, um eine stabile Integration zu gewährleisten.

Warum istsender_address ein Pflichtfeld beim Erstellen eines Labels über die API?

Versanddienstleister verlangen, dass auf jedem Versandetikett eine Absenderadresse angegeben wird, um den Absender eines Pakets zu identifizieren. Wenn bei der Erstellung eines Pakets über die API keine Absenderadresse angegeben wird, wird deine Standardadresse (wie in deinem Sendcloud-Konto gespeichert) für den Druck des Etiketts verwendet. Wie Sie eine Absenderadresse erhalten und wie die Verbindung zwischen Absenderadressen, Etiketten und Marken aussieht, wird in unserer Dokumentation genauer erklärt.

Kann ich Versandregeln benutzen, wenn ich Pakete über die API erstelle?

Versandregeln werden angewendet, wenn du die Pakete über das Sendcloud Panel erstellt, solange der Wert apply_shipping_rules auf true gesetzt ist. Wir empfehlen die Versandmethode „Unstamped Letter“ zum Erstellen deiner Pakete zu verwenden, wenn du Versandregeln darauf anwenden möchtest. So kannst du die Pflichtangabe shipping_method hinterlegen und alle Versandegeln, welche die Versandmethode ändern, werden korrekt angewendet.

Kann ich die API testen, bevor mir erstellte Labels in Rechnung gestellt werden?

Du kannst die Versandmethode „Unstamped Letter“ (unfrankierter Brief) verwenden, um deine Pakete zu erstellen. Das erlaubt dir, die API zu testen, ohne für erstellte Labels Rechnungen zu erhalten.

Bitte beachte, dass es nicht möglich ist, diese Versandmethode für Retouren zu verwenden. Um Retourensendungen zu testen, verwende bitte eine Versandmethode, die über Sendcloud storniert werden kann und storniere das Label vor 23:59 Uhr am Tag der Erstellung. In unserer Dokumentation findest du weitere Informationen zum Erstellen von Testlabels.

Ich erhalte die Fehlermeldung „User is not allowed to announce“. Wo liegt der Fehler?

Stelle sicher, dass du die grundlegenden Schritte zum Einrichten deines Kontos durchgeführt und ein Lastschriftverfahren verbunden hast. Siehe: Starte mit Sendcloud.

Kann ich alle meine Versandmethoden über die API sehen, wenn ich einen eigenen Vertrag mit einem Versanddienstleister anbinde?

Ja – Wenn du einen eigenen Vertrag mit einem Versanddienstleister verbunden hast, kannst du neben den Sendcloud-Versandmethoden auch deine eigenen Versandmethoden anfragen, indem du eine GET-Anfrage an den Endpunkt „Liste der Versandmethoden abrufen“ stellst.

Kann ich meine eigenen Preise aus meinen eigenen Verträgen mit Versanddienstleistern sehen, wenn ich die API verwende, um Tarife zu prüfen und Methoden zu vergleichen?

Ja, wenn du zuvor deine eigenen Preise in Sendcloud per CSV Datei hochgeladen hast.

Ich erhalte die Fehlermeldung, „Invalid Shipment ID“, wenn ich ein Paket über die API erstelle. Was mache ich falsch?

Es ist wahrscheinlich, dass sich die von dir verwendete shipping_method_id auf eine Versandmethode bezieht, die von der gewählten Adresse nicht unterstützt wird, z. B. wenn du eine nationale Versandmethode für den internationalen Versand verwenden möchtest. Es ist auch möglich, dass du eine Retourenmethode für eine ausgehende Sendung verwenden möchtest. Du kannst den Shipping Products Endpoint verwenden, um eine für dein Paket passende Versandmethode zu finden, basierend auf den Parametern, die du in deiner Anfrage festlegst.

Achte abschließend auch darauf, dass der Name der Versandmethode immer noch mit der gewünschten Versandmethode übereinstimmt. Die Versandmethoden-Namen in unserer Datenbank können sich ändern und sollten nicht länger als eine Stunde zwischengespeichert werden.

Ich habe erfolgreich einen Paketauftrag erstellt, aber das Paket erscheint nicht in meinem Sendcloud Konto. Was läuft da schief?

Es ist wahrscheinlich, dass die Anfrage keinen Wert für den boolesche Wert request_label enthält. 

• Wenn dieser Wert true ist, wird das Label zusammen mit der Anfrage für die Erstellung eines Pakets gedruckt, und das Paket erscheint in dem Tab erstellte Labels in Sendcloud.
• Wenn der Wert stattdessen false ist, wird das Paketobjekt erstellt, taucht dann aber unter deinen eingehenden Bestellungen auf.
• Wenn du diesen Wert nicht festlegt, kannst du den Update a parcel Endpoint verwenden, um das Feld auf trueoder falsezu setzen. Die Paket-ID (welche du für die Anfrage benötigst) erhältst du über den Retrive all parcels Endpoint.

Unterstützt die API das Importieren von Notizen oder Bemerkungsfeldern in Bestellungen?

Ja! Damit du zum Beispiel die Notiz „Bitte verpacke den Artikel vor dem Versand als Geschenk“ hinzufügen kannst. Diese erscheinen dann auch auf den Kommissionierlisten und Lieferscheinen, wenn du Pack & Go verwendest. 

Ich habe einen Bericht über die API erstellt, aber meine CSV-Datei ist leer. Was läuft da schief?

Bitte beachte den direction Filter, wenn du eine Anfrage an den reporting Endpoint sendest. Wenn du die direction als incoming festlegst, siehst du nur Retourensendungen. Wenn du keine eingehenden Retouren hast, ist der Bericht leer.

Außerdem musst du die Integrations-ID in deiner Anfrage angeben. Es ist nicht möglich, einen Bericht für alle deine Integrationen auf einmal zu erstellen, stelle daher sicher, dass du die korrekte Integrations-ID angibst.

Wie finde ich meine integration_id?

Du findest die integration_id über den Retrieve a list of integrations Endpoint oder in deinem Sendcloud Panel (Einstellungen > Integrationen > Finde deine Integration auf der Liste > Konfigurieren), die Integrations-ID findest du am Ende der URL, also zum Beispiel 'https://app.sendcloud.com/v2/settings/integrations/api/95977'.

Wie finde ich meine sender_address_id? 

Über den Retrieve a list of sender addresses Endpoint oder in deinem Sendcloud PaNel (Einstellungen > Adressen > Absenderadressen > Konfigurieren), Die Absender-ID findest du am Ende der URL, also zum Beispiel 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'

Wie finde ich meine brand_id?

Über den Retrieve configured brands Endpoint oder in deinem Sendcloud Panel (Einstellungen > Brands > Konfigurieren), die Integrations-ID findest du am Ende der URL, also zum Beispiel 'https://app.sendcloud.com/v2/settings/brands/86054'

Ich erhalte die Fehlermeldung „Service point delivery is not enabled for this integration.“ Was läuft hier schief?

Du musst die Service Point Zustellung in deinem Sendcloud Panel aktivieren. Gehe dazu zu Einstellungen > Integrationen > API > Konfigurieren > Setzte den Haken bei Service Point Delivery. Genauere Infos dazu findest du auch im Artikel API Dokumentation und Quick Start Guide.

Wenn ich eine GET-Anfrage stelle, um eine Liste der Versandmethoden abzurufen, sehe ich nicht die Methoden aller Anbieter.

Als Erstes solltest du prüfen, dass du alle gewünschten Versanddienstleister in deinem Sendcloud Konto unter Versand > Versanddienstleister aktiviert hast. Benutze das Dropdown-Menü, um für jedes der Länder, in denen du eine Absenderadresse hast, weitere Versanddienstleister hinzuzufügen.

Wenn du das erledigt hast, musst du die gewünschte Absenderadresse in deiner Anfrage an den Shipping Methods Endpoint angeben, um Versandmethoden für andere Länder als dem Land deiner Standard-Absenderadresse anzeigen zu lassen. Wenn deine Standard-Absenderadresse Beispielsweise in Deutschland ist, du aber die Versandmethoden für Royal Mail (Großbritannien) einsehen möchtest, musst du die Absender-ID deiner britischen Absenderadresse angeben. In unserer Dokumentation findest du genauere Infos dazu.

Wenn ich Pakete über die API erstelle, werden die Hausnummern auf meinen Versandetiketten dupliziert. Was läuft da schief?

Das am häufigsten verwendete Adressformat ist wie folgt:

• address : Fürstenrieder Straße
• house_number: 70

Alternativ kannst du die Adresse auch folgendermaßen angeben:

• address: Fürstenrieder Straße 70

Kann ich mehrteilige (Multicollo) Sendungen über die API erstellen?

Ja, kannst du—genauere Informationen dazu findest du in unserer Dokumentation. 

Kann ich die gleiche Brand mehreren Absenderadressen zuordnen?

Ja, du kannst einigen oder allen deinen Absenderadressen dieselbe Brand zuweisen.

Kann ich der gleichen Absenderadresse mehrere Brands zuordnen?

Pro Absenderadresse kann nur eine Brand zugewiesen werden. Du kannst dies aber umgehen, indem du eine Absenderadresse einfach mehrmals anlegst und jedem Eintrag eine andere Brand zuweist. Da nur eine Adresse als Standardadresse festgelegt werden kann, empfehlen wir, dem Duplikat einen einprägsamen Namen zu geben, damit du die Adressen im Panel einfach auseinanderhalten kannst.

Kann ich internationale Sendungen über die API erstellen?

Selbstverständlich! Die Zolldokumente werden direkt automatisch erstellt, insofern du die Pflichtfelder (siehe unten) korrekt für jeden Artikel deiner Sendung ausfüllst. Genauere Informationen dazu findest du in unserer Dokumentation.

Was sind die Pflichtfelder für den internationalen Versand?

• customs_invoice_number
• customs_shipment_type
• country_state(Nur verpflichtend für Australien, Kanada, Italien und die USA)
• parcel_items
  • origin_country (ISO 2) 
  • hs_code

Related articles and resources

→ API Dokumentation und Quick Start Guide

→ Sendcloud API Referenz (Englisch)

→ Sendcloud Entwickler Portal (Englisch)

→ API Paketshopzustellung