Admin API: de backend-koppeling van Shopware 6 voor ERP en automatisering

De Admin API is de koppeling waarmee Shopware 6 van buitenaf wordt beheerd: producten, voorraden, bestellingen, klanten en instellingen kunt u ermee lezen en schrijven. Het is de standaardweg om ERP, PIM, CRM en middleware aan de webshop te koppelen.

Alles wat u in de administratie van Shopware 6 kunt doen, kunt u ook via de Admin API uitvoeren: producten aanmaken, voorraden wijzigen, bestellingen lezen, klanten bijwerken, statuswijzigingen starten. De administratie zelf is slechts een client van deze API; elke actie in de backend is een API-aanroep.

Juist daarom is de Admin API de standaardweg voor koppelingen met externe systemen. ERP, PIM, voorraadbeheer, CRM en middleware communiceren via deze koppeling met Shopware, meestal op de achtergrond en zonder interactie van gebruikers. De API is REST-gebaseerd, levert JSON en bereikt alle entiteiten van de Data Abstraction Layer.

Shopware 6 biedt twee koppelingen die vaak met elkaar worden verward:

• Admin API: voor backendprocessen en systeemkoppelingen. Volledige toegang binnen de toegekende rechten, authenticatie via OAuth 2.0, endpoints onder /api/.
• Store API: voor klantgerichte frontends zoals Storefront, apps of headless webshops. Werkt in de context van een Sales Channel en een klant, authenticatie via sw-access-key, endpoints onder /store-api/.

Vuistregel: wat een medewerker in de administratie doet, hoort bij de Admin API. Wat een klant in de webshop doet, hoort bij de Store API. De verschillen in detail legt ons artikel over GraphQL en REST API’s in Shopware uit.

De toegang verloopt via OAuth 2.0. Voor systeemkoppelingen maakt u onder Instellingen → Systeem → Integraties een integratie met een eigen rol aan en ontvangt u een toegangssleutel-ID en een beveiligingssleutel. Daarmee vraagt u een token aan:

POST /api/oauth/token
{
  "grant_type": "client_credentials",
  "client_id": "IHRE_ZUGRIFFSSCHLUESSEL_ID",
  "client_secret": "IHR_SICHERHEITSSCHLUESSEL"
}

Het token is tien minuten geldig en wordt meegestuurd als Authorization: Bearer-header. Voor tools die namens een gebruiker werken, is er daarnaast het granttype password met refresh token. Geef per integratie alleen de rechten die het proces nodig heeft; met ACL-rollen kunt u de toegang beperken tot afzonderlijke entiteiten en bewerkingen. Achtergronden over het protocol vindt u in het woordenboekitem OAuth.

• Entiteiten lezen en schrijven: GET /api/product, POST /api/product, PATCH /api/product/{id}, DELETE /api/product/{id}, op dezelfde wijze voor bestellingen, klanten, categorieën, media en alle andere entiteiten.
• Zoeken met criteria: POST /api/search/product met filters, sortering, paginering, aggregaties en associaties. Zo laadt u bijvoorbeeld alle bestellingen van een dag inclusief orderregels in één aanroep.
• Sync API: POST /api/_action/sync schrijft veel records van meerdere entiteiten in één verzoek. De juiste weg voor voorraad- en prijsafstemming met duizenden artikelen.
• Acties: statuswijzigingen via State Machine (/api/_action/order/{id}/state/…), documenten genereren, e-mails versturen, indexering starten.
• Versiebeheer en metadata: /api/_info/ levert de versie, beschikbare entiteiten en het OpenAPI-schema; de Swagger-interface onder /api/_info/swagger.html documenteert alle endpoints.

In een typische ERP-integratie verzorgt de Admin API deze gegevensstromen:

• Artikelen en prijzen: het ERP is leidend, Shopware ontvangt stamgegevens, varianten en prijzen via de Sync API.
• Voorraden: magazijnvoorraden worden met korte tussenpozen of gebeurtenisgestuurd bijgewerkt, zodat de beschikbaarheid in de webshop klopt.
• Bestellingen: het ERP haalt nieuwe bestellingen op via een zoekopdracht met het criterium “bestelstatus open en nog niet geëxporteerd” en markeert ze daarna, bijvoorbeeld via een extra veld.
• Status en trackingnummers: verzend- en betalingsstatus worden via een State Machine-actie teruggeschreven, trackingnummers worden aan de levering gekoppeld.

In plaats van cyclisch op te vragen, kunt u zich door Shopware laten informeren: webhooks melden nieuwe bestellingen of gewijzigde producten, en de integratie laadt dan alleen wat is gewijzigd. Welke systemen u zo kunt koppelen, laat ons overzicht van ERP- en CRM-integraties zien, een concreet voorbeeld is de handleiding over Xentral en Shopware 6.

• Sync API voor bulkdata: afzonderlijke aanroepen per artikel zijn bij grote catalogi te traag; bundel schrijfacties in pakketten van enkele honderden records.
• Alleen wijzigingen overdragen: met updatedAt-filters of webhooks draagt u alleen delta’s over in plaats van de volledige voorraad.
• Idempotent werken: gebruik vaste ID’s (UUID’s) uit uw leidende systeem, zodat herhaalde aanroepen geen dubbele records veroorzaken.
• Fouten afhandelen: de Sync API meldt fouten per record; registreer mislukte items en herhaal ze gericht.
• Indexering in acht nemen: na grote imports draaien indexers via de Message Queue; de worker moet actief zijn, anders verschijnen gegevens met vertraging in de webshop.
• Rechten en secrets: een eigen integratie per systeem, minimale rol, sleutels in de secret store, regelmatige rotatie.

• 401 Unauthorized: token verlopen of onjuiste toegangsgegevens. Token vernieuwen, integratie controleren.
• 403 Forbidden: de rol van de integratie heeft het recht voor deze entiteit of bewerking niet.
• 400 bij schrijfacties: verplichte velden ontbreken of gegevenstypen kloppen niet; de foutmelding noemt veld en pad.
• Gegevens verschijnen niet in de webshop: indexer of cache. Controleer de Message Queue-worker en leeg de cache.
• Trage imports: afzonderlijke aanroepen in plaats van de Sync API of te grote pakketten; met de header indexing-behavior: use-queue-indexing kunt u de indexering naar de wachtrij verplaatsen.

De Admin API is de ruggengraat van elke Shopware-integratie. Wie de logica ervan begrijpt, met OAuth 2.0, zoeken met criteria, Sync API en State Machine, kan ERP, PIM en CRM betrouwbaar koppelen. Voor individuele koppelingen en plugins die de Admin API met eigen endpoints uitbreiden, ondersteunen wij u met Shopware-pluginontwikkeling.