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
- Öffne die Tool-Einstellungen, Register Schnittstellen, Bereich Schnittstelle Artwork. Dafür brauchst du das Recht Tooleinstellungen.
- 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.
- 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.
- 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.
| Recht | Erlaubt |
|---|---|
calendar:read | Räume, Bereiche, Termine und Terminstatus lesen (Raumbelegung) |
inventory:read | Inventar-Kategorien und -Artikel lesen (Inventar) |
ticketing:read, ticketing:write | Fü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.
| Code | Bedeutung |
|---|---|
200 | Erfolg, auch bei leerer Liste |
400 | Parameter fehlt oder ist ungültig; errors nennt den Parameter |
401 | Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen |
403 | Schlüssel hat das nötige Recht nicht |
429 | Zu viele Anfragen; nach den Sekunden im Header Retry-After erneut versuchen |
5xx | Stö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
| Parameter | Pflicht | Bedeutung |
|---|---|---|
from | ja | Erster Tag (JJJJ-MM-TT) |
to | ja | Letzter Tag, einschließlich; höchstens drei Jahre nach from |
rooms | nein | Raum-IDs, z. B. rooms=31,32 |
areas | nein | Bereichs-IDs; zusammen mit rooms gilt beides (Räume und alle Räume der Bereiche) |
updated_since | nein | Nur seit diesem Zeitpunkt geänderte oder gelöschte Termine |
page, per_page | nein | Seite 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_typeroom_id,room_name,area_id,area_namestartundendals Zeitpunkte (end= ab dann ist der Raum frei),all_day,start_dateundend_date(erster und letzter Kalendertag, einschließlich)status(Terminstatus) undroom_request_pending(offene Raumanfrage)series_idbei 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)
| Endpunkt | Inhalt |
|---|---|
GET /api/v1/inventory | Inventar-Kategorien mit ihren Unterkategorien und Artikeln, seitenweise (per_page Standard 15, höchstens 100) |
GET /api/v1/inventory/articles | Artikel, 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.
Zuletzt aktualisiert am