API og webhooks — kom i gang NO

Velg REST, tRPC eller MCP, avgrens tilgangen og finn den gjeldende API-kontrakten.

Kaduno tilbyr ulike grensesnitt for systemintegrasjoner, innloggede brukere og AI-assistenter. Start med riktig grensesnitt og riktig butikk.

Du skalBrukTilgang
Koble ERP, lager eller en annen tjeneste til butikkdataREST under /api/v1Butikkavgrenset REST API-nøkkel med nødvendige rettigheter
Bygge kode som opptrer som innlogget ansatt eller kundetRPCBrukerens sesjon og butikkontekst
La ChatGPT, Claude eller en annen assistent arbeide i KadunoMCPOAuth eller en egnet agentnøkkel
Reagere på at noe skjer i butikkenWebhooksEt abonnement for butikken og en mottaker hos dere

REST-nøkler virker ikke som tRPC-sesjoner. Agentnøkler har egne roller og scopes. Se AI-agenter for MCP-oppsett og bekreftelser.

Opprett en REST-tilkobling

  1. Velg butikk i admin og åpne Integrasjoner → Offentlig REST API.
  2. Opprett en nøkkel for integrasjonen. Velg bare rettighetene den trenger, for eksempel catalog:read for lesing av katalogen.
  3. Kopier nøkkelen når den opprettes. Oppbevar den i serverens hemmelighetslager, aldri i nettleserkode, et offentlig repository eller en URL.
  4. Send nøkkelen som Authorization: Bearer <REST_API_KEY>.
  5. Start med et lesekall fra butikkens API-referanse. Kontroller butikk, data og feilhåndtering før dere tar i bruk skriveoperasjoner.

Temarettigheter: lesing er ikke publisering

REST-temaendepunktene bruker følgende rettigheter. Disse er skilt fra MCP-omfangene og fra katalogrettighetene:

RettighetTilgangViktig grense
themes:readLese butikkidentitet, liste/hente temaer, validere filer uten lagring og lage forhåndsvisningslenkeGir ikke rett til å endre eller aktivere tema
themes:writeSkrive temafiler, aktivere, deaktivere og slette temaer; godtas også for temalesingEn oppdatering av et aktivt tema kan gå live med en gang

Et leseomfang kan lage en forhåndsvisningslenke, men gjør ikke lenken offentlig beregnet. Del den bare med dem som skal gjennomgå utkastet. API-nøkkelen skal aldri følge med lenken.

Ved kildekontroll 13. november 2026 var temarettighetene registrert i API-et og beskrevet på temaendepunktene, men manglet i referansens korte «Permission Scopes»- tabell. Tabellen er derfor ikke en uttømmende liste. Kontroller det konkrete endepunktet og nøkkelens rettigheter; ikke gi * for å omgå et dokumentasjonsavvik.

Se temautkast og forhåndsvisning for forskjellene mellom MCP, CLI, REST og Git før dere gir skrivetilgang.

Første lesekall: bekreft testbutikken

Denne øvelsen bruker temaendepunktene fordi de kan bekrefte butikkidentiteten uten å lese kundedata. Den krever en avtalt testbutikk, en REST-nøkkel med bare themes:read og butikkens bekreftede API-adresse. Den er ikke en øvelse i å publisere et tema. Eksemplene er kontrollert mot rutekoden, ikke kjørt med deres konto; verifiser resultatet før neste steg.

  1. Få butikkens ID eller slug bekreftet i admin og noter forventet butikknavn.
  2. Last nøkkelen inn som KADUNO_API_KEY fra hemmelighetslageret. Sett KADUNO_API_URL til API-adressen uten avsluttende skråstrek. Ikke legg nøkkelverdien i en kommando som lagres i shell-historikken.
  3. Les butikkidentiteten:
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${KADUNO_API_KEY}" \
  "${KADUNO_API_URL}/api/v1/store"

Et vellykket svar har feltene id, slug, name og storefrontUrl. Sammenlign ID/slug med testbutikken. Stopp hvis butikken ikke stemmer, selv om svaret er 200. Ikke publiser et faktisk svar med interne butikkopplysninger i en supportsak.

  1. Les temaoversikten, uten å endre noen filer:
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${KADUNO_API_KEY}" \
  "${KADUNO_API_URL}/api/v1/themes"

Svaret inneholder themes. En tom liste er ikke en autentiseringsfeil. Noter hvilket tema som er aktivt dersom listen inneholder et; ikke bruk aktiv slug som mål for en senere skriveøvelse. Denne listen har ikke samme paginering som produktlisten. Bruk endepunktets skjema, ikke et generelt listeeksempel.

  1. Test avvisning i testmiljøet: et kall til /api/v1/themes uten nøkkel skal avvises med 401. En separat nøkkel som bare har catalog:read, ikke * eller temarettigheter, skal ikke få lese temaene (403). Dette er bare lesekall; ikke bruk aktivering eller sletting som test av tilgang.
  2. Hvis dere opprettet engangsnøkler for øvelsen, tilbakekall dem i admin. unset KADUNO_API_KEY rydder bare shell-variabelen og tilbakekaller ikke nøkkelen.

Ikke skriv nøkkelen, full Authorization-header eller følsomme svar til logger. Hvis en nøkkel blir eksponert, tilbakekall den før dere fortsetter.

Referanse og kontrakt

  • API-referansen viser endepunktene.
  • OpenAPI JSON kan importeres i API-verktøy.
  • Integrasjoner → API-referanse i admin viser referansen i butikkens kontekst.

Uten butikkfilter viser den offentlige referansen hele plattformen. Det betyr ikke at alle endepunktene er tilgjengelige for butikkens moduler eller nøkkel. Bruk skjemaet for det konkrete endepunktet som kilde for felter, obligatoriske verdier, svar og paginering. Ikke anta at alle lister har samme sideformat.

/api/v1 er REST-grensesnittets versjonerte sti. Ved oppdatering av en integrasjon: sammenlign OpenAPI-kontrakten med det dere bruker, og test relevante kall på eksempeldata. MCP har sin egen verktøykontrakt; les den gjennom kshop_platform med handlingen contract i den tilkoblede assistenten.

Feil og nye forsøk

Ved 401 kontrollerer dere autentiseringen. Ved 403 kontrollerer dere rettigheter og aktive moduler. En 404 kan også skyldes at posten ikke er tilgjengelig i valgt butikk.

REST-svar kan ha X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Ved 429 skal klienten respektere Retry-After. Ikke gjenta en skrivehandling automatisk etter et tidsavbrudd: kontroller om den første forespørselen allerede ble utført. Bruk endepunktets mekanisme for idempotens når den finnes.

Fra lesing til hendelser

Et webhook-abonnement trenger webhooks:manage. Velg bare hendelsene integrasjonen bruker, og sett en hemmelig signatur ved opprettelse via REST. Uten en signerings- hemmelighet signeres ikke leveringen.

Fortsett med webhook-mottakeren for signaturverifisering, gjentatte leveringer og feiloppfølging.