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 skal | Bruk | Tilgang |
|---|---|---|
| Koble ERP, lager eller en annen tjeneste til butikkdata | REST under /api/v1 | Butikkavgrenset REST API-nøkkel med nødvendige rettigheter |
| Bygge kode som opptrer som innlogget ansatt eller kunde | tRPC | Brukerens sesjon og butikkontekst |
| La ChatGPT, Claude eller en annen assistent arbeide i Kaduno | MCP | OAuth eller en egnet agentnøkkel |
| Reagere på at noe skjer i butikken | Webhooks | Et 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
- Velg butikk i admin og åpne Integrasjoner → Offentlig REST API.
- Opprett en nøkkel for integrasjonen. Velg bare rettighetene den trenger,
for eksempel
catalog:readfor lesing av katalogen. - Kopier nøkkelen når den opprettes. Oppbevar den i serverens hemmelighetslager, aldri i nettleserkode, et offentlig repository eller en URL.
- Send nøkkelen som
Authorization: Bearer <REST_API_KEY>. - 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:
| Rettighet | Tilgang | Viktig grense |
|---|---|---|
themes:read | Lese butikkidentitet, liste/hente temaer, validere filer uten lagring og lage forhåndsvisningslenke | Gir ikke rett til å endre eller aktivere tema |
themes:write | Skrive temafiler, aktivere, deaktivere og slette temaer; godtas også for temalesing | En 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.
- Få butikkens ID eller slug bekreftet i admin og noter forventet butikknavn.
- Last nøkkelen inn som
KADUNO_API_KEYfra hemmelighetslageret. SettKADUNO_API_URLtil API-adressen uten avsluttende skråstrek. Ikke legg nøkkelverdien i en kommando som lagres i shell-historikken. - 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.
- 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.
- Test avvisning i testmiljøet: et kall til
/api/v1/themesuten nøkkel skal avvises med401. En separat nøkkel som bare harcatalog:read, ikke*eller temarettigheter, skal ikke få lese temaene (403). Dette er bare lesekall; ikke bruk aktivering eller sletting som test av tilgang. - Hvis dere opprettet engangsnøkler for øvelsen, tilbakekall dem i admin.
unset KADUNO_API_KEYrydder 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.