BPP Partner API Guidelines

Zielgruppe: Drittanbieter (Versicherungsplattformen, Versicherer, Daten-Hubs), die eine API bereitstellen, gegen die das BPP-System integriert.
Version: 1.1
Datum: 05.11.26
Referenzspezifikation: bpp-partner-api.openapi.yaml

Teil A — Anforderungen an eine BPP-kompatible Partner-API

1. Spec-Veröffentlichung & Versionierung (PUB)

• PUB-01 (MUSS) Die OpenAPI-Spec unter einer stabilen, anbietereigenen URL veröffentlichen, die Umbenennungen von Anbieter/Plattform übersteht. Bei Hosting auf SwaggerHub o.ä. MÜSSEN breaking Slug-/URL-Änderungen vorab angekündigt und weitergeleitet werden.
• PUB-02 (MUSS) GET /meta/version bereitstellen, das { apiVersion, specVersion } zurückgibt.
• PUB-03 (MUSS) Die API mit semver versionieren. Breaking Changes erfordern eine neue Major-Version, einen Changelog-Eintrag und eine veröffentlichte Abkündigungsrichtlinie (Vorankündigungsfenster, Sunset-Datum).
• PUB-05 (MUSS) Die Spec MUSS schemakorrekt sein: Listen-Responses als Arrays typisiert, Zahlen als Zahlen typisiert, jedes Response-Body-Schema vorhanden.

2. Authentifizierung (AUTH)

• AUTH-01 (MUSS) Einen dokumentierten, standardkonformen Authentifizierungsmechanismus anbieten. OAuth2 Client-Credentials, gescopte API-Keys oder ein Username/Password-(Resource-Owner-)Grant sind allesamt akzeptabel. BPP speichert Drittanbieter-Credentials sicher pro Mandant und pro Endbenutzer (goUser).
• AUTH-03 (MUSS) Klar unterschiedliche 401 (nicht authentifiziert/abgelaufen) vs. 403 (authentifiziert, aber verboten) zurückgeben, jeweils mit einem stabilen maschinellen Grund-Code — niemals ein undurchsichtiger INVALID_CREDENTIALS-String für jeden Fehlermodus.
• AUTH-04 (MUSS) Token-Lebensdauer und Refresh-Modell dokumentieren. Token-TTL SOLLTE ≥ 15 Minuten betragen; TTLs unter 5 Minuten erzwingen aggressive Re-Auth während Bulk-Syncs.
• AUTH-06 (SOLLTE) Standard-TLS auf Standard-Ports mit öffentlich vertrauenswürdigen Zertifikaten verwenden.
• AUTH-07 (MUSS) Die Integrationsdokumentation beschreibt den vollständigen Authentifizierungs-Flow eindeutig: ob ein Client-Zertifikat (mTLS) erforderlich ist und wie es zu beziehen/installieren ist; wie sich ein Konsument (BPP) gegen die API registriert/anmeldet; wie ein Access-Token bezogen wird (Token-Endpoint-URL, Grant-Type, erforderliche Credentials/Parameter sowie ein Beispiel-Request und -Response); und Token-Lebensdauer plus Refresh-/Erneuerungsverhalten.

3. Scope (SCOPE)

• SCOPE-01 (MUSS) Jeder Endpoint gibt eindeutig an, ob er im Mandanten-Scope (der gesamte Mandant) oder im goUser-Scope (nur die Daten des authentifizierten Benutzers) arbeitet. Beispielsweise muss explizit sein, ob GET /catalogs die Code-Listen des gesamten Mandanten zurückgibt oder nur die für den authentifizierten goUser sichtbaren. Kein Endpoint darf die Sichtbarkeit der von ihm zurückgegebenen Daten mehrdeutig lassen.
• SCOPE-02 (SOLLTE) Das Scoping-Modell ist über die API hinweg einheitlich. Wo ein Endpoint beide Scopes bedienen könnte, ist die Auswahl explizit — ein dokumentierter Parameter oder Token-Claim — nie implizit oder abgeleitet.

