API-Referenz¶
Die ZEDAL-Plattform stellt ihre Funktionalität als Familie von gRPC-Diensten bereit. Du erreichst sie auf drei Wegen, die auf dieselben Backend-Methoden führen:
| Zugriffsweg | Wofür | Referenz |
|---|---|---|
| REST / JSON | Jede Sprache mit HTTP-Client, kein Codegen nötig. Nicht der volle Funktionsumfang — ein Teil der Import- und Zustell-Operationen fehlt. | openapi.live.zedal.de — 131 Operationen |
| gRPC | Type-Safety, Code-Generierung, Server-Streaming | .proto-Definitionen |
| .NET SDK | C#-Anwendungen — kapselt Auth, Retries, Dokument-Handling | Zedal.Sdk auf NuGet |
Bestehende Integrationen über den älteren SOAP-Webservice beschreibt SOAP (Legacy); er wird nicht mehr erweitert.
Maßgeblich sind in allen drei Fällen die .proto-Definitionen: REST-Routen und OpenAPI-Dokument werden zur Laufzeit daraus abgeleitet, das SDK wird daraus generiert.
Was wo dokumentiert ist¶
Die generierte Referenz beschreibt Signaturen — welche Operation es gibt, welche Felder eine Nachricht hat, welcher Typ ein Feld trägt. Sie beschreibt nicht, welche Werte fachlich zulässig sind und welche Regeln der Server zusätzlich durchsetzt. Dafür gibt es zwei eigene Kapitel:
- Feldregeln — Formate, Pflichtfelder jenseits des Schemas, Wertebereiche
- Fehlercodes — was eine Ablehnung bedeutet und was zu tun ist
Wer eine Submission zusammenbaut, braucht beide. Das Schema allein reicht nicht aus, um ein gültiges Dokument zu erzeugen.
Umgebungen¶
| Umgebung | gRPC (nativ) | REST / JSON und gRPC-Web |
|---|---|---|
| Production | api.live.zedal.de |
openapi.live.zedal.de |
| Preview | api.preview.zedal.de |
openapi.preview.zedal.de |
| Test | api.test.zedal.de |
openapi.test.zedal.de |
REST/JSON und gRPC-Web laufen über denselben Host (openapi.*), natives gRPC über api.*. Im .NET SDK wählst du die Umgebung über TargetSystem, die Adressen setzt das SDK selbst.
Authentifizierung¶
Alle drei Wege nutzen dasselbe Token-Modell: ein langlebiges Refresh-Token aus dem Login, daraus jeweils ein kurzlebiges Access-Token für die eigentlichen Aufrufe. Details und der vollständige Ablauf stehen in Erste Schritte.
Versionierung¶
Änderungen erfolgen ausschließlich auf Proto-Ebene. Die Proto-Pakete folgen Semantic Versioning; Deprecations werden im Proto annotiert und im Changelog geführt.
Deprecations sind im OpenAPI-Dokument nicht sichtbar
Eine im Proto als veraltet markierte Methode erscheint in der generierten OpenAPI-Referenz nicht als deprecated — derzeit ist dort keine einzige Operation so gekennzeichnet, obwohl es im Vertrag veraltete Methoden gibt.
Verlass dich für den Abkündigungsstand deshalb nicht auf die REST-Referenz, sondern auf den Changelog.