> For the complete documentation index, see [llms.txt](https://docs.spiroq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spiroq.com/de/operator-api/operator-api.md).

# Betreiber-API

Diese Dokumentation richtet sich an Entwickler, die externe Systeme (E-Shop, ERP / WMS, MCP) mit dem System Spiroq zur Verwaltung von Verkaufsautomaten integrieren möchten. Senden Sie Requests **vom Server Ihres ERP / WMS**. Das Token gehört nicht in den Browser, in eine mobile Anwendung und nicht in die Anwendung auf dem Automaten.

Die Betreiber-API ist für Benutzer mit dem Betreibertarif **Enterprise** vollständig verfügbar.

***

## Voraussetzungen

* Konto im [Admin Hub](https://app.spiroq.com) mit dem Tarif **Enterprise**
* mindestens ein Automat, der Ihrem Konto zugewiesen ist
* Möglichkeit, das API-Token sicher in den Secrets auf Ihrem Server zu speichern

Der Schlüssel gilt für **Ihre gesamte Automatenflotte**. Einen fremden Automaten oder ein fremdes Produkt gibt die API als `404` zurück.

***

## Implementierungsleitfaden

Gehen Sie die Schritte in dieser Reihenfolge durch. Jeder Schritt verweist auf die Seite mit Parametern und Beispielen.

| Schritt | Was Sie tun                                                                                  | Details                                                                              |
| ------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 1       | Sie erstellen einen API-Schlüssel und prüfen den ersten `GET`                                | [Verbindung und API-Schlüssel](/de/operator-api/operator-api/pripojeni.md)           |
| 2       | Sie setzen Header, Limits und die Fehlerbehandlung                                           | [Authentifizierung, Limits und Fehler](/de/operator-api/operator-api/autentizace.md) |
| 3       | Sie laden Kategorien und Produkte und legen den Katalog bei Bedarf an oder aktualisieren ihn | [Produktkatalog](/de/operator-api/operator-api/katalog.md)                           |
| 4       | Sie laden Automaten und aktuelle Fächer (`stock`, zugewiesenes Produkt)                      | [Automaten, Fächer und Bestand](/de/operator-api/operator-api/stroje-a-zasoby.md)    |
| 5       | Sie legen fest, welches Produkt im Fach liegt                                                | [Fachlayout](/de/operator-api/operator-api/layout.md)                                |
| 6       | Sie lagern ein / aus (der Automat muss online sein)                                          | [Automaten, Fächer und Bestand](/de/operator-api/operator-api/stroje-a-zasoby.md)    |
| 7       | Optional bereiten Sie einen Befüllungsplan für den Techniker am Automaten vor                | [Befüllungspläne](/de/operator-api/operator-api/restock.md)                          |
| 8       | Bei Schreibzugriffen auf den Automaten behandeln Sie `202` und `Idempotency-Key`             | [Jobs und Idempotenz](/de/operator-api/operator-api/joby.md)                         |

**Den Bestand in den Fächern schreibt der Automat.** Einlagerung und Auslagerung erfordern daher einen Online-Automaten und warten auf die Bestätigung vom Automaten — Einheiten werden nicht „nur in der Cloud“ gespeichert.

***

## Was die API abdeckt

| Unterstützt                                                      | Nicht abgedeckt                                            |
| ---------------------------------------------------------------- | ---------------------------------------------------------- |
| Liste der Automaten und Fachstatus                               | Anlegen von Kategorien (legen Sie diese im Admin Hub an)   |
| Einlagerung und Auslagerung an einem **Online**-Automaten        | Bestellungen, Reservierungen, Ausgabe an den Kunden        |
| Produktwechsel im Fach (einschließlich Restverkauf)              | Allergene und Preisgruppen beim Produkt                    |
| Anlegen und Bearbeiten eines Produkts (Bild als öffentliche URL) | Hochladen einer Bilddatei                                  |
| Befüllungsplan (Kommissionierliste)                              | Paginierung von Listen (max. 100 Einträge pro `GET`-Liste) |

***

## Übersicht der Endpunkte

Alle Pfade liegen unter `{BASE}/v1`. Schreibzugriffe (`POST` / `PUT` / `PATCH`) erfordern den Header `Idempotency-Key`.

| Method | Pfad                           | Beschreibung                                   |
| ------ | ------------------------------ | ---------------------------------------------- |
| GET    | `/machines`                    | Liste der Automaten                            |
| GET    | `/machines/:ref`               | Automatendetails                               |
| GET    | `/machines/:ref/slots`         | Fächer, Produkte, Anzahl der Einheiten         |
| POST   | `/machines/:ref/stock/fill`    | Einlagerung                                    |
| POST   | `/machines/:ref/stock/clear`   | Auslagerung                                    |
| PUT    | `/machines/:ref/layout`        | Zuweisung von Produkten zu Fächern             |
| POST   | `/machines/:ref/restock-plans` | Befüllungsplan                                 |
| GET    | `/products`                    | Katalog                                        |
| GET    | `/products/:ref`               | Ein Produkt                                    |
| POST   | `/products`                    | Neues Produkt                                  |
| PATCH  | `/products/:ref`               | Produkt bearbeiten                             |
| GET    | `/categories`                  | Kategorien                                     |
| GET    | `/categories/:ref`             | Eine Kategorie                                 |
| GET    | `/jobs/:id`                    | Status eines zuvor gestarteten Schreibzugriffs |

`:ref` beim Automaten = UUID oder Seriennummer. Beim Produkt = UUID, SKU oder EAN. Bei der Kategorie = UUID oder Name.