Zugang

Das Token gehört zu Ihrer Organisation, nicht zu einer Person. Ein Token, manchmal auch Schlüssel genannt, ist eine lange Zeichenfolge, die für Programme wie ein Passwort wirkt. Ihr System meldet sich damit an der API an. Mit dem Token liest Ihr System die Ausschreibungen, die procuris kennt. Welchen Teil davon es holt, steuert es selbst über Filter.

Anfrage stellen

Das Token steht im Header Authorization. Davor steht das Wort Bearer mit einem Leerzeichen. Der Abruf geht über HTTPS an https://api.procuris.eu. Die Pfade beginnen mit der Version /v1:

GET /v1/tenders/e9da30eb-50e6-47f1-887f-434016267b2f HTTP/1.1
Host: api.procuris.eu
Authorization: Bearer <Ihr Token>
Accept: application/json

Die API antwortet mit JSON in UTF-8. Abrufe über unverschlüsseltes HTTP lehnt sie ab. Die Ablehnung kommt jedoch erst, nachdem das Token schon im Klartext durch das Netz gegangen ist. Hat Ihr System ein Token einmal über HTTP gesendet, behandeln Sie es darum als öffentlich geworden, siehe Token verloren oder öffentlich geworden.

Lesen, nicht schreiben

Die API liest nur. Sie kennt zwei Abrufe, beide mit GET:

Ihr System kann über die API nichts in procuris ändern. Suchaufträge, Board und Arbeitsmappen bleiben unberührt.

Token erstellen

Tokens erstellt nur die Rolle Inhaber. Das geschieht im Bereich API-Zugang unter Einstellungen › Organisation. Der Bereich erscheint erst, wenn der Zugang nach Vertragsschluss eingerichtet ist, und auch dann sieht ihn nur die Rolle Inhaber. Bis dahin führt die Zeile API-Zugang im Abschnitt Auf Anfrage derselben Seite nur zur Anfrage eines Angebots. Ihre IT baut den Abruf. Das Token bekommt sie von der Inhaberin.

1. Die Inhaberin wählt Token erstellen und gibt dem Token einen Namen, zum Beispiel „CRM-Abgleich“.
2. procuris zeigt das Token einmal an. Danach ist es nicht mehr lesbar, auch nicht für procuris.
3. Die Inhaberin gibt das Token über einen Passwortmanager an Ihre IT weiter, statt per E-Mail oder Chat, weil Nachrichten in Postfächern und Verläufen liegen bleiben.
4. Ihre IT legt es im Secret-Speicher des abrufenden Systems ab, nicht im Quellcode, weil Quellcode kopiert und geteilt wird. Ein Secret-Speicher ist ein geschützter Ablageort für Zugangsdaten, den nur das abrufende Programm und wenige Personen lesen dürfen.

Tokens laufen nicht von selbst ab. Wechseln Sie sie trotzdem regelmäßig, zum Beispiel einmal im Jahr. Ein unbemerkt kopiertes Token ist dann spätestens nach diesem Jahr wertlos. Verlässt jemand mit Zugriff auf das Token das Unternehmen, wechseln Sie es zusätzlich, weil die Person das Token sonst weiter nutzen könnte.

Token wechseln ohne Ausfall

Zwei gleichzeitig gültige Tokens erlauben den Wechsel ohne Ausfall. Eine Organisation kann bis zu zwei Tokens haben, und beide teilen sich die Grenze für Abrufe. Bestehen schon zwei Tokens, sperrt die Inhaberin zuerst das, das kein System mehr nutzt. Erst dann ist Platz für ein neues.

1. Die Inhaberin erstellt unter API-Zugang ein zweites Token.
2. Ihre IT trägt das neue Token in Ihrem System ein und prüft einen Abruf.
3. Die Inhaberin entfernt das alte Token unter API-Zugang mit Sperren.

Nutzen zwei Systeme je ein Token, zum Beispiel CRM und ERP, wechseln Sie ein Token nach dem anderen. Ein drittes Token ist nicht möglich. Darum leiht sich das System, dessen Token wechselt, für die Dauer des Wechsels das Token des anderen Systems:

1. Ihre IT trägt im CRM vorübergehend das Token des ERP ein und prüft einen Abruf.
2. Die Inhaberin sperrt das alte CRM-Token und erstellt ein neues.
3. Ihre IT trägt das neue Token im CRM ein. Das ERP läuft die ganze Zeit mit seinem Token weiter.
4. Für das ERP wiederholen Sie die Schritte 1 bis 3 mit vertauschten Rollen. Das ERP leiht sich dann das neue CRM-Token.

Beide Systeme rufen während des Wechsels ohne Pause ab. Die Grenze für Abrufe ändert sich dadurch nicht, weil sie ohnehin für beide Tokens zusammen gilt.

Token verloren oder öffentlich geworden

Die Inhaberin sperrt und ersetzt Tokens selbst unter API-Zugang. Eine Sperre wirkt ab dem nächsten Abruf.

• Öffentlich geworden: Steht das Token zum Beispiel in einem Code-Archiv oder einer E-Mail, sperrt die Inhaberin es sofort und erstellt danach ein neues. Der Abgleich ruht, bis Ihre IT das neue Token eingetragen hat. Diese Pause wiegt weniger als ein Token, das Fremde kennen.
• Verloren: Ist das Token nicht mehr auffindbar, aber nicht öffentlich, erstellt die Inhaberin ein neues und sperrt danach das alte. Bestehen schon zwei Tokens, sperrt sie zuerst das verlorene.
• Notfall: Ist niemand mit der Rolle Inhaber erreichbar, schreiben Sie an support@procuris.eu. Wir sperren das Token nach Rückfrage bei Ihrer Organisation. Ein neues Token erstellt danach wieder die Inhaberin.

Ein gesperrtes Token führt zur Antwort 401.

Fehler

Fehler kommen als HTTP-Status mit einer Beschreibung in JSON. Die Beschreibung steht im Antworttext (dem Teil der Antwort nach den Headern). Ihr Format ist application/problem+json nach RFC 9457, dem Internet-Standard für Fehlermeldungen von Schnittstellen:

{
  "type": "https://docs.procuris.eu/docs/api/zugang#fehler",
  "title": "Token ungültig",
  "status": 401,
  "detail": "Das Token ist unbekannt oder gesperrt.",
  "instance": "/v1/tenders"
}

Grenzen

Ohne andere Regelung im Angebot gelten 60 Abrufe je Minute. Die Grenze gilt je Organisation, über beide Tokens zusammen. Ihr Angebot kann höhere Grenzen umfassen.

Drei Header zeigen, wie viele Abrufe noch frei sind. Sie stehen in jeder Antwort auf einen Abruf mit gültigem Token. Bei einer Antwort 401 erkennt procuris keine Organisation, darum fehlen die Header dort.

Über der Grenze antwortet die API mit 429. Der Header Retry-After nennt die Wartezeit in Sekunden.

Ein stündlicher Abgleich bleibt weit unter der Grenze: 1.000 geänderte Datensätze brauchen bei 100 je Seite 10 Abrufe, während die Grenze 60 je Minute erlaubt.

Verwandte Seiten

• API: erster Abruf
• Datenmodell
• Filter und Takt