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

curl -s -X POST https://www.steuersoft.online/api/v1/mandanten \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.
• IP-Freigabe: Der Zugang kann auf feste Adressen oder Netze beschränkt sein. Anfragen von anderswo werden mit 403 abgewiesen.
• Gültigkeit: Zugänge laufen nach der vereinbarten Frist ab und 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 (api:stsc_…), wenn Ihr Programm die Änderung selbst ausgelöst hat.
• 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.
• 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

Fehlerantworten tragen detail mit einer lesbaren Meldung. Der Tokenendpunkt antwortet nach RFC 6749 mit error und error_description.

Anfragen je Zugang sind begrenzt (Vorgabe: 600 pro Minute, für Uploads weniger). Bei 429 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 beim Inhaber angefragt
• 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, Retry-After und 409 (Version) behandelt
• Webhook-Signatur und Zeitabweichung werden geprüft, Doppel über die Ereignis-Kennung erkannt
• X-Request-ID wird in Ihren Protokollen mitgeschrieben