STS-Online in Ihr Programm einbinden

Überblick

Basisadresse: https://www.steuersoft.online. Alle Pfade beginnen mit /api/v1/. Verbindungen sind ausschließlich per HTTPS möglich.

Ihre Schwerpunkte

Typische Bereiche für Software von Buchstellen, Kanzleien und Beratungsstellen. Die Endpunkt-Referenz stellt sie nach vorn.

Die übrigen Funktionen stehen ebenfalls zur Verfügung. Was ein Zugang tatsächlich darf, legt die Organisation über die Rechte fest.

Schnellstart

1. Zugriffstoken anfordern

Kennung (stsc_…) und Geheimnis (stss_…) im Basic-Kopf, grant_type=client_credentials im Körper. Die Antwort enthält access_token und expires_in (Sekunden). Fordern Sie kurz vor Ablauf oder nach einer Antwort 401 ein neues Token an.

curl -s -u "$STS_CLIENT_ID:$STS_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  https://www.steuersoft.online/api/v1/extern/token

2. Verbindung testen

GET /api/v1/extern/ich zeigt Zugang, Organisation und Berechtigungen.

curl -s -H "Authorization: Bearer $TOKEN" https://www.steuersoft.online/api/v1/extern/ich

3. Daten anlegen – sicher gegen Doppel

# Idempotency-Key: ein eigener Schlüssel je Vorgang, z. B. aus Ihrer Nummer
# gebildet (oder uuidgen bzw. [guid]::NewGuid()) — bei Wiederholung derselbe.
curl -s -X POST https://www.steuersoft.online/api/v1/mandanten \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: mandant-anlegen-M-100" \
  -H "Content-Type: application/json" \
  -d '{"nachname": "Muster", "vorname": "Erika", "externe_id": "M-100"}'

Zugang & Rechte

Jeder Zugang gehört zu genau einer Organisation. Der Inhaber vergibt beim Anlegen die Rechte und kann sie jederzeit einschränken. Das wirkt sofort, auch für bereits ausgestellte Token. Die Referenz nennt je Aufruf die nötigen Rechte.

• Token mit weniger Rechten: scope=lesen bei der Tokenanforderung, etwa für reine Lese-Abgleiche. Mehr Rechte als der Zugang sind nicht möglich. Es gilt, was das Token darf — GET /api/v1/extern/ich nennt es in scopes.
• IP-Freigabe: Der Zugang kann auf feste Adressen oder Netze beschränkt sein. Anfragen von anderswo werden mit 403 abgewiesen.
• Gültigkeit: 90 Tage bis 2 Jahre, danach muss das Geheimnis erneuert werden. Zugänge können jederzeit widerrufen werden.
• Nicht über die Schnittstelle: Anmeldung, Benutzer- und Rechteverwaltung, Organisationseinstellungen und die Verwaltung von Zugängen und Webhooks.

Konventionen

Doppelte Anlage vermeiden

Zwei Mechanismen ergänzen sich. Nutzen Sie beide.

Webhooks

Der Inhaber trägt in STS-Online eine HTTPS-Adresse Ihres Programms ein und wählt die Ereignisse. Bei jedem Ereignis kommt ein POST mit JSON. Er enthält nur Kennungen und den Bearbeitungsstand, keine Namen, Beträge oder Steuerdaten. Die Einzelheiten holen Sie über die Schnittstelle.

{
  "id": "0b8e6a0e-…",
  "ereignis": "fall.status_geaendert",
  "zeitpunkt": "2026-09-28T10:15:02+00:00",
  "organisation_id": "…",
  "ausgeloest_von": "api:stsc_…",
  "daten": {
    "fall_id": "…",
    "externe_id": "F-2025-100",
    "status": "validiert",
    "status_vorher": "in_bearbeitung"
  }
}

Signatur prüfen

Kopf X-STS-Signature: t=<Unix-Zeit>,v1=<HMAC>. HMAC-SHA256 mit Ihrem Signaturgeheimnis (whsec_…) über <t>. und den unveränderten Körper. Weisen Sie Nachrichten mit falscher Signatur oder mehr als 5 Minuten Zeitabweichung ab.

# Prüfung im Empfänger — Beispiel mit openssl:
# erwartet = HMAC-SHA256(Geheimnis, "<t>." + roher Körper), hexadezimal
printf '%s.%s' "$T" "$KOERPER" | openssl dgst -sha256 -hmac "$WHSEC" -hex

• Schnell antworten: innerhalb von 10 Sekunden mit 2xx, danach verarbeiten. Umleitungen werden nicht verfolgt.
• Wiederholungen: Bei Fehlern wird bis zu etwa drei Tage lang in wachsenden Abständen erneut zugestellt. Ist Ihr Endpunkt dauerhaft nicht erreichbar, wird der Webhook abgeschaltet.
• Mindestens einmal: Ein Ereignis kann ausnahmsweise doppelt kommen. Erkennen Sie Doppel an id bzw. X-STS-Event-Id. Die Reihenfolge ist nicht garantiert, im Zweifel lesen Sie den aktuellen Stand.
• Eigene Änderungen: ausgeloest_von nennt Ihren Zugang, wenn Ihr Programm die Änderung selbst ausgelöst hat: api:stsc_… beim Zugang einer Organisation, api:stsg_… (Kennung der Freigabe in dieser Organisation) beim Partner-Zugang.
• Adresse: nur HTTPS auf Port 443 oder 8443, öffentlich erreichbar.

