Publikt intake-API

APIHjälp och dokumentation

Skicka data till mellanlagring med en intake-nyckel. Detta API publicerar inte direkt och använder inte kontots läs- eller skrivnyckel.

1. Skaffa en intake-nyckel

En Stockisto-operatör utfärdar en nyckel med api:intake, bunden till ditt konto och en källa: scraper, delegated eller crowd. Skicka den i X-API-Key. Förvara den i serverns hemlighetslager; den visas bara en gång. Nycklar med api:read eller api:write kan inte använda intake. En intake-nyckel kan inte läsa kontots API.

Både kuvertets source och posternas eventuella provenance.source måste stämma med nyckelns källa. Utgångna, återkallade och okända nycklar ger 401.

2. Skicka en batch

Byt ut platshållarna och använd nyckelns källa. Anropet skriver till mellanlagringen; kör det bara med en nyckel som utfärdats för din källa.

curl -X POST https://api.test.stockisto.com/api/public/v1/intake/batches \
  -H "X-API-Key: <YOUR_INTAKE_KEY>" \
  -H "Content-Type: application/json" \
  --data '{"contractVersion":"1.0","source":"scraper","idempotencyKey":"<UNIQUE_BATCH_KEY>","records":[{"kind":"retailer-company","naturalKey":"<UNIQUE_RETAILER_KEY>","payload":{"name":"<RETAILER_NAME>"}}]}'

En ny batch ger 202 med id, status och en statuslänk i Location. Samma idempotencyKey med samma nyckel ger 200 och den befintliga batchen med duplicate: true. Det förbrukar ingen ytterligare kvot, även när dagskvoten är slut. Värdet är unikt inom kontot; en kollision med en annan nyckel ger 409.

FältRegel
contractVersionObligatoriskt: 1.0.
sourceObligatoriskt: nyckelns källa.
idempotencyKeyObligatoriskt, högst 200 tecken.
descriptionValfritt, högst 500 tecken.
metadataValfritt JSON-objekt.
recordsFrån 1 till 50 000 poster.
kindObligatoriskt; supplier-company, retailer-company, installer-company och retailer-stock kan tillämpas. Andra giltiga typer stannar i mellanlagringen.
naturalKeyObligatoriskt för dessa fyra typer; högst 512 tecken.
payloadObligatoriskt JSON-objekt; högst 256 KB.
provenanceValfria source, fetchedAt (UTC, inte i framtiden), confidence (0 till 1) och sourceRef (högst 1024 tecken).

Läs validationErrors för avvisade poster. Giltiga poster går vidare. Ett ogiltigt kuvert eller en batch utan giltiga poster avvisas.

3. Läs status och granskning

GET /api/public/v1/intake/batches listar bara batcher från samma nyckel. Läs en batch med GET /api/public/v1/intake/batches/<BATCH_ID>. En annan nyckels batch ger 404, även inom samma konto.

Statusarna är received, validated, staged, in_review, applied, partially_applied och rejected. Källbatcher stannar vid in_review om en operatör inte har godkänt automatisk tillämpning för källan. Ovanligt stora borttagningar kräver alltid granskning. Kontrollera statusen; mottaget betyder inte publicerat.

En operatör kan registrera en HTTPS-adress för återanrop på nyckeln. Slutstatusarna applied, partially_applied och rejected utlöser en signerad leverans av import.completed.

4. Gränser

GränsVärde
Anropets kropp64 MB
Poster per batch50 000
Innehåll per post256 KB
Anrop per nyckel30 per minut
Batcher per UTC-dygnNormalt 200; högst 10 000 vid utfärdandet
Poster per UTC-dygnNormalt 500 000; högst 10 000 000 vid utfärdandet

När dagskvoten är slut får du 429, error: "intake_quota_exceeded" och ett quota-objekt med dailyBatchLimit, batchesToday, dailyRecordLimit, recordsToday och resetAt. Följ Retry-After och vänta till återställningen i stället för att skicka om.

5. Åtgärda ett avslag

StatusNästa steg
400Rätta fälten i errors.
401Be operatören utfärda eller byta nyckel.
403Använd rätt källa och en api:intake-nyckel.
404Läs batchen med nyckeln som skickade den.
409Välj en ny idempotencyKey; en annan nyckel äger värdet.
413Dela upp batchen i mindre anrop.
429Vänta enligt Retry-After eller till resetAt.

För kontots vanliga importer använder du Public imports API.

För återförsäljares datafiler, läs Återförsäljarflöden.