Admin-API: Backend-interfacet i Shopware 6 til ERP og automatisering

Admin-API’et er det interface, som Shopware 6 administreres udefra med: produkter, lagerbeholdninger, ordrer, kunder og indstillinger kan læses og skrives. Det er standardvejen til at koble ERP, PIM, CRM og middleware på shoppen, også for webshops i Danmark, der vil automatisere driften.

Alt, hvad du kan gøre i administrationen af Shopware 6, kan du også gøre via Admin-API’et: oprette produkter, ændre lagerbeholdninger, læse ordrer, opdatere kunder og udløse statusskift. Selve administrationen er blot en klient til dette API; hver handling i backend er et API-kald.

Netop derfor er Admin-API’et standardvejen til integrationer med tredjepartssystemer. ERP, PIM, lagerstyring, CRM og middleware kommunikerer med Shopware via dette interface, som regel i baggrunden og uden brugerinteraktion. Det er REST-baseret, returnerer JSON og giver adgang til alle entiteter i Data Abstraction Layer.

Shopware 6 stiller to interfaces til rådighed, som ofte forveksles:

• Admin-API: til backend-processer og systemintegrationer. Fuld adgang inden for de tildelte rettigheder, godkendelse via OAuth 2.0, endpoints under /api/.
• Store-API: til kundevendte frontends som storefront, apps eller headless-shops. Arbejder i konteksten af en salgskanal og en kunde, godkendelse via sw-access-key, endpoints under /store-api/.

Tommelfingerregel: Det, en medarbejder gør i administrationen, hører til Admin-API’et. Det, en kunde gør i shoppen, hører til Store-API’et. Forskellene i detaljer forklarer vi i vores artikel om GraphQL og REST-API’er i Shopware.

Adgangen sker via OAuth 2.0. Til systemintegrationer opretter du under Indstillinger → System → Integrationer en integration med sin egen rolle og får et adgangsnøgle-ID og en sikkerhedsnøgle. Med dem anmoder du om et token:

POST /api/oauth/token
{
"grant_type": "client_credentials",
"client_id": "DIT_ADGANGSNOEGLE_ID",
"client_secret": "DIN_SIKKERHEDSNOEGLE"
}

Tokenet er gyldigt i ti minutter og sendes med som Authorization: Bearer-header. Til værktøjer, der arbejder på vegne af en bruger, findes desuden grant-typen password med refresh-token. Giv hver integration kun de rettigheder, processen har brug for; med ACL-roller kan adgangen begrænses helt ned til enkelte entiteter og operationer. Baggrunden for protokollen finder du i opslaget om OAuth.

• Læse og skrive entiteter: GET /api/product, POST /api/product, PATCH /api/product/{id}, DELETE /api/product/{id}, tilsvarende for ordrer, kunder, kategorier, medier og alle øvrige entiteter.
• Søgning med kriterier: POST /api/search/product med filtre, sortering, paginering, aggregeringer og associationer. Sådan henter du for eksempel alle ordrer fra en dag inklusive ordrelinjer i ét kald.
• Sync-API: POST /api/_action/sync skriver mange datasæt fra flere entiteter i én forespørgsel. Den rigtige vej til lager- og prisopdateringer med tusindvis af varer.
• Handlinger: statusskift via state machine (/api/_action/order/{id}/state/…), generering af dokumenter, afsendelse af mails, start af indeksering.
• Versionering og metadata: /api/_info/ returnerer version, tilgængelige entiteter og OpenAPI-skemaet; Swagger-brugerfladen under /api/_info/swagger.html dokumenterer alle endpoints.

I en typisk ERP-integration står Admin-API’et for disse dataflows:

• Varer og priser: ERP-systemet er master, og Shopware modtager stamdata, varianter og priser via Sync-API’et.
• Lagerbeholdning: Lagerbeholdninger opdateres med korte intervaller eller hændelsesstyret, så tilgængeligheden i shoppen er korrekt.
• Ordrer: ERP-systemet henter nye ordrer via søgning med kriteriet „ordrestatus åben og endnu ikke eksporteret” og markerer dem derefter, for eksempel via et ekstra felt.
• Status og trackingnumre: Forsendelses- og betalingsstatus skrives tilbage via state machine-handlinger, og trackingnumre fra fx PostNord, GLS eller DAO knyttes til leverancen.

I stedet for at spørge cyklisk kan du lade Shopware give besked: webhooks melder nye ordrer eller ændrede produkter, og integrationen henter så kun det, der er ændret. Hvilke systemer der kan kobles på denne måde, viser vores oversigt over ERP- og CRM-integrationer, og et konkret eksempel er vejledningen til Xentral og Shopware 6.

• Sync-API til massedata: Enkeltkald pr. vare er for langsomme ved store kataloger; saml skriveoperationer i pakker på nogle hundrede datasæt.
• Overfør kun ændringer: Med updatedAt-filtre eller webhooks overfører du kun deltaer i stedet for hele beholdningen.
• Arbejd idempotent: Brug faste ID’er (UUID’er) fra dit mastersystem, så gentagne kald ikke skaber dubletter.
• Håndter fejl: Sync-API’et melder fejl pr. datasæt; log og gentag de fejlede poster målrettet.
• Hold øje med indekseringen: Efter store importer kører indeksere via message queue; workeren skal være aktiv, ellers vises data forsinket i shoppen.
• Rettigheder og secrets: egen integration pr. system, minimal rolle, nøgler i en secret store og regelmæssig rotation.

• 401 Unauthorized: Tokenet er udløbet, eller adgangsoplysningerne er forkerte. Forny tokenet, og kontrollér integrationen.
• 403 Forbidden: Integrationens rolle har ikke rettighed til denne entitet eller operation.
• 400 ved skriveoperationer: Obligatoriske felter mangler, eller datatyperne passer ikke; fejlmeddelelsen angiver felt og sti.
• Data vises ikke i shoppen: indeksering eller cache. Kontrollér message queue-workeren, og ryd cachen.
• Langsomme importer: enkeltkald i stedet for Sync-API eller for store pakker; med headeren indexing-behavior: use-queue-indexing kan indekseringen flyttes til køen.

Admin-API’et er rygraden i enhver Shopware-integration. Den, der forstår logikken med OAuth 2.0, søgning med kriterier, Sync-API og state machine, kan koble ERP, PIM og CRM pålideligt på. Vi hjælper webshops i Danmark med individuelle integrationer og plugins, der udvider Admin-API’et med egne endpoints, gennem Shopware-pluginudvikling.