API Einstieg

Diese Seite zeigt den kürzesten sinnvollen Integration-API-Ablauf: Token erstellen, ihn mit einem schnellen VAT-ID-Lookup testen und anschließend einen wiederholungssicheren USt-IdNr.-Validierungslauf starten.

1. Base URL Wählen

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

Die Beispiele unten verwenden die Produktion. Ersetzen Sie den Host durch die Test-Base-URL, wenn Sie eine Testintegration validieren.

2. Token Erstellen

Erstellen Sie ein Personal Access Token in der Optimus Web-App unter Settings > API Interface > API Tokens.

Kopieren Sie das Token sofort. Das vollständige Secret wird nur einmal angezeigt.

3. Eine VAT ID Auflösen

Verwenden Sie den Quick-Lookup-Endpunkt, um zu prüfen, ob Authentifizierung, Netzwerkzugriff und die ausgewählte Umgebung funktionieren:

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

Eine erfolgreiche Antwort liefert den USt-IdNr.-Status und, wenn verfügbar, normalisierte Unternehmensdaten:

{
  "vatId": "DE284700631",
  "status": "Valid",
  "resolvedData": {
    "companyName": "Optimus Software GmbH",
    "street": "Tal 44",
    "city": "München",
    "zip": "80331"
  },
  "checkedAt": "2026-04-19T10:17:26.4359867Z"
}

Wenn Sie die aufgelöste Straße in Straßenname und Hausnummer getrennt benötigen, fordern Sie diese Felder mit include an:

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

Die zusätzlichen Felder werden nur dann in included zurückgegeben, wenn die Daten aufgelöst werden können:

{
  "vatId": "DE284700631",
  "status": "Valid",
  "resolvedData": {
    "companyName": "Optimus Software GmbH",
    "street": "Tal 44",
    "city": "München",
    "zip": "80331"
  },
  "included": {
    "addressStreetName": "Tal",
    "addressHouseNumber": "44"
  },
  "checkedAt": "2026-04-19T10:17:26.4359867Z"
}

4. Eine Asynchrone Validierung Starten

Verwenden Sie die asynchrone Validierung für Importe, größere Batches, wiederholungssichere Jobs und Workflows, die PDFs erzeugen.

Erstellen Sie validation-request.json:

{
  "records": [
    {
      "vatId": "DE284700631",
      "companyName": "Optimus Software GmbH",
      "street": "Tal 44",
      "zip": "80331",
      "city": "München",
      "customerNumber": "C-1001"
    }
  ],
  "options": {
    "checkType": "Standard",
    "retryDuration": "None"
  }
}

Senden Sie die Anfrage mit einem Idempotency Key aus Ihrem eigenen System, zum Beispiel einer Import-Job-ID:

curl -X POST "https://app.optimussoftware.de/api/v1/integration/vat/validations/async" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: customer-import-2026-05-13-001" \
  -H "Content-Type: application/json" \
  -d @validation-request.json

Die Antwort enthält eine operationId. Wenn der Status Running ist, warten Sie vor dem Polling auf den Wert aus Retry-After.

5. Ergebnis Abfragen

curl -X GET "https://app.optimussoftware.de/api/v1/integration/vat/validations/{operationId}" \
  -H "Authorization: Bearer <token>"

Wenn der Lauf abgeschlossen ist, enthält die Antwort Statuswerte pro Datensatz und Feldvergleichsergebnisse.

Was Sie Als Nächstes Lesen Sollten

• Nutzen Sie API Authentication für Token-Erstellung, erlaubte IP-Bereiche und Token-Widerruf.
• Nutzen Sie den Validation Runs Guide, um synchrone oder asynchrone Validierung auszuwählen und Ergebnisse zu interpretieren.
• Nutzen Sie Synchrone USt-Validierung starten für Request- und Response-Details.
• Nutzen Sie Idempotency, bevor Sie automatische Wiederholungen hinzufügen.
• Nutzen Sie API Errors, wenn Sie entscheiden müssen, ob eine Anfrage korrigiert oder später erneut versucht werden soll.