Artikelstamm über die API pflegen

Nach diesem Artikel kannst du deinen kompletten Artikelstamm — Artikel, Preise, Kategorien, Rezepturen und Pakete — aus deinem eigenen System über die API anlegen, ändern und abgleichen, statt Excel-Dateien zu importieren.

Wenn dein Artikelstamm in einem anderen System lebt (Warenwirtschaft, ERP, Rezepturverwaltung), hältst du ihn über die Schnittstelle /api/v1/products mit Univents abgeglichen. Dein System schickt die Artikel, Univents legt sie an oder aktualisiert sie — mit denselben Regeln wie im Inventar: Brutto/Netto-Preis, Standard-Steuersatz, Einkaufspreis je Gebinde, vererbte Allergene und automatische Paketpreise.

Welche Felder es gibt, welchen Typ sie haben und welche Werte erlaubt sind, steht vollständig in der Schnittstellen-Beschreibung unter https://univents.app/api/v1/docs (Abschnitt products, Schema Product).

Schlüssel und Berechtigung

Erstelle unter Integrationen → Entwickler → API-Schlüssel einen Schlüssel mit Artikel & Kategorien lesen und Artikel, Kategorien & Rezepturen schreiben. Schreiben schließt Lesen nicht ein — wähle beides, wenn dein System auch abfragen soll. Die Einrichtung steht im Artikel zu den API-Schlüsseln.

Deine eigene Kennung: external_id

Gib jedem Artikel die Nummer aus deinem System als external_id mit. Sie ist in deinem Workspace eindeutig; ein zweiter Artikel mit derselben Kennung wird abgelehnt. Damit musst du dir unsere internen IDs nicht merken. Wird ein Artikel gelöscht, ist seine Kennung wieder frei.

Einen Artikel anlegen

curl -X POST https://univents.app/api/v1/products \
  -H "Authorization: Bearer rv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Bauernbrot","external_id":"ERP-1001","sku":"BR-1","price_gross":4.28,"tax_rate":7,"alt_unit_name":"Laib","category_name":"Brot","allergens":["gluten"]}'

Ohne tax_rate gilt der Standard-Steuersatz deines Workspace. Eine Kategorie gibst du per category_id oder per category_name an — gibt es den Namen noch nicht, wird die Kategorie angelegt.

Preise: eine Seite führt

Schicke entweder price_net oder price_gross. Die Seite, die du schickst, führt (price_basis), die andere rechnet Univents mit dem Steuersatz aus. Beide zusammen werden abgelehnt, damit nie eine Seite still verloren geht. Änderst du später nur den Steuersatz, bleibt die führende Seite stehen und die andere wird neu berechnet.

Viele Artikel auf einmal abgleichen

Mit POST /api/v1/products/batch schickst du bis zu 500 Artikel in einem Aufruf:

curl -X POST https://univents.app/api/v1/products/batch \
  -H "Authorization: Bearer rv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"external_id":"ERP-1001","price_gross":4.48},{"external_id":"ERP-1002","sku":"MEHL-405","name":"Weizenmehl 405","price_net":0.89,"alt_unit_name":"kg"}]}'

So findet Univents den passenden Artikel je Zeile:

  1. id, wenn du sie mitschickst,
  2. sonst external_id — unbekannt heißt: neu anlegen,
  3. sonst sku, aber nur wenn genau ein Artikel diese Artikelnummer hat,
  4. sonst wird angelegt (dafür ist name Pflicht).

Eine Zeile ohne id, external_id und sku wird abgelehnt, damit eine Wiederholung keine Dubletten erzeugt. Beim ersten Abgleich mit external_id und sku verknüpft Univents deine Kennung mit dem vorhandenen Artikel gleicher Artikelnummer.

Was überschrieben wird: Felder, die du schickst, überschreiben den gespeicherten Wert. Felder, die du weglässt, bleiben unverändert. null leert ein Feld.

Beschreibung: description ist Klartext. Schickst du sie (beim Anlegen, Ändern oder im Abgleich), ersetzt sie die im Inventar formatierte Beschreibung: die Formatierung fällt weg, und Inventar, Buchungsseite und Belege zeigen genau deinen Text. Jeder Zeilenumbruch (\n) wird im Inventar ein eigener Absatz.