4. Allgemeine Datenkonventionen (GEN)

• GEN-01 (MUSS) Alle Datums- und Zeitangaben sind ISO 8601 — date (YYYY-MM-DD) oder UTC date-time mit explizitem Offset. Niemals Locale-Formate (dd.MM.yyyy), niemals zonenlose Lokalzeit, einheitlich über jedes Feld und jeden Endpoint hinweg.
• GEN-02 (MUSS) Geld- und Dezimalwerte sind JSON-Zahlen (oder dokumentierte Strings mit fester Genauigkeit) mit deklarierter Skala und einem expliziten Währungsfeld. Keine formfreien Strings.
• GEN-03 (MUSS) Fehlende/unbekannte Werte sind JSON-null oder ausgelassene Felder — niemals Leerstrings und niemals magischer Platzhaltertext ("k.A."). Wird ein Feld befüllt, aber zurückgehalten (Berechtigungen), ist das explizit zu kennzeichnen. Felder, die im Schema nicht als nullable markiert sind, MÜSSEN immer einen Wert haben — ohne Ausnahme.
• GEN-04 (MUSS) Für jedes String-Feld eine maximale Länge und einen Zeichensatz dokumentieren, damit Konsumenten Speicher ohne verlustbehaftetes Abschneiden dimensionieren können. Der Server DARF Werte, die er speichert oder zurückgibt, NICHT stillschweigend abschneiden.
• GEN-05 (MUSS) Feste Aufzählungen (Geschlecht, Zahlungsintervall, …) verwenden dokumentierte geschlossene Code-Sets, keine lokalisierten Anzeigestrings. Mandantendefinierbare Domänen fallen unter CAT (§7).
• GEN-06 (MUSS) Erforderliche Stammdatenfelder (z.B. Kundenname) sind entweder garantiert befüllt oder explizit als unbekannt gekennzeichnet.
• GEN-07 (MUSS) Wo immer eine Prämie zurückgegeben wird, MUSS eindeutig sein, was der Wert darstellt: die Währung sowie ob es sich um einen Netto- und/oder Brutto-Betrag handelt. Wird nur einer von Netto/Brutto zurückgegeben, MUSS die Response angeben, welcher es ist, und den angewandten Versicherungssteuersatz, damit der Konsument den fehlenden Wert berechnen kann.
• GEN-08 (MUSS) Schreib-Repräsentationen sind symmetrisch zu Lese-Repräsentationen: Ein Request-Body akzeptiert jedes Enum- und Datums-/Zeitfeld in exakt der Form, in der die API es ausgibt — gleiche Groß-/Kleinschreibung, gleiches Datums-/Zeitformat. Kein Feld, das "als ISO 8601 mit Offset liest, aber nur zonenlose Lokalzeit akzeptiert"; kein Feld, das "PascalCase ausgibt, aber nur camelCase akzeptiert". Ein von der API gelesener und wortwörtlich zurückgeschickter Wert MUSS akzeptiert werden. Ein unbekannter oder falsch geschriebener Wert für eine feste Aufzählung wird mit einem stabilen Code abgelehnt, der die erlaubten Werte aufzählt (ERR-03).

5. Identifikatoren (ID)

• ID-01 (MUSS) Jede Ressource — einschließlich jedes verschachtelten/untergeordneten Objekts (Beteiligte, Risiken, Sparten, Adressen, Bankverbindungen) — trägt ihre eigene global eindeutige, unveränderliche, nie wiederverwendete Primär-ID, non-null in jeder Repräsentation.
• ID-02 (MUSS) IDs sind case-stabil und byte-stabil über Responses hinweg. Dieselbe reale Entität erscheint stets unter derselben ID; Konsumenten rekonstruieren Identität nie über Name/Geburtsdatum-Matching oder Listenposition.
• ID-03 (MUSS) Verschachtelte Referenzen tragen die ID plus genügend denormalisierte Identität, um ohne N+1-Lookup zu rendern und zu deduplizieren (z.B. enthält eine Referenz auf eine versicherte Person displayName und birthDate, nicht nur personId).

