System & Administration

Artwork-API

Daten aus Artwork mit API-Schlüssel in andere Programme übernehmen. Zugang, Rechte, Endpunkte für Raumbelegung und Inventar

Über die Artwork-API lesen andere Programme Daten aus Artwork, zum Beispiel eine Jahresplanung, die wissen muss, welche Räume belegt sind. Die API ist versioniert (/api/v1) und antwortet immer mit JSON. Jedes Programm braucht einen eigenen API-Schlüssel mit den passenden Rechten.

Zugang einrichten

  1. Öffne die Tool-Einstellungen, Register Schnittstellen, Bereich Schnittstelle Artwork. Dafür brauchst du das Recht Tooleinstellungen.
  2. Lege einen Schlüssel mit sprechendem Namen an (z. B. den Namen des angebundenen Programms) und wähle nur die Rechte, die das Programm braucht.
  3. Setze bei Bedarf ein Ablaufdatum. Der Schlüssel gilt bis zum Ende dieses Tages. Ohne Ablaufdatum läuft er nach der Standardlaufzeit ab, im Regelfall nach einem Jahr. Ein späteres Ablaufdatum verlängert sie nicht: Es gilt immer das frühere der beiden Daten.
  4. Kopiere den Schlüssel sofort in den geschützten Secret-Speicher des angebundenen Programms. Er wird nur einmal angezeigt.

Das Programm schickt den Schlüssel bei jeder Anfrage im Header Authorization: Bearer <Schlüssel> mit.

RechtErlaubt
calendar:readRäume, Bereiche, Termine und Terminstatus lesen (Raumbelegung)
inventory:readInventar-Kategorien und -Artikel lesen (Inventar)
ticketing:read, ticketing:writeFür den Artwork-Ticketshop vorgesehen

Alle Rechte sind lesend, außer ticketing:write. Mit einem Schlüssel lassen sich keine anderen Daten abrufen und nichts in Artwork ändern.

Ältere Schlüssel, bei denen die Liste unter Berechtigungen „Keine — erstellt, bevor es Berechtigungen gab“ zeigt, werden von diesen Endpunkten abgewiesen. Rechte lassen sich nicht nachträglich vergeben; lege für das Programm einen neuen Schlüssel an. Ob und wann ein Schlüssel benutzt wird, zeigt sein Protokoll in derselben Liste.

Schlüssel wechseln

Zum Wechseln legst du einen zweiten Schlüssel an, stellst das Programm um und widerrufst danach den alten. Beide Schlüssel funktionieren in der Zwischenzeit parallel. Ein widerrufener oder abgelaufener Schlüssel wird sofort abgewiesen.

Grundregeln

  • Nur über HTTPS; alle Antworten als JSON (UTF-8), auch Fehler.
  • Höchstens 120 Anfragen pro Minute und Schlüssel.
  • Zeitpunkte nach ISO 8601 mit Zeitzone, z. B. 2027-03-01T15:00:00+01:00.
  • IDs bleiben dauerhaft gleich, auch wenn ein Raum oder Projekt umbenannt wird.
  • Bestehende Felder werden nicht umbenannt oder entfernt. Neue Felder können hinzukommen; angebundene Programme sollen unbekannte Felder ignorieren.
CodeBedeutung
200Erfolg, auch bei leerer Liste
400Parameter fehlt oder ist ungültig; errors nennt den Parameter
401Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen
403Schlüssel hat das nötige Recht nicht
429Zu viele Anfragen; nach den Sekunden im Header Retry-After erneut versuchen
5xxStörung bei Artwork

Fehler enthalten eine lesbare Meldung in message. Jede erfolgreiche Antwort der Raumbelegung nennt in generated_at den Zeitpunkt, zu dem sie erzeugt wurde.

Raumbelegung (calendar:read)

Welcher Raum ist wann durch welches Projekt belegt? Die Raumbelegung liefert dafür die Räume, die Termine darin und die Terminstatus.

Räume: GET /api/v1/rooms

Alle Räume ohne Papierkorb mit id, name, Bereich (area_id, area_name), Raumkategorien, Kapazität, Farbe und den Angaben zu temporären Räumen. Mit areas=3,4 lassen sich die Räume bestimmter Bereiche abrufen.

Termine: GET /api/v1/events

ParameterPflichtBedeutung
fromjaErster Tag (JJJJ-MM-TT)
tojaLetzter Tag, einschließlich; höchstens drei Jahre nach from
roomsneinRaum-IDs, z. B. rooms=31,32
areasneinBereichs-IDs; zusammen mit rooms gilt beides (Räume und alle Räume der Bereiche)
updated_sinceneinNur seit diesem Zeitpunkt geänderte oder gelöschte Termine
page, per_pageneinSeite und Termine je Seite (Standard 500, höchstens 1000)

Geliefert wird jeder Termin mit Raum, der den Zeitraum berührt, mit seinen echten Beginn- und Endzeiten. Jeder Termin enthält unter anderem:

  • id, title (Projektname, ohne Projekt der Terminname oder Termintyp), project_id, project_name, event_type
  • room_id, room_name, area_id, area_name
  • start und end als Zeitpunkte (end = ab dann ist der Raum frei), all_day, start_date und end_date (erster und letzter Kalendertag, einschließlich)
  • status (Terminstatus) und room_request_pending (offene Raumanfrage)
  • series_id bei Terminserien, updated_at, deleted_at

Nicht enthalten sind Planungstermine, Termine ohne Raum, Termine in Räumen im Papierkorb sowie Personendaten, Beschreibungen und Kommentare. Gelöschte Termine erscheinen nur bei Abfragen mit updated_since, dann mit gesetztem deleted_at.

Längere Listen sind in Seiten aufgeteilt: links.next enthält die Adresse der nächsten Seite und ist auf der letzten Seite leer. Der Abruf ohne updated_since ist immer der vollständige Stand.

Terminstatus: GET /api/v1/event-statuses

Alle Terminstatus mit id, name, color, order und default, dazu status_enabled. Die id entspricht status.id an den Terminen. So kann ein angebundenes Programm festlegen, welche Status als Belegung zählen. Sind Terminstatus in den Termineinstellungen ausgeschaltet, ist status_enabled falsch und Termine haben keinen Status.

Inventar (inventory:read)

EndpunktInhalt
GET /api/v1/inventoryInventar-Kategorien mit ihren Unterkategorien und Artikeln, seitenweise (per_page Standard 15, höchstens 100)
GET /api/v1/inventory/articlesArtikel, seitenweise (per_page Standard 50, höchstens 100), filterbar mit search, category_id, subcategory_id
GET /api/v1/inventory/articles/{id}Ein Artikel mit Inventarnummer, Name, Beschreibung, Kategorie, Gesamtmenge (quantity), Eigenschaften und Bildern

Die früheren Adressen ohne Versionsnummer (/api/inventory, /api/inventory/articles) liefern noch dieselben Daten, sind aber abgekündigt. Stelle angebundene Programme auf /api/v1 um.

Auf dieser Seite