Die Antwort nennt für jede Zeile created, updated oder error mit Grund und Feldnamen. Eine fehlerhafte Zeile hält die anderen nicht auf. Mit "dry_run": true prüfst du einen Abgleich, ohne etwas zu schreiben. Zeigen zwei Zeilen auf denselben Artikel (etwa einmal per Kennung, einmal per Artikelnummer), gilt nur die erste. Ein Batch zählt als eine Anfrage für das Limit von 120 Anfragen pro Minute; zusätzlich sind höchstens 6 Batch-Aufrufe pro Minute und Schlüssel möglich (3.000 Artikel). Artikelnummern und Kennungen dürfen jedes Zeichen enthalten, auch Zoll-Angaben wie Monitor 24", HDMI.

Rezepturen und Pakete

PUT /api/v1/products/{id}/components ersetzt die komplette Zutaten- bzw. Inhaltsliste eines Artikels:

curl -X PUT https://univents.app/api/v1/products/<id>/components \
  -H "Authorization: Bearer rv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"components":[{"child_external_id":"ERP-2001","quantity_per_parent":0.5},{"child_sku":"SALZ-1","content_quantity":10}]}'

Jede Zeile verweist mit genau einem von child_product_id, child_external_id oder child_sku auf einen Artikel deines Workspace. Die Menge steht in der Einheit der Zutat (quantity_per_parent) oder in ihrem Inhalt je Einheit (content_quantity, z. B. 200 ml aus der 1-l-Flasche). Die Liste wird ganz oder gar nicht ersetzt; enthält eine Zutat schon diesen Artikel, wird abgelehnt. Automatische Preise, Einkaufspreise und Allergene rechnet Univents danach selbst nach. Bekommt ein einfacher Artikel (Typ physical_product, weder Paket, Rezept noch Verleih) dabei mindestens einen Bestandteil, wird er automatisch zum Paket (is_bundle) — genau wie im Inventar, wenn du den ersten Bestandteil hinzufügst. Die Antwort meldet das mit promoted_to_bundle. Rezepte, Pakete, Verleih-Artikel und Dienstleistungen behalten ihren Typ, und eine leere Liste ändert nichts am Typ. Soll der Artikel ein Rezept sein, setzt du is_kitchen_produced am Artikel. Ein Artikel, der per API ohne product_type und ohne Bestandteile angelegt wurde, ist eine Dienstleistung und bleibt es auch hier — schicke dann "product_type":"physical_product" mit, wenn er ein Paket werden soll.

Ein Paket legst du am einfachsten in einem Aufruf an: Schicke die Bestandteile direkt beim Anlegen mit (POST /api/v1/products oder eine Batch-Zeile), im selben Format wie oben:

curl -X POST https://univents.app/api/v1/products \
  -H "Authorization: Bearer rv_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Grillpaket","external_id":"ERP-3001","components":[{"child_external_id":"ERP-2001","quantity_per_parent":2}]}'

Fehlt product_type und ist mindestens ein Bestandteil dabei, legt Univents den Artikel als physischen Artikel an, und er wird zum Paket. Schickst du product_type mit, bleibt genau dieser Typ — auch service. Die Bestandteile werden geprüft, bevor etwas gespeichert wird; lassen sie sich nicht speichern, wird auch der Artikel nicht angelegt. Im Batch dürfen Bestandteile auf Artikel zeigen, die eine frühere Zeile desselben Aufrufs anlegt (nicht eine spätere), und "dry_run": true prüft die Bestandteile mit. Bringt eine Batch-Zeile Bestandteile für einen schon vorhandenen Artikel mit, ersetzt sie dessen Liste wie der Aufruf oben, ohne den Typ zu ändern.

Kategorien und Räumlichkeiten

  • /api/v1/product-categories legt Katalog-Kategorien an, benennt sie um und löscht sie. Artikel einer gelöschten Kategorie wandern in die Sammel-Kategorie; die Sammel-Kategorie selbst lässt sich nicht löschen.
  • PUT /api/v1/products/{id}/locations legt fest, an welchen Räumlichkeiten ein Artikel angeboten (available) oder automatisch mitgebucht (required) wird.

Änderungen abholen

GET /api/v1/products?updated_since=… liefert alle seit einem Zeitpunkt geänderten Artikel, seitenweise mit cursor. Zusätzlich filterst du nach external_id, sku oder category_id. Gelöschte Artikel bekommst du mit include_deleted=true.

Was (noch) nicht über die API geht

Bilder, Varianten, Preisgruppen, Preise ab Stichtag, weitere Lieferanten je Artikel und Ticket-Kontingente pflegst du weiter im Inventar. Felder, die Univents selbst berechnet (z. B. vererbte Allergene), sind lesbar, aber nicht schreibbar — wer sie schickt, bekommt eine Absage mit dem Feldnamen.

Univents-Newsletter

Drei Themen, einzeln wählbar. Etwa einmal im Monat, nicht öfter.

Themen