6. Metadaten-Block (META)

• META-01 (MUSS) Jede Ressource gibt ein einheitliches metadata-Objekt zurück:

  {
    "createdAt": "2026-01-10T08:30:00Z",
    "updatedAt": "2026-07-01T14:12:05Z",
    "createdBy": { "id": "u-1042", "displayName": "M. Huber" },
    "updatedBy": { "id": "u-1042", "displayName": "M. Huber" }
  }
  

• META-02 (MUSS) createdAt/updatedAt sind non-null, serverseitig zugewiesen, UTC, und updatedAt ist monoton — es steigt bei jeder Mutation der Ressource.

• META-04 (SOLLTE) createdBy/updatedBy tragen eine stabile Akteur-ID + Anzeigenamen, damit Audit-Spalten auf der BPP-Seite nicht erfunden werden müssen.

7. Dynamische Kataloge (CAT)

Gilt für jede Wertedomäne, die die Mandanten des Anbieters zur Laufzeit dynamisch definieren oder bearbeiten können: Dokumenttypen, Vertrags-/Schadenstatus, Produkt-/Spartentypen, Versichererlisten, Beteiligtenrollen usw.

• CAT-01 (MUSS) Jede dynamische Domäne ist über einen Katalog-Endpoint auffindbar — GET /catalogs (Liste der Domänen) und GET /catalogs/{domain} — und gibt alle aktuell definierten Werte zurück als:

  { "code": "invoice", "label": "Honorarnote / Rechnung an VN", "active": true }
  

  plus ein katalogweites updatedAt/version. Integratoren holen den Katalog, statt Schreibweisen hart zu codieren.

• CAT-02 (MUSS) Datensätze referenzieren einen Domänenwert über seinen stabilen, unveränderlichen code — nie über ein lokalisiertes Anzeige-Label. Labels dürfen jederzeit umbenannt/gekürzt werden; Codes nicht.

• CAT-03 (MUSS) Schreibvorgänge werden gegen denselben Katalog validiert, und eine Ablehnung benennt den beanstandeten Wert und zählt im Fehler-Body die erlaubten Codes auf (siehe ERR-03).

• CAT-04 (DARF NICHT) Katalog-Labels werden vom Server nie stillschweigend abgeschnitten.

• CAT-05 (SOLLTE) Deaktivierte Werte bleiben auflösbar (active: false), damit historische Datensätze weiterhin mappen; neue Schreibvorgänge mit inaktiven Codes werden gemäß CAT-03 abgelehnt.

8. Delta-Sync & Änderungserkennung (SYNC)

BPP synchronisiert den gesamten Bestand nächtlich und auf Anforderung. Voll-Rescans existieren nur, weil Delta-Pfade meist fehlen — eine ideale API macht sie überflüssig.

• SYNC-01 (MUSS) Jeder Entitätstyp (Kunden, Verträge, Risiken, Schäden, Dokumente) stellt einen Delta-Pfad bereit — GET …?updatedSince=<ISO8601>, der vollständige Ressourcen-Repräsentationen (oder mindestens { id, updatedAt, version }) zurückgibt, stabil sortiert nach (updatedAt, id). Das Delta KANN über einen Top-Level-Feed (GET /{entity}?updatedSince=…) oder über eine Liste im besitzenden Scope (z.B. GET /customers/{customerId}/risks?updatedSince=…) bereitgestellt werden; die Spec MUSS pro Entitätstyp den maßgeblichen Delta-Pfad benennen. updatedSince umfasst auch Neuanlagen (createdAt setzt updatedAt); Löschungen signalisiert der Lösch-Feed GET /deletions (DEL-04).
• SYNC-02 (MUSS) updatedSince ist wiederholbar — ein erneuter Lauf mit demselben Watermark ist sicher und selbstheilend nach einem verpassten Lauf.
• SYNC-03 (MUSS) Das Fehlen eines Zeitstempels ist nie das Änderungssignal. Ein Datensatz ohne updatedAt ist eine Spec-Verletzung, nicht "unverändert" und nicht "verändert" (siehe META-02).
• SYNC-04 (SOLLTE) Für Dokumente enthält der Delta-Feed sha256, damit Konsumenten unveränderte Binärdaten deterministisch überspringen können (siehe DOC-02).

