DIGIBIZ Reporting API · Sandbox

Schnellstart

Diese Anleitung führt Sie in etwa zehn Minuten zum ersten Aufruf der Sandbox. Sie holen ein Token und rufen damit /v1/whoami und eine erste Datenseite ab.

Was Sie brauchen

Die Sandbox nutzt diese Adressen:

Zweck Wert
Token-Endpunkt https://login.microsoftonline.com/e0a4a9bd-bad6-4168-be92-5082a168c035/oauth2/v2.0/token
Scope api://9e80ba51-31dd-4c19-8b53-c098bf37477e/.default
API https://reporting-sandbox.app.spdigi.biz/v1

1. Zugangsdaten setzen

Lesen Sie das Secret verdeckt ein. So landet es nicht in der Shell-Historie.

export CLIENT_ID="<Ihre Client-ID>"
read -rsp 'Client-Secret: ' CLIENT_SECRET && echo && export CLIENT_SECRET

2. Token holen

Die Sandbox nutzt den Client-Credentials-Flow von Microsoft Entra ID.

RESPONSE=$(curl -s -X POST "https://login.microsoftonline.com/e0a4a9bd-bad6-4168-be92-5082a168c035/oauth2/v2.0/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  --data-urlencode client_secret="$CLIENT_SECRET" \
  --data-urlencode scope="api://9e80ba51-31dd-4c19-8b53-c098bf37477e/.default")
TOKEN=$(printf '%s' "$RESPONSE" | jq -r '.access_token // empty')
[ -n "$TOKEN" ] || printf '%s\n' "$RESPONSE" | jq .

Fehlt das Token, zeigt der letzte Befehl die Antwort von Entra ID. Die Felder error und error_description nennen die Ursache, etwa eine falsche Client-ID oder ein abgelaufenes Secret.

Ein Token gilt etwa 60 bis 90 Minuten. Holen Sie danach ein neues.

3. Identität prüfen

curl -s -H "Authorization: Bearer $TOKEN" "https://reporting-sandbox.app.spdigi.biz/v1/whoami" | jq

Die Antwort nennt Ihre Client-ID, die freigegebenen Verfahren und die Spaltengruppen. Jedes Verfahren hat einen festen Schlüssel der Form p_.... Mit diesem Schlüssel filtern Sie später einzelne Verfahren.

4. Erste Datenseite abrufen

curl -s -H "Authorization: Bearer $TOKEN" "https://reporting-sandbox.app.spdigi.biz/v1/cases?page_size=100" | jq '.meta, (.data | length), .next_link'

Jede Antwort enthält data, meta und auf allen Seiten außer der letzten next_link. Rufen Sie next_link unverändert auf, bis das Feld fehlt. Bauen Sie den Cursor nicht selbst.

Ein Verfahren wählen Sie mit proceeding_id:

curl -s -H "Authorization: Bearer $TOKEN" "https://reporting-sandbox.app.spdigi.biz/v1/invoices?proceeding_id=p_...&page_size=500"

5. Wenn etwas schiefgeht

Fehler kommen als application/problem+json. Das Feld code nennt die Ursache. Der Fehlerkatalog erklärt jeden Code. Die häufigsten Fälle:

Grenzen der Sandbox

Weiter