Utviklere

API-oversikt

Customer API-et: basis-URL, bearer-autentisering, omfang, sandkasse, versjonering, paginering, idempotens, ratebegrensning og feil.

Basis-URL og referanse

https://api.itemra.io

Den interaktive referansen bor på api.itemra.io/scalar/v1, og den styrte OpenAPI-kontrakten på api.itemra.io/openapi/v1.json. Alle ruter er versjonert under /v1; kontrakten er endringskontrollert, brytende endringer krever ny versjon, og utfasinger annonseres med standard utfasings-headere i god tid.

Autentisering

Forespørsler autentiserer med en bearer-nøkkel fra Innstillinger → API-nøkler:

curl -sS "https://api.itemra.io/v1/items?limit=10&sort=name" \
  -H "Authorization: Bearer $ITEMRA_API_KEY"

En nøkkel kan bare kalle endepunkter omfanget tillater (items:read, stock:write, …); tenantens plan-funksjoner og nøkkelsikkerhet (IP-lister, utløp) gjelder i tillegg. Dev-miljønøkler (itemra_dev_…) opererer mot et isolert sandkassedatasett, så integrasjonsutvikling aldri rører det levende lageret.

Paginering, filtrering, sortering

Samlinger returnerer data pluss markørmetadata under page. Send page.nextCursor tilbake som cursor for neste side — markører er ugjennomsiktige og tenant-bundne; konstruer eller dekod dem aldri. Filtrerbare felt og sorteringsnøkler dokumenteres per endepunkt i referansen.

Idempotens

Hvert muterende endepunkt som dokumenterer det krever en Idempotency-Key-header: en stabil unik verdi per logisk operasjon. Prøv nøyaktig samme kropp med samme nøkkel på nytt etter et tvetydig avbrudd; samme nøkkel med annen kropp avvises. Det er dette som gjør nye forsøk trygge.

Ratebegrensning

Standard: 1 200 forespørsler per minutt per nøkkel, med strengere innsendingsgrense (20/min) på tunge endepunkter som opprettelse av importjobber. Ved 429, respekter Retry-After. Overstyringer per nøkkel kan konfigureres med nøkkelen.

Feil

Feil er RFC 7807-problemdokumenter med stabil maskinkode code og en traceId:

{
  "status": 400,
  "detail": "Unsupported sort field.",
  "code": "validation.failed",
  "traceId": "f00d4b9b4b6d…",
  "params": { "field": "sort" }
}

Forgren på code, ikke på detail-teksten, og ta vare på traceId ved kontakt med support.

Fortsett med hurtigstarten, ressursturen, hendelsesstrømmen og webhook-verifisering.