9. Löschungen & Merges (DEL)

BPP löst im Partnersystem niemals Löschungen aus: keine anbieterseitige, von BPP aufrufbare DELETE-Operation ist erforderlich, und diese Spec definiert keine. Stattdessen MUSS die Spec festlegen, was Konsumenten beobachten, wenn ein Eintrag anbieterseitig gelöscht wird.

• DEL-01 (MUSS) Anbieterseitige Löschungen werden über genau eine der beiden nachstehenden Strategien offengelegt, vom Anbieter gewählt und einheitlich über jeden Entitätstyp hinweg angewandt (Kunden, Verträge, Risiken, Schäden, Dokumente). Strategien pro Entitätstyp zu mischen ist eine Verletzung. BPP beobachtet Löschungen nur — es löst sie nie aus —, sodass kein DELETE-Endpoint erforderlich ist.
  • Strategie A — maßgebliche Liste: Der nächste Abruf des besitzenden Scopes liefert die vollständige aktuelle Menge, sodass Fehlen = gelöscht. Beispiel: Ein Kunde hat 5 Verträge im Anbietersystem und einer wird dort gelöscht — der nächste Abruf der Verträge dieses Kunden liefert genau die verbleibenden 4. Nur gültig, wenn Listen vollständig sind (keine stillen Obergrenzen — siehe PAGE-03).
  • Strategie B — Soft-Delete-Marker: Gelöschte Einträge bleiben abrufbar und sind in metadata klar gekennzeichnet (deletedAt-Zeitstempel und/oder status: deleted), auch in updatedSince-Delta-Feeds — die Löschung erhöht updatedAt, sodass Delta-Konsumenten sie sehen.
• DEL-02 (MUSS) Ein GET auf eine gelöschte ID gibt 410 Gone zurück (oder 404 mit einem stabilen code, der "nie existiert" / "gelöscht" / "zusammengeführt in X" unterscheidet) — deterministisch, nie zu 401 oder einem anderen Status für dieselbe Bedingung driftend. Gilt unter beiden Strategien.
• DEL-03 (SOLLTE) Merges legen die überlebende ID (mergedIntoId) offen, damit Konsumenten neu verlinken können, statt Daten zu verwaisen. Bewusst SOLLTE statt MUSS: kein beobachteter Vorfall erzwingt es — aber ohne mergedIntoId ist ein anbieterseitiger Merge (z.B. Dubletten-Bereinigung) von einer einfachen Löschung nicht unterscheidbar, und der Konsument löscht/verwaist verknüpfte Daten, statt sie auf die überlebende ID umzuhängen.
• DEL-04 (MUSS bei Strategie A, SOLLTE bei Strategie B) Ein Lösch-Feed GET /deletions?deletedSince=<ISO8601>&entityType=…, der { entityType, id, deletedAt, mergedIntoId? } zurückgibt. Bei Strategie A ist er verpflichtend, weil eine Löschung dort für updatedSince-Konsumenten sonst unsichtbar ist (Fehlen erhöht nie einen Watermark). Bei Strategie B SOLLTE er angeboten werden — er deckt endgültige Hard-Deletes ab (z.B. DSGVO-Löschung), die den Soft-Delete-Eintrag entfernen.

10. Collections, Rollen & Pagination (PAGE / ROLE)

