Tabellen

Wandle Links in einer Google-Tabelle oder hochgeladenen Arbeitsmappe mit dem Bearer-Token deines Kontos um. Die Ausgabe ist immer .xlsx, auch bei CSV-Eingaben. Links werden an derselben Stelle ersetzt, mit deiner Kontozuordnung und optional campaign und label gemäß Links.

Google-Tabelle als EingabeAbschnittslink kopieren

Sende eine Google-Sheets-URL, die NinjaBuy lesen kann. Die Umwandlung liest alle Tabs statt nur der Vorschau und friert einen Snapshot für diesen Auftrag ein.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

XLSX oder CSV als EingabeAbschnittslink kopieren

Reserviere zuerst einen Upload. filename muss nach dem Entfernen umgebender Leerzeichen 1 bis 255 Zeichen enthalten und auf .xlsx oder .csv enden. bytes ist die genaue Dateigröße in Bytes, von 1 bis 20.971.520.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

Die Antwort 201 enthält upload_id, eine signierte PUT-url, expires_at (Millisekunden seit der Unix-Epoche), max_bytes und request_id. Die Reservierung läuft nach 15 Minuten ab. Sende die Rohdatei per PUT an die zurückgegebene URL und übermittle dann ihre Upload-ID:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

Der direkte PUT verwendet das Antwortformat des Speicherdienstes. NinjaBuy prüft die hochgeladenen Bytes beim Einreichen der Umwandlung. Unbekannte oder fremde Upload-IDs ergeben 404. Das gespeicherte Objekt muss der angegebenen Byteanzahl entsprechen; ein Objekt, das größer als angegeben ist oder die Obergrenze überschreitet, ergibt 413 upload-too-large, und ein kleineres (abgeschnittenes) Objekt ergibt 422 invalid-workbook mit einer Erklärung zur abweichenden Byteanzahl. Diese Prüfungen erfolgen vor dem Herunterladen und greifen auch, wenn sich die Bytes nach der Metadatenprüfung ändern. Abgelehnte Rohuploads werden gelöscht; akzeptierte Rohuploads werden gelöscht, sobald ihr validierter Snapshot gespeichert ist.

Sende genau eine Quelle: url oder upload_id. Beide akzeptieren optional campaign und label; async ist nicht nötig. Beide POST-Routen akzeptieren Idempotency-Key und verbrauchen jeweils einen Platz im gemeinsamen Kontingent von 30 Aufrufen pro Minute. Untergeordnete Linkumwandlungen verbrauchen keine weiteren Plätze.

Auftrag und DownloadAbschnittslink kopieren

Eine Tabellenübermittlung ergibt 202 mit Location: /api/v1/jobs/JOB_ID, Retry-After: 5 und diesem Körper:

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

Frage Aufträge mit dem Token desselben Kontos bis done oder failed ab und beachte poll_after_seconds. Ein abgeschlossenes job.result enthält kind: "sheet_conversion", counts und eine signierte download_url, die 15 Minuten gültig ist. Frage erneut ab, um eine neue Downloadsignatur zu erhalten. Ein fehlgeschlagener Auftrag enthält error und keinen Teildownload.

Bei einem Google Sheet kann job.result zusätzlich copy_url enthalten: einen Nur-Lese-Link zu einer exakten Google-Sheets-Kopie mit deinen Links an ihrer Stelle; wer den Link hat, kann mit Datei → Kopie erstellen eine eigene Kopie anlegen. copy_notes nennt, was Leser dieser Kopie wissen sollten, etwa dass mit =IMAGE() eingefügte Bilder in ihrer Kopie einmal Zugriff erlauben brauchen. download_url liefert weiterhin die XLSX-Datei. copy_counts enthält dieselben Zählungen für die Kopie; lässt sich die XLSX-Datei nicht erstellen, behält das Ergebnis copy_url, hat kein download_url, und copy_notes nennt den Grund. download_notes nennt Zeile für Zeile, was die XLSX-Datei vom Sheet nicht enthalten kann, etwa Diagramme oder einen zweiten Link in einer Zelle.

Snapshots und Ergebnisdateien werden sieben Tage nach Abschluss oder Fehlschlagen des Auftrags aufbewahrt. Nach der Bereinigung bleibt der Auftrag mit seinem Status und seinen Zählern abrufbar; job.result.download_url wird weggelassen. Gemeinsam genutzte Snapshots bleiben erhalten, solange ein anderer Auftrag sie noch benötigt. Verwaiste Rohuploads werden eine Stunde nach Ablauf der Upload-Reservierung gelöscht; bei einem validierten Upload, für den nie ein Auftrag gestartet wird, wird der Snapshot sieben Tage nach Ablauf der Reservierung gelöscht. Die Bereinigung läuft stündlich.

Es gilt links_found = converted + sum(left_by_host) + unresolved. Social-Media-Links, Google-Sheets-Links, Navigation innerhalb derselben Arbeitsmappe und vorhandene NinjaBuy-Links bleiben unverändert. Jeder Umwandlungskandidat muss vor dem Schreiben der Ausgabe eine Antwort erhalten; fehlende Antworten lassen den Auftrag fehlschlagen.

Erhaltung der ArbeitsmappeAbschnittslink kopieren

Die Ausgabe erhält Stile, verbundene Zellen, Zeilen- und Spaltengrößen sowie Bilder, soweit sie im eingelesenen Raster abgebildet sind. Rich-Text-Abschnitte bleiben in Zellen ohne Zellhyperlink erhalten; verlinkte Zellen verwenden eine Textbezeichnung und einen Hyperlink. Die Arbeitsmappe wird neu serialisiert: Diagramme, Makros und andere Funktionen außerhalb dieses Rasters bleiben nicht erhalten.

XLSX unterstützt einen Hyperlink pro Zelle. Die Umwandlung ersetzt Links an Ort und Stelle, statt daneben einen zweiten Link einzufügen. Eine Zelle mit zwei oder mehr verschiedenen Linkzielen ohne Bild behält das erste als Hyperlink und führt die übrigen in der Notiz der Zelle auf, sodass kein Ziel verloren geht.

GrenzenAbschnittslink kopieren

Eine überschrittene Parser- oder Ausgabegrenze führt ausdrücklich zum Fehler. Siehe Fehler für invalid-workbook, upload-expired und upload-too-large.