Die Liste aller Ereignistypen steht in der Endpunkt-Referenz.

Partner-Zugang für Software-Anbieter

Verbindet sich Ihr Programm mit vielen Organisationen (z. B. allen Kunden Ihrer Software), erhalten Sie einen Partner-Zugang: eine Kennung (stsp_…) und ein Geheimnis, ausgestellt vom Betreiber. Kennung und Geheimnis einzelner Organisationen brauchen Sie dann nicht.

1. Freigabe durch den Kunden: Der Inhaber einer Organisation gibt Ihren Zugang selbst frei und wählt die Rechte. Führen Sie ihn mit diesem Link dorthin:https://www.steuersoft.online/organisation?tab=schnittstelle&partner=<Ihre Kennung>Nach der Freigabe sieht er dort auch die Kennung seiner Organisation.
2. Freigaben abfragen: GET /api/v1/extern/partner/freigaben mit Ihrer Kennung und Ihrem Geheimnis (Basic) liefert alle Organisationen, die Sie freigegeben haben, mit organisation_id und Rechten.
3. Token je Organisation: POST /api/v1/extern/token wie im Schnellstart, zusätzlich organisation_id. Jedes Token gilt nur für diese eine Organisation und höchstens mit den dort freigegebenen Rechten.

# 1. Welche Organisationen haben Sie freigegeben?
curl -s -u "$STS_PARTNER_ID:$STS_PARTNER_SECRET" https://www.steuersoft.online/api/v1/extern/partner/freigaben

# 2. Token für GENAU EINE dieser Organisationen
curl -s -u "$STS_PARTNER_ID:$STS_PARTNER_SECRET" \
  -d grant_type=client_credentials -d organisation_id="$ORG_ID" \
  https://www.steuersoft.online/api/v1/extern/token

• Widerruf: Eine Organisation kann die Freigabe jederzeit widerrufen. Laufende Token antworten dann mit 401, neue Token mit 403 access_denied. Entfernen Sie die Organisation in diesem Fall aus Ihrem Abgleich.
• IP-Freigabe: Für einen Partner-Zugang legt sie der Betreiber fest; sie gilt für alle Organisationen. Teilen Sie ihm die festen Adressen Ihrer Server mit.
• Sperre: Sperrt der Betreiber Ihren Zugang, werden alle Token sofort ungültig — auch nach dem Entsperren. Fordern Sie danach neue Token an.
• Partner-Webhook: Auf Wunsch richtet der Betreiber einen Webhook für Ihren Zugang ein. Sie erhalten dann die Ereignisse aller Organisationen, die Sie freigegeben haben; organisation_id in der Nachricht ordnet sie zu. Die Signatur prüfen Sie wie oben.
• Getrennte Daten: Organisationen sind strikt getrennt. Eine externe Kennung darf in verschiedenen Organisationen gleich lauten.

Fehler & Grenzen

Jede Fehlerantwort hat dasselbe Format: code (maschinenlesbar und stabil — reagieren Sie darauf, nicht auf Texte), message (lesbare Meldung), request_id (wie der Kopf X-Request-ID) und detail mit den Einzelheiten, etwa detail.vorhanden_id oder der Liste ungültiger Eingaben. Der Tokenendpunkt antwortet nach RFC 6749 mit error und error_description.

{
  "code": "externe_id_vergeben",
  "message": "Diese externe Kennung ist in der Organisation bereits vergeben.",
  "request_id": "4dd50eff1abe",
  "detail": { "code": "externe_id_vergeben", "externe_id": "M-100", "vorhanden_id": "…" }
}

Anfragen je Zugang sind begrenzt (Vorgabe: 600 pro Minute, für Uploads und Importe weniger), die Tokenausgabe ebenso. Bei 429 — auch slow_down vom Tokenendpunkt — nennt Retry-After die Wartezeit in Sekunden.

Endpunkt-Referenz

Checkliste vor dem Produktivgang

• Geheimnis nur serverseitig bzw. im Tresor abgelegt, nicht im Quelltext
• IP-Freigabe mit den festen Adressen Ihres Servers angefragt (beim Inhaber, beim Partner-Zugang beim Betreiber)
• Nur die nötigen Rechte beantragt (loeschen, elster, ki nur bei Bedarf)
• Token wird vor Ablauf bzw. nach 401 automatisch erneuert
• Jede ändernde Anfrage mit Idempotency-Key, Wiederholung mit demselben Schlüssel
• Eigene Nummern als externe_id, 409 mit vorhanden_id behandelt
• 429 (auch slow_down beim Token), Retry-After und 409 (Version) behandelt
• Fehler über code ausgewertet, request_id mitprotokolliert
• Webhook-Signatur und Zeitabweichung werden geprüft, Doppel über die Ereignis-Kennung erkannt
• X-Request-ID wird in Ihren Protokollen mitgeschrieben