API Authentifizierung

Integration-API-Requests verwenden Bearer-Authentifizierung mit einem Optimus Personal Access Token.

Dasselbe Tokenmodell wird von Integration CLI und der Integration API verwendet. Erstellen Sie für jede Produktionsintegration ein separates Token, damit es widerrufen oder per IP eingeschränkt werden kann, ohne andere Systeme zu beeinflussen.

Token In Optimus Erstellen

In der Optimus Web-App:

1. Öffnen Sie Settings.
2. Wählen Sie den Tab API Interface.
3. Klicken Sie in API Tokens auf Create Token.
4. Geben Sie einen beschreibenden Token Name ein.
5. Fügen Sie optional Allowed IP ranges hinzu.
6. Klicken Sie auf Create Token.
7. Kopieren Sie das Token sofort.

Das Token-Secret wird nach der Erstellung nur einmal angezeigt. Nachdem der Dialog geschlossen wurde, zeigt die Web-App nur noch das Token-Präfix und maskierte Zeichen.

Die Seite API Tokens verlinkt außerdem auf die Integration-API-Dokumentation, in der Sie sich authentifizieren und Requests ausprobieren können.

Erlaubte IP-Bereiche

Erlaubte IP-Bereiche schränken ein, von wo aus das Token verwendet werden kann.

• Lassen Sie das Feld leer, um Requests von jeder IP-Adresse zu erlauben.
• Fügen Sie exakte IPv4-Adressen oder IPv4-CIDR-Bereiche hinzu, um den Zugriff einzuschränken.
• Drücken Sie im Dialog zur Token-Erstellung nach jeder IP-Adresse oder jedem CIDR-Bereich Enter.
• Sie können erlaubte IP-Bereiche später in der Tokenliste bearbeiten.

Beispiele:

203.0.113.10
203.0.113.0/24

Token Senden

Senden Sie das Token im Authorization-Header:

Authorization: Bearer <token>

Beispielrequest:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE284700631" \
  -H "Authorization: Bearer <token>"

Fügen Sie den tok_optimus_-Tokenwert nicht in Quellcode, Issue-Tracker, Logs, Screenshots oder Dokumentationsbeispiele ein.

Base URLs

Umgebung	Base URL
Produktion	https://app.optimussoftware.de
Test	https://dev.app.optimussoftware.de

Verwenden Sie die Test-Base-URL, während Sie eine Testintegration validieren. Verwenden Sie Produktion nur, wenn der Client bereit ist, echte USt-IdNr.-Daten zu validieren.

Requests In Der API-Referenz Ausprobieren

Öffnen Sie die Integration-API-Dokumentation von der Seite API Tokens, authentifizieren Sie sich mit Ihrem Token als Bearer Token und verwenden Sie dann die generierte Endpunktreferenz, um Requests zu prüfen.

Wenn Sie curl verwenden, fügen Sie denselben Header manuell hinzu:

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/resolve?vatId=DE284700631" \
  -H "Authorization: Bearer <token>"

Bestehende Tokens Verwalten

Die Liste API Tokens zeigt:

• Tokenname.
• Token-Präfix, der Rest ist maskiert.
• Erstellungsdatum.
• Datum der letzten Verwendung, falls verfügbar.
• Ablaufstatus.
• Erlaubte IP-Bereiche.

Verwenden Sie Edit IP ranges, um erlaubte Quell-IPs zu aktualisieren. Verwenden Sie Revoke, um ein Token dauerhaft zu deaktivieren. Der Widerruf eines Tokens kann nicht rückgängig gemacht werden, und Anwendungen, die dieses Token verwenden, können danach nicht mehr auf die API zugreifen.

Authentifizierungsfehler

Status	Bedeutung	Behebung
401	Token fehlt, ist ungültig, abgelaufen oder widerrufen.	Erstellen Sie ein neues Token unter Settings > API Interface > API Tokens und aktualisieren Sie Ihren Client.
403	Token wird erkannt, darf aber nicht auf die Ressource zugreifen, oder der Request ist von der aktuellen IP-Adresse nicht erlaubt.	Prüfen Sie Tokenberechtigungen, Kontozugriff und erlaubte IP-Bereiche.