• PAGE-01 (MUSS) Listen-Endpoints geben ein wohlgeformtes JSON-Array plus einen typisierten Pagination-Envelope zurück: { items: [...], page: { nextCursor, hasMore, total } } mit ganzzahligem total und explizitem hasMore.
• PAGE-02 (MUSS) Pagination ist cursorbasiert (opakes nextCursor) mit dokumentierter, stabiler Sortierung; Offset-Paging, falls angeboten, dokumentiert sein Konsistenzmodell.
• PAGE-03 (MUSS) Listen begrenzen Ergebnisse nie stillschweigend und dokumentieren jede Feld-Projektion gegenüber der Detail-Ressource. Was die Liste als existent ausweist, existiert.
• ROLE-01 (MUSS) Eine Collection ist nach dem benannt, was sie tatsächlich enthält. Ein Feld namens insuredPersons enthält nur versicherte Personen — eine gemischte Beteiligtenliste heißt participants, und jedes Element trägt einen expliziten role-Code aus einem veröffentlichten Katalog (CAT-01) mit dokumentierter Semantik.
• ROLE-02 (SOLLTE) Rollen-Vokabulare sind kontextübergreifend konsistent (Vertragsbeteiligte vs. Kundenbeziehungen) oder explizit querverwiesen — keine parallelen Enums für dasselbe Konzept.

Kunden-Unter-Collections (Adressen, Bankverbindungen, Kontaktinfos) tragen einen isDefault-Boolean: höchstens ein Eintrag pro Collection ist der aktuelle Default (isDefault: true), Nicht-Default-Einträge bleiben auflösbar. Jede Unter-Collection bietet einen Detail-Endpoint (GET /customers/{customerId}/addresses/{addressId}, …). Risiken eines Kunden: GET/POST /customers/{customerId}/risks, PUT …/risks/{riskId} partiell (fehlendes Feld = unverändert, typeCode unveränderlich, optionales If-Match — IDEM-04).

Kunden sind beschreibbar: POST /customers legt einen Kunden atomar an — optional samt ersten Adressen, Bankverbindungen und Kontaktinfos im selben Body (die 201-Antwort liefert die Kind-Einträge in Request-Reihenfolge zur einmaligen id-Übernahme); PUT /customers/{customerId} aktualisiert partiell (customerType unveränderlich, Unter-Collections nicht Teil des Bodys). Jede Unter-Collection bietet POST /customers/{customerId}/addresses (bzw. …/bank-accounts, …/contact-infos) und PUT …/{id} partiell mit optionalem If-Match (IDEM-04); iban ist unveränderlich (andere IBAN = neues Konto). isDefault: true macht einen Eintrag zum Default und setzt den bisherigen im selben Schreibvorgang auf false; ohne isDefault: true ändert der Server den Default nie von sich aus (auch nicht beim ersten Eintrag). Jede Änderung an einer Unter-Collection — über die API oder anbieterseitig, einschließlich der Entfernung eines Eintrags — erhöht metadata.updatedAt des Kunden; maßgeblicher Delta-Pfad der Unter-Collections ist damit GET /customers?updatedSince=… (SYNC-01). Doppelte IBANs pro Kunde werden abgelehnt (IDEM-03). Rechtsform (legalFormCode) und Region (regionCode) referenzieren die Kataloge legalForms bzw. regions (CAT-01..05) — nie Freitext; regions enthält die österreichischen und deutschen Bundesländer mit ihrem ISO-3166-2-Code als code (AT-1 … AT-9, DE-BW … DE-TH), und ein regionCode MUSS zu countryCode passen.

11. Dokumente (DOC)

