Spreadsheets

Zet links in een Google-spreadsheet of geüploade werkmap om met het bearer-token van je account. De uitvoer is altijd .xlsx, ook bij CSV-invoer. Links worden op dezelfde plek vervangen, met de toeschrijving aan je account en optioneel campaign en label zoals beschreven bij Links.

Google-spreadsheet als invoerSectielink kopiëren

Stuur een Google Sheets-URL die NinjaBuy kan lezen. De conversie leest elk tabblad, niet alleen de voorbeeldweergave, en legt een momentopname voor deze opdracht vast.

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 of CSV als invoerSectielink kopiëren

Reserveer eerst een upload. filename moet eindigen op .xlsx of .csv en na het verwijderen van omringende spaties 1 tot 255 tekens bevatten. bytes is de exacte bestandsgrootte in bytes, van 1 tot 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}'

Het antwoord 201 bevat upload_id, een ondertekende PUT-url, expires_at (milliseconden sinds de Unix-epoch), max_bytes en request_id. De reservering verloopt na 15 minuten. Verstuur het ruwe bestand met PUT naar de ontvangen URL en dien daarna de upload-ID in:

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"}'

De directe PUT gebruikt het antwoordcontract van de opslagdienst. NinjaBuy valideert de geüploade bytes wanneer je de conversie indient. Onbekende upload-ID's en die van andere accounts geven 404. Het opgeslagen object moet overeenkomen met het opgegeven aantal bytes; een object dat groter is dan opgegeven of de bovengrens overschrijdt, geeft 413 upload-too-large, en een kleiner (afgekapt) object geeft 422 invalid-workbook met uitleg over het afwijkende aantal bytes. Deze controles vinden plaats vóór het downloaden en gelden ook als de bytes na de metadatacontrole veranderen. Geweigerde ruwe uploads worden verwijderd; geaccepteerde ruwe uploads worden verwijderd zodra hun gevalideerde momentopname is vastgelegd.

Stuur precies één bron: url of upload_id. Beide accepteren optioneel campaign en label; async is niet nodig. Beide POST-routes accepteren Idempotency-Key en gebruiken elk één plek in het gedeelde venster van 30 oproepen per minuut. Onderliggende linkconversies gebruiken geen extra plekken.

Opdracht en downloadSectielink kopiëren

Een spreadsheetindiening geeft 202 met Location: /api/v1/jobs/JOB_ID, Retry-After: 5 en deze body:

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

Vraag Opdrachten op met het token van hetzelfde account tot done of failed en respecteer poll_after_seconds. Een voltooid job.result bevat kind: "sheet_conversion", counts en een ondertekende download_url die 15 minuten geldig is. Vraag opnieuw op voor een nieuwe downloadhandtekening. Een mislukte opdracht bevat error en geen gedeeltelijke download.

Voor een Google Sheet kan job.result ook copy_url bevatten: een link (alleen bekijken) naar een exacte Google Sheets-kopie met jouw links op hun plek; iedereen met de link kan met Bestand → Een kopie maken een eigen kopie bewaren. copy_notes vermeldt wat een lezer van die kopie moet weten, bijvoorbeeld dat afbeeldingen die met =IMAGE() zijn gemaakt in de eigen kopie één klik op Toegang toestaan nodig hebben. download_url levert nog steeds het XLSX-bestand. copy_counts geeft dezelfde tellingen voor de kopie; lukt het XLSX-bestand niet, dan houdt het resultaat copy_url, heeft het geen download_url en vermeldt copy_notes waarom. download_notes vermeldt regel voor regel wat het XLSX-bestand van de sheet niet kan bevatten, zoals grafieken of een tweede link in een cel.

Momentopnamen en resultaatbestanden worden zeven dagen bewaard nadat de opdracht is voltooid of mislukt. Na het opruimen blijft de opdracht opvraagbaar met de status en tellingen, en wordt job.result.download_url weggelaten. Gedeelde momentopnamen blijven bewaard zolang een andere opdracht ze nog nodig heeft. Achtergelaten ruwe uploads worden één uur na het verlopen van de uploadreservering verwijderd; bij een gevalideerde upload waarvoor nooit een opdracht start, wordt de momentopname zeven dagen na het verlopen van de reservering verwijderd. Het opruimen gebeurt elk uur.

De dekking voldoet aan links_found = converted + sum(left_by_host) + unresolved. Sociale links, Google Sheets-links, navigatie binnen dezelfde werkmap en bestaande NinjaBuy-links blijven ongewijzigd. Elke conversiekandidaat moet een antwoord krijgen voordat de uitvoer wordt geschreven; ontbrekende antwoorden laten de opdracht mislukken.

Behoud van de werkmapSectielink kopiëren

De uitvoer behoudt stijlen, samengevoegde cellen, rij- en kolomgroottes en afbeeldingen zoals weergegeven in het ingelezen raster. Rich-textfragmenten blijven behouden in cellen zonder celhyperlink; gekoppelde cellen gebruiken één tekstlabel en hyperlink. De werkmap wordt opnieuw geserialiseerd: grafieken, macro's en andere functies buiten dit raster blijven niet behouden.

XLSX ondersteunt één hyperlink per cel. De conversie vervangt links op dezelfde plek in plaats van een tweede link ernaast toe te voegen. Een cel met twee of meer verschillende linkdoelen zonder afbeelding houdt het eerste als hyperlink en zet de overige in de notitie van de cel, zodat er geen doel verloren gaat.

LimietenSectielink kopiëren

Overschrijding van een parser- of schrijflimiet leidt expliciet tot een fout. Zie Fouten voor invalid-workbook, upload-expired en upload-too-large.