AI translation
This page was translated from German with AI. If in doubt, the German original applies.
API reference¶
The ZEDAL platform provides its functionality as a family of gRPC services. You can reach them via three paths that lead to the same backend methods:
| Access path | What for | Reference |
|---|---|---|
| REST / JSON | Any language with an HTTP client, no codegen required. Not the full feature set — some of the import and delivery operations are missing. | openapi.live.zedal.de — 131 operations |
| gRPC | Type safety, code generation, server streaming | .proto definitions |
| .NET SDK | C# applications — encapsulates auth, retries, document handling | Zedal.Sdk on NuGet |
Existing integrations via the older SOAP web service are described under SOAP (legacy); it is no longer extended.
In all three cases, the .proto definitions are authoritative: REST routes and the OpenAPI document are derived from them at runtime, and the SDK is generated from them.
What is documented where¶
The generated reference describes signatures — which operations exist, which fields a message has, which type a field carries. It does not describe which values are permitted in business terms and which additional rules the server enforces. There are two separate chapters for that:
- Field rules — formats, required fields beyond the schema, value ranges
- Error codes — what a rejection means and what to do
If you are assembling a submission, you need both. The schema alone is not enough to produce a valid document.
Environments¶
| Environment | gRPC (native) | REST / JSON and 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 |
| Development | api.dev.zedal.de |
openapi.dev.zedal.de |
REST/JSON and gRPC-Web run over the same host (openapi.*), native gRPC over api.*. In the .NET SDK, you select the environment via TargetSystem; the SDK sets the addresses itself.
Authentication¶
All three paths use the same token model: a long-lived refresh token from the login, from which a short-lived access token is obtained each time for the actual calls. Details and the complete flow are in Getting started.
Versioning¶
Changes are made exclusively at the proto level. The proto packages follow Semantic Versioning; deprecations are annotated in the proto and tracked in the Changelog.
Deprecations are not visible in the OpenAPI document
A method marked as deprecated in the proto does not appear as deprecated in the generated OpenAPI reference — currently not a single operation is marked that way there, even though the contract contains deprecated methods.
For the deprecation status, therefore, do not rely on the REST reference but on the Changelog.