• DOC-01 (MUSS) Dokument-Metadaten sind vor dem Download der Binärdaten vollständig bekannt. Listen-/Detail-Metadaten enthalten: id, fileName, sizeBytes, mimeType, sha256, documentTypeCode, createdAt, updatedAt und die Links zur besitzenden Entität. mimeType ist maßgebliche Server-Wahrheit, nicht aus dem Dateinamen abgeleitet.
• DOC-02 (MUSS) Die Binärdaten liegen an einem separaten Endpoint (GET /documents/{id}/content), der HEAD (Größe/Hash/Mime via Header) und HTTP-Range-Anfragen unterstützt. Die Übertragung erfolgt gestreamt als application/octet-stream / multipart mit Content-Length; base64-in-JSON ist für kleine Dateien (z.B. Antrags-PDFs) akzeptabel.
• DOC-03 (MUSS) documentId ist über die Lebensdauer des Dokuments stabil und unveränderlich; sha256/version ändert sich genau dann, wenn sich der Inhalt ändert, sodass "ersetzt" vs. "neues Dokument" eindeutig ist.
• DOC-05 (MUSS) Dokumenttypen folgen CAT-01..05 (Katalog-Endpoint mit stabilen Codes; Upload-Ablehnung listet erlaubte Codes auf).
• DOC-06 (MUSS) Die erlaubten MIME-Typen für den Upload (eine dokumentierte Liste), die maximale Upload-Größe und Request-Timeouts sind in der Spec veröffentlicht. Bei Verletzung gibt der Server einen deterministischen Status mit einem stabilen maschinellen Code zurück (413 bei zu großer Payload, 422 bei unzulässigem MIME-Typ) und meldet das überschrittene Limit bzw. die erlaubte Menge im Fehler-Envelope zurück.
• DOC-07 (SOLLTE) Für sehr große Dateien SOLLTE die API einen Streaming-Download-Endpoint anbieten (Chunked Transfer, fortsetzbar via HTTP-Range), damit Integratoren nie ganze Dateien im Speicher puffern. Das Verhalten DARF NICHT mit der Dateigröße variieren, und die veröffentlichte Maximalgröße (DOC-06) gilt weiterhin.
• DOC-08 (MUSS) Dokument-Metadaten geben den Besitzer an: Mindestens eine von customerId, contractId, claimId ist gesetzt; Konsumenten verlinken über die spezifischste non-null ID (claimId → contractId → customerId). Nur claimId bei einem Schadendokument genügt — der Konsument löst über Schaden → Vertrag → Kunde auf (Implementierer-Wahl). Ein Upload ohne jede Besitzer-ID wird abgelehnt (422, stabiler Code).
• DOC-09 (SOLLTE) Für sehr große Dateien einen fortsetzbaren, chunked Upload-Pfad anbieten (initialisieren → Chunks → finalisieren; Gegenstück zu DOC-07). Das Verhalten variiert nicht mit der Dateigröße; die Maximalgröße (DOC-06) gilt weiterhin.

12. Fehlermodell (ERR)

• ERR-01 (MUSS) Fehler sind RFC 7807 application/problem+json: type, title, status, menschenlesbares detail, plus ein stabiler maschineller code aus einem dokumentierten Katalog (keine opaken P0001-artigen Codes, die nur der Support des Anbieters entschlüsseln kann).
• ERR-02 (MUSS) HTTP-Statusklassen werden korrekt und deterministisch verwendet: Not-Found ist 404/410, Validierung ist 400/422, Auth ist 401/403. Dasselbe logische Versagen mappt stets auf denselben Status — Business-Fehler werden nie in 200-Bodies geschmuggelt, und dauerhafte vs. transiente Fehler sind unterscheidbar, damit Konsumenten wissen, was retry-fähig ist.
• ERR-03 (MUSS) Validierungsfehler tragen errors[] aus { field, code, message }; Katalogwert-Ablehnungen enthalten den abgelehnten Wert und die allowedCodes (CAT-03). Schlägt ein Write-Back fehl (z.B. eine Schadenanlage via POST /claims aus BPP), benennt die Response konkret, welches Feld warum beanstandet wurde — nie nur ein generischer Validierungsfehler.
• ERR-04 (SOLLTE) Der vollständige Fehlercode-Katalog wird zusammen mit der Spec veröffentlicht, inklusive, welche Codes terminal vs. retry-fähig sind.

13. Rate Limits, Retries & Idempotenz (RATE / IDEM)

