Skip to content

AI translation

This page was translated from German with AI. If in doubt, the German original applies.

gRPC

Native gRPC is the direct path to the platform: type safety through generated stubs, server streaming and the lowest transfer overhead. The .proto definitions are the authoritative specification — REST and the .NET SDK are derived from them.

Endpoints

Environment Native gRPC (HTTP/2) 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

Both paths lead to the same backend methods. gRPC-Web does not run over the native host, but over openapi.* — that is where the gRPC-Web framing is translated and server streaming is delivered incrementally. Browser clients use this path.

Authentication

The same three-stage token model as with REST, except that the values are in the gRPC metadata instead of HTTP headers:

authorization: Bearer <access-token>
provider_id:   <id>

provider_id belongs on every call, including the login. The .NET SDK sets the metadata itself as soon as the provider is known — if you build directly against gRPC, you have to supply it.

Login (AuthApi/IssueRefreshToken) and obtaining access (AuthApi/RequestAccess) are regular gRPC methods. The flow, including token rotation and the role of DiscoveryApi/ListProvider, is described under REST → Authentication and applies unchanged.

Services

Service Responsibility
AuthApi Login, tokens, sessions, client IDs
DocumentApi, DocumentTemplateApi Documents: import, export, inbox, parameters
FileApi File operations
CommonApi, MasterdataApi Global parameters, master data
CompanyDocumentApi DIWASS from the company perspective — Notification, Movement, Annex VII
AuthorityDocumentApi DIWASS from the authority perspective — Acknowledgement, Decision, signals
OperatorApi, AuthorityApi DIWASS directory: operator and authority search
RetrievalApi, AttachmentApi DIWASS retrieval and attachments
BmuDocumentApi BMU consignment notes and acceptance notes under the NachwV: create, append layers, set fields, signature positions; see BMU guide
DiscoveryApi Provider discovery

The complete list of all operations with signatures is in the REST reference — it is generated from the same protos and matches the gRPC contract exactly.

Streaming

Server streaming is available natively and via gRPC-Web. Not via REST/JSON — that path is unary.

Timeouts

Set deadlines according to the expected payload, not across the board. Calls that are forwarded to DIWASS on the server side need considerably more time than pure platform operations — concrete guideline values are in the DIWASS guides. A tight default produces DEADLINE_EXCEEDED, which looks like a server error but is not one.

Obtaining the proto definitions

The .proto files are available as a ZIP under Proto definitions, together with an example for code generation. For .NET, the generated contract is available as the NuGet package Zedal.GrpcApis; the .NET SDK includes it as a dependency.

For other languages, you generate the stubs from the protos yourself — or you use REST and skip that step.

Next