Integration & Automatisierung

API: Vorgänge und Aufgaben aus einem anderen System lesen

Mit der API liest ein anderes System — etwa euer ERP — Vorgänge, Aufgaben und Vorlagen aus Bricksta. Es meldet sich mit einem API-Schlüssel an und braucht keine Person dafür. In Version 1 kann die API nur lesen; ändern kann sie noch nichts.

Auf dieser Seite

Anmelden mit dem API-Schlüssel

  1. 1
    Eine Person mit Organisationsverwaltung legt in der Organisation einen API-Zugang an. Bricksta zeigt den Schlüssel dabei einmal an; kopiere ihn gleich an die Stelle, wo das andere System ihn braucht.
  2. 2
    Das andere System schickt den Schlüssel bei jedem Aufruf im Kopf mit: Authorization: Bearer <Schlüssel>.
  3. 3
    Schicke den Schlüssel nie in der Adresse (Query-String). Dort landet er in Protokollen.
  4. 4
    Ist ein Schlüssel verloren oder nicht mehr nötig, wird der API-Zugang widerrufen. Der Schlüssel gilt dann sofort nicht mehr.

Jeder Aufruf steht im Lauf-Protokoll des API-Zugangs: Zeit, Pfad, Status und Dauer. Feldinhalte stehen nie darin.

Was die API kann

Ein externes System liest mit seinem API-Schlüssel die Vorgänge, die Aufgaben samt allen Feldern (mit Feld-IDs und Options-IDs) und die Vorlagen eurer Firma. Der Schlüssel handelt als eigenes API-Konto, ein Systemkonto. Er sieht genau das, was dieses Konto sehen darf: seine Rollen, private Vorlagen und die Sichtbarkeit einzelner Felder gelten auch hier.

Ein API-Konto mit Verwaltungsrechten (Organisation, Mitglieder oder Vorlagen verwalten) weist Bricksta ab. Gib dem API-Konto nur die Rechte, die das lesende System braucht.

API, Auslöser oder KI-Assistent?

AuslöserEin anderes System stößt Bricksta von außen an, zum Beispiel um einen Vorgang zu starten.Der Auslöser, ohne Person
KI-Assistent (MCP)Claude oder ChatGPT arbeiten im Chat mit Bricksta. Mehr dazu unter Bricksta in Claude und ChatGPT nutzen.Eine Person, mit ihren Rechten
APIEin System liest Daten aus Bricksta, Maschine zu Maschine.Das API-Konto, mit Schlüssel

Soll Bricksta von sich aus melden, wenn etwas passiert, nutzt du den Rückkanal: ausgehende Webhooks.

Die Abrufe in Version 1

GET /api/v1/casesEine Seite Vorgänge. Filter: updated_since, template, status, field mit value, limit (1 bis 100) und cursor.
GET /api/v1/cases/{id}Ein Vorgang mit allen seinen Aufgaben.
GET /api/v1/tasks/{id}Eine Aufgabe mit allen Feldern, auch den leeren, jeweils mit ihren IDs.
GET /api/v1/templatesDie Vorlagen eurer Firma, die das API-Konto sehen darf.
GET /api/v1/openapi.jsonDie Beschreibung der API als OpenAPI 3.1. Dafür braucht es keine Anmeldung.

Blättern und abgleichen

Bei GET /api/v1/cases gibst du den next_cursor der Antwort beim nächsten Aufruf als cursor mit. Ist next_cursor leer (null), bist du am Ende. Ein Vorgang kann beim Blättern mindestens einmal geliefert werden, also auch zweimal. Gleiche deshalb über die id ab.

Änderungen aus den letzten 30 Sekunden erscheinen erst beim nächsten Abruf. Für einen laufenden Abgleich merkst du dir das größte updated_at deiner letzten Antwort und fragst damit als updated_since nur nach Neuem. Nimm dafür nicht die Uhrzeit deines Abrufs: Was in den 30 Sekunden davor geändert wurde, fehlte in der Antwort und fiele sonst durch. updated_at ändert sich auch, wenn eine Aufgabe oder ein Feldwert des Vorgangs geändert wird.

Grenzen

Lesende Aufrufe120 je Minute und Schlüssel
Schreibende Aufrufe30 je Minute und Schlüssel (für spätere Versionen)
Gleichzeitige Aufrufehöchstens 4 je Schlüssel, 8 je Firma

Bei Überschreitung antwortet Bricksta mit 429 und dem Kopf Retry-After: so viele Sekunden wartest du, dann geht es weiter. Eine Firma, deren Vertrag beendet ist, kann weiter lesen.

Fehlermeldungen

Bei einem Fehler antwortet Bricksta mit application/problem+json (RFC 9457) und einem code. Nach dem code richtest du die Behandlung im anderen System aus. Die Codes stehen unten nach Status geordnet.

Anfrage fehlerhaft (400)

invalid_parameterEin Parameter hat einen ungültigen Wert.
unknown_parameterDie Anfrage enthält einen Parameter, den es nicht gibt.
invalid_limitlimit liegt nicht zwischen 1 und 100.
invalid_cursorDer cursor ist ungültig oder abgelaufen. Beginne die Liste von vorn.
idempotency_key_requiredEin schreibender Befehl braucht einen Idempotenz-Schlüssel. Betrifft spätere Versionen.
unknown_commandDiesen Befehl gibt es nicht.

Anmeldung und Rechte (401, 403, 404)

invalid_api_key401Der Schlüssel fehlt, ist unbekannt oder widerrufen. Bricksta antwortet in allen drei Fällen gleich.
account_has_admin_rights403Das API-Konto hat Verwaltungsrechte und wird abgewiesen.
forbidden403Das API-Konto darf das nicht sehen oder tun.
not_found404Das Objekt gibt es nicht. Das gilt auch für Objekte einer anderen Firma.

Schreibende Befehle (409 bis 423)

Diese vier Codes treten erst bei schreibenden Befehlen späterer Versionen auf. Version 1 liest nur.

conflict409Der Stand hat sich inzwischen geändert.
payload_too_large413Die gesendeten Daten sind zu groß.
unprocessable422Die Daten sind lesbar, passen aber nicht zu den Regeln der Vorlage.
read_only423Die Firma ist gerade schreibgeschützt.

Zu viele Aufrufe (429)

rate_limitedDas Limit je Minute ist erreicht. Warte die Zeit aus Retry-After ab.
too_many_concurrent_requestsZu viele Aufrufe laufen gleichzeitig. Warte kurz und versuche es erneut.

Serverseitige Fehler (500 bis 503)

internal_error500Bei Bricksta ist etwas schiefgegangen. Versuche es später erneut.
timeout503Die Antwort hat zu lange gedauert. Mit Retry-After.
temporarily_unavailable503Bricksta ist kurz nicht erreichbar. Mit Retry-After.
not_written503Ein schreibender Befehl wurde nicht ausgeführt. Mit Retry-After.
outcome_unknown503Ob ein schreibender Befehl ausgeführt wurde, ist offen. Ohne Retry-After: erst nachsehen, dann entscheiden.