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ält | Regel |
|---|---|
contractVersion | Obligatoriskt: 1.0. |
source | Obligatoriskt: nyckelns källa. |
idempotencyKey | Obligatoriskt, högst 200 tecken. |
description | Valfritt, högst 500 tecken. |
metadata | Valfritt JSON-objekt. |
records | Från 1 till 50 000 poster. |
kind | Obligatoriskt; supplier-company, retailer-company, installer-company och retailer-stock kan tillämpas. Andra giltiga typer stannar i mellanlagringen. |
naturalKey | Obligatoriskt för dessa fyra typer; högst 512 tecken. |
payload | Obligatoriskt JSON-objekt; högst 256 KB. |
provenance | Valfria 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äns | Värde |
|---|---|
| Anropets kropp | 64 MB |
| Poster per batch | 50 000 |
| Innehåll per post | 256 KB |
| Anrop per nyckel | 30 per minut |
| Batcher per UTC-dygn | Normalt 200; högst 10 000 vid utfärdandet |
| Poster per UTC-dygn | Normalt 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
| Status | Nästa steg |
|---|---|
| 400 | Rätta fälten i errors. |
| 401 | Be operatören utfärda eller byta nyckel. |
| 403 | Använd rätt källa och en api:intake-nyckel. |
| 404 | Läs batchen med nyckeln som skickade den. |
| 409 | Välj en ny idempotencyKey; en annan nyckel äger värdet. |
| 413 | Dela upp batchen i mindre anrop. |
| 429 | Vä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.