Links
Anfragefelder, Ergebnisse pro Link und wiederholte Anfragen.
Links erstellen
POST https://www.ninjabuy.com/api/v1/links erfordert ein Bearer-Token und Content-Type: application/json.
| Feld | Regeln |
|---|---|
links | Erforderliches Array mit 1 bis 2.000 Zeichenfolgen. Jede Eingabe wird von umgebenden Leerzeichen befreit und muss 1 bis 4.096 Zeichen lang sein. |
campaign | Optional, 3 bis 64 Kleinbuchstaben, Ziffern oder Bindestriche, beginnend mit einem Buchstaben oder einer Ziffer: ^[a-z0-9][a-z0-9-]{2,63}$. Besuche führen diesen Wert als utm_campaign mit. |
label | Optionaler Name in deiner Linkliste: nach dem Entfernen umgebender Leerzeichen 1 bis 40 druckbare Zeichen, ohne Steuerzeichen. Werden Leerzeichen entfernt, entsteht eine Warnung. |
async | Optionaler boolescher Wert. true startet immer einen Hintergrundauftrag. |
Produktlinks von Taobao, Tmall, Weidian und 1688, unterstützte Links von Einkaufsagenten und Kurzlinks, Weidian- und Taobao-Shops (auch die Seite eines unterstützten Agenten dafür) sowie unterstützte öffentliche NinjaBuy-Seiten können umgewandelt werden. Eine NinjaBuy-URL oder ein bloßer Pfad wie /search?q=hoodie wird akzeptiert. Wenn du einen vorhandenen NinjaBuy-Empfehlungslink einfügst, erhältst du deinen eigenen zugeordneten Link zu dessen Ziel.
Direkt oder als Stapel
Bis zu 100 Eingaben ohne async: true ergeben 200 mit results, warnings und request_id. Mehr als 100 oder async: true ergeben 202 mit einem Auftrag, Location und Retry-After. Siehe Schnellstart und Aufträge.
Ergebnisse behalten die Eingabereihenfolge bei, auch bei wiederholten Eingaben. Jede Zeile enthält input und status sowie optional target, url, code und note.
| Status | Bedeutung |
|---|---|
ok | Umgewandelt; url ist der zugeordnete NinjaBuy-Link. |
unsupported | Erkannt, aber nicht verlinkbar, etwa ein nicht unterstützter Marktplatz oder eine private NinjaBuy-Seite. |
unreadable | Es konnte kein verwendbares Ziel gelesen werden. |
sheet | Eine Google-Sheet-URL; dieser Endpunkt wandelt deren Inhalte nicht um. |
Bei einer Tabelle kannst du mit der Tabellen-API den Inhalt in XLSX umwandeln oder sie auf NinjaBuy einfügen. Eine vorhandene NinjaBuy-Seite unter /spreadsheets/d/<sheet id> kann selbst einen zugeordneten Link erhalten.
Wiederholte Anfragen und Zuordnung
Für dasselbe Konto, normalisierte Ziel, dieselbe Kampagne und Bezeichnung liefert die Erstellung denselben Link über REST, MCP und Stapelverarbeitung. Eine andere Kampagne oder Bezeichnung erhält einen eigenen Link. Ohne Idempotency-Key erstellt das erneute Senden eines Stapels einen neuen Auftrag; die Wiederverwendung von Links dedupliziert keine Aufträge.
Neue REST-Links speichern createdVia: "api". Bei Wiederverwendung bleibt die ursprüngliche Quelle (api, mcp, share oder redirect) erhalten. Dieses Feld steht in MCP-Ergebnissen von list_links und link, nicht in der REST-Erstellungsantwort. Siehe Empfehlungen zu Zuordnung und Berichten.
Idempotency-Key
Sende optional Idempotency-Key bei POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets, um eine Anfrage ohne weiteren Auftrag oder zusätzlichen Aufruf im Linkkontingent zu wiederholen. Verwende für jede beabsichtigte Anfrage einen eigenen Schlüssel aus 1 bis 255 druckbaren ASCII-Zeichen.
Idempotency-Key: partner-batch-2026-10-23-001Für 24 Stunden geben dasselbe Konto, derselbe Schlüssel und dieselbe validierte Anfrage den ursprünglichen Status, bytegleichen Körper und die ursprünglichen Header einschließlich request_id zurück, ergänzt um Idempotent-Replayed: true. Die Reihenfolge der JSON-Objektschlüssel ist unerheblich. Nach 24 Stunden kannst du den Schlüssel wiederverwenden.
- Ein anderer Körper oder eine andere POST-Route mit demselben Schlüssel ergibt
422(idempotency-key-reused); verwende einen neuen Schlüssel. - Solange die erste Anfrage läuft, ergeben Wiederholungen
409(idempotency-key-in-progress) mitRetry-After; warte vor dem nächsten Versuch. - Ein ungültiger Schlüssel ergibt
400(bad-idempotency-key). Ungültige Körper reservieren keinen Schlüssel. - Sobald die Ausführung beginnt, wird die erste Antwort einschließlich Fehlern gespeichert. Ein
429wird nicht gespeichert: Wiederhole mit demselben Schlüssel nachRetry-After.
Eine abgestürzte Anfrage kann bis zum Ablauf des Schlüssels als laufend gelten. Diese Antwortwiederholung ist von der oben beschriebenen Wiederverwendung passender Links getrennt.