• RATE-01 (MUSS) Rate Limits sind dokumentiert (pro Sekunde/Burst, pro Mandant vs. global). Throttling gibt 429 mit Retry-After- und RateLimit-*-Headern zurück — Konsumenten sollten nie blinde feste Verzögerungen justieren müssen.
• RATE-02 (SOLLTE) Aktuelles Kontingent/Verbrauch ist abfragbar, damit ein Bulk-Sync sich selbst takten kann.
• RATE-03 (MUSS) Die Dokumentation gibt an, ob Rate Limits serverseitig aktiv sind und wie restriktiv sie sind — konkrete Zahlen (Requests/Sekunde, Burst, pro Mandant vs. global) und etwaige Implikationen für Bulk-/Nacht-Syncs. "Keine Limits" MUSS explizit angegeben werden; Schweigen ist keine Antwort. Konsumenten dimensionieren ihre Sync-Concurrency direkt aus dieser Angabe.
• IDEM-01 (MUSS) Alle Schreibvorgänge (POST/PUT) akzeptieren einen Idempotency-Key-Header und geben bei Replay das ursprüngliche Ergebnis zurück — sodass eine wiederholte Anfrage mit identen Werten nach einem Netzwerk-Aussetzer nie ein Duplikat erzeugen kann.
• IDEM-02 (MUSS) Was gerade geschrieben wurde, ist sofort lesbar: Eine neu erstellte Ressource ist unmittelbar per ID abrufbar und erscheint in Listen — oder die Verzögerung ist dokumentiert und begrenzt.
• IDEM-03 (MUSS) Die API gibt nie Duplikat-Ressourcen für denselben natürlichen Schlüssel zurück (keine doppelten IBANs, doppelten Beziehungen, doppelten Beteiligten) — Dedup ist Aufgabe des Anbieters, nicht des Konsumenten.
• IDEM-04 (MUSS) Jede Update-Operation dokumentiert eindeutig: partiell (fehlendes Feld = unverändert) oder Voll-Ersetzung, wie verschachtelte Collections behandelt werden (Elemente mit ID / ohne ID / fehlende Elemente), und ob If-Match/ETag unterstützt wird (veralteter Schreibvorgang → 412 + resource.versionConflict).

14. Umgebungen, Health & Betrieb (ENV / OPS)

• ENV-01 (MUSS) Eine erreichbare Sandbox mit repräsentativen, zurücksetzbaren Testdaten und klar getrennten Credentials. Die Sandbox ist strikt von der Produktion isoliert, sodass e2e-Schreibtests gegen die Sandbox nie Produktionsdaten verschmutzen können.
• ENV-02 (SOLLTE) Sandbox und Produktion laufen mit derselben API-Version, wobei die Sandbox kommende Versionen zuerst erhält.
• ENV-03 (MUSS) Die vollständige API-Oberfläche ist in der Sandbox end-to-end ausführbar — Lese-, Aktualisierungs- und Write-Back-Endpoints — jeweils testbar ohne jegliches Risiko für Produktionsdaten. Ein Konsument muss einen Schreibpfad (Anlegen/Aktualisieren/Upload) gegen die Sandbox validieren können, bevor er jemals die Produktion berührt.
• OPS-01 (MUSS) Unauthentifiziertes GET /health (Liveness) plus ein Readiness-/Status-Endpoint, der den Zustand pro Subsystem meldet.
• OPS-02 (SOLLTE) Eine öffentliche Statusseite mit abonnierbarem Incident-Feed; Wartungsfenster werden vorab angekündigt und als maschinenlesbares Signal offengelegt, das ein Client vor dem Start eines Bulk-Laufs abfragen kann.
• OPS-03 (SOLLTE) Latenz- und Timeout-Erwartungen pro Endpoint sind veröffentlicht (typisch, Worst-Case, serverseitiges Request-Timeout), damit Konsumenten Client-Timeouts und fortsetzbare Bulk-Läufe dimensionieren können.

Teil B — Häufig beobachtete Fallstricke

Aus rund zwei Jahren Produktionsintegration realer Drittanbieter-APIs. Jeder Fallstrick ist das "Warum" hinter den referenzierten Anforderungen in Teil A.