gRPC

The Synchro Service is a gRPC server first: the REST gateway translates each HTTP call into the same RPC. Calling gRPC directly gives you typed clients generated from our .proto files.

Endpoint

Address	synchro.api.external-integration.ubikap.dev:443
Transport	HTTP/2 over TLS — plaintext is not accepted
REST gateway	https://synchro.api.external-integration.ubikap.dev, same host

Services

Service	RPCs	Token
services.authentication.v1.AuthenticationService	LogIn	None
services.synchronization.v1.SynchronizationService	PostAsyncTasks, GetSynchroState, GetGlobalSynchroState	Office token

Over REST, LogIn and PostAsyncTasks are POST requests with a JSON body; GetSynchroState and GetGlobalSynchroState are GET requests with their fields in the query string, nested fields joined by dots (?filter.workspace.externalId=4242).

Proto files

Download the .proto files. The archive holds:

• services/<service>/v1/<service>_service.proto, one file per service, in the package services.<service>.v1;
• buf.yaml and buf.lock, which pin the two imported dependencies: google/api/annotations.proto (googleapis) and buf/validate/validate.proto (protovalidate).

With buf, buf generate resolves those dependencies by itself: see Getting Started for a TypeScript client. The archive is rebuilt with every release of these docs; download it again when the changelog announces a change.

Server reflection

The server implements gRPC server reflection, under both grpc.reflection.v1 and grpc.reflection.v1alpha. Tools such as grpcurl and Postman can list the two services, describe the messages and build requests without the .proto files.

Authentication

Call services.authentication.v1.AuthenticationService/LogIn first, then send the token it returns in the metadata of every other call:

authorization: Bearer <token>

See Authentication for the login fields and the token’s scope.

Status codes

Errors carry a gRPC status code and a message describing the problem. The REST gateway answers the matching HTTP status.

gRPC status	Code	HTTP (REST)	Typical cause
INVALID_ARGUMENT	3	400	Invalid input, wrong TOTP code, unknown office, task type not implemented.
UNAUTHENTICATED	16	401	Missing or expired token.
PERMISSION_DENIED	7	403	No access to the office, or to the RPC.
NOT_FOUND	5	404	The requested resource does not exist.
INTERNAL	13	500	Unexpected server error, or a user that is not set up as a synchronization partner: contact us if it persists.
CANCELLED	1	499	The client cancelled the call or its deadline expired.
UNKNOWN	2	500	Any other error.

Every RPC answers quickly — the synchronization itself runs in the background — so set a short deadline on every call (e.g. 30 seconds).

Messages

Messages are proto3. Through the REST gateway, the same messages are JSON with camelCase field names (synchronization_id becomes synchronizationId).

• Enums are written as their names, in lower camel case: "pending", "synchronizeStockholders".
• The int64 counters of GetSynchroState (pendingCount, …) are JSON strings ("3"), as protobuf’s JSON mapping requires.
• Dates (createdAt, updatedAt, date) are ISO 8601 strings.

Recipes: Call the service with grpcurl or Postman.