Getting Started

This page generates a TypeScript gRPC client with ts-proto and @grpc/grpc-js. Any other gRPC toolchain works from the same proto files. To try the API without writing code, see Call the API with grpcurl or Postman.

Requirements

• Node.js 20 or later (or Bun);
• npm (or any other package manager);
• network access to the Buf Schema Registry, from which buf downloads the two proto dependencies.

Generate the client

1. Download the Public API .proto files and unzip them at the root of your project. The ubikap-public-api-proto/ folder holds the services, plus a buf.yaml and a buf.lock that pin their dependencies (googleapis, protovalidate).
2. Install the code generators and the runtime libraries:

npm install --save-dev @bufbuild/buf ts-proto
npm install @grpc/grpc-js @bufbuild/protobuf

3. Create ubikap-public-api-proto/buf.gen.yaml:

version: v2

clean: true

managed:
  enabled: true

plugins:
  - local: protoc-gen-ts_proto
    out: ../src/generated # Emptied before each generation
    strategy: all
    opt:
      - outputClientImpl=true
      - esModuleInterop=true
      - stringEnums=true

outputClientImpl=true generates a <Service>ClientImpl class per service. stringEnums=true types enums as their names ("REGISTER_ITEM_MINUTES"), as the REST gateway does.

4. Generate the client from the ubikap-public-api-proto/ folder. npx puts protoc-gen-ts_proto on the PATH for buf:

cd ubikap-public-api-proto
npx buf generate --template buf.gen.yaml .

The files are written to src/generated/, mirroring the proto paths: src/generated/services/authentication/v1/authentication_service.ts, and so on.

Note

The generated imports have no file extension. Compile them with "moduleResolution": "bundler" (or "node"), or add the importSuffix=.js option to buf.gen.yaml for "nodenext".

Call the API

1. Create the transport. ts-proto does not depend on any gRPC library: every generated client takes an rpc object, which you implement once on top of @grpc/grpc-js.

import * as grpc from '@grpc/grpc-js';

const connection = new grpc.Client('public.api.external-integration.ubikap.dev:443', grpc.credentials.createSsl());

const CALL_TIMEOUT_MS = 30_000;

interface Rpc {
  request(service: string, method: string, data: Uint8Array): Promise<Uint8Array>;
}

const makeRpc = (token?: string): Rpc => ({
  request: (service, method, data) => {
    const metadata = new grpc.Metadata();

    if (token) {
      metadata.set('authorization', `Bearer ${token}`);
    }

    return new Promise((resolve, reject) => {
      connection.makeUnaryRequest(
        // A gRPC method path is "/<package>.<Service>/<Method>"
        `/${service}/${method}`,
        (message: Uint8Array) => Buffer.from(message),
        (response: Buffer) => response,
        data,
        metadata,
        { deadline: Date.now() + CALL_TIMEOUT_MS },
        (error, response) => {
          if (error) {
            return reject(error);
          }

          resolve(response ?? Buffer.alloc(0));
        },
      );
    });
  },
});

2. Log in with your Public API user and the current TOTP code:

import { AuthenticationServiceClientImpl } from './generated/services/authentication/v1/authentication_service';

const authenticationService = new AuthenticationServiceClientImpl(makeRpc());

const { token } = await authenticationService.LogIn({
  officeScope: { target: { office: { key: 'OFC_1234' } } },
  userUuid: '01920000-0000-7000-8000-000000000000', // UUIDv7 given by Ubikap
  userCode: '12345678', // Current 8-digit TOTP code
});

3. Call an authenticated RPC with a client that carries the token:

import { RegisterServiceClientImpl } from './generated/services/register/v1/register_service';

const registerService = new RegisterServiceClientImpl(makeRpc(token));

const { registers } = await registerService.ListRegisters({ workspaceKey: 'acme7391_CP_42' });

A failed call rejects with a grpc.ServiceError, whose code is a gRPC status code. See Public API authentication for the token’s scope, expiry and errors.

Call the REST gateway

The Public API is served at https://public.api.external-integration.ubikap.dev, over gRPC and REST on the same host: see gRPC. Every RPC is also served over HTTP at /<package>.<Service>/<Method>, with a JSON body that uses the camelCase field names.

curl -X POST https://public.api.external-integration.ubikap.dev/services.authentication.v1.AuthenticationService/LogIn \
  -H 'Content-Type: application/json' \
  -d '{"officeScope":{"target":{"office":{"key":"OFC_1234"}}},"userUuid":"01920000-0000-7000-8000-000000000000","userCode":"12345678"}'

curl -X POST https://public.api.external-integration.ubikap.dev/services.file_object.v1.FileObjectService/Create \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{}'

The read-only RPCs (ListRegisters, GetCapitalizationTable) are GET requests, with their fields in the query string:

curl "https://public.api.external-integration.ubikap.dev/services.register.v1.RegisterService/ListRegisters?workspaceKey=acme7391_CP_42" \
  -H "Authorization: Bearer $TOKEN"

The API reference lists every route with its request and response, and a grpcurl example for each.