gRPC and HTTP/JSON Transcoding¶

Dual Protocol¶

Every Invora API is available over both gRPC and REST/JSON. The backend uses gRPC as the canonical protocol, with automatic HTTP/JSON transcoding via google.api.http annotations.

Using REST/JSON¶

Standard HTTP requests with JSON bodies. This is what's documented in Apidog.

curl -X POST https://stg-gateway.invora.app/api/v1/simple/invoices/list \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"limit": "10"}}'

Field Name Mapping¶

Proto fields use snake_case. JSON uses camelCase (automatic transcoding):

Proto	JSON
`currency_code`	`currencyCode`
`freeze_immediately`	`freezeImmediately`
`tax_currency_code`	`taxCurrencyCode`

Date/Time Types¶

Proto Type	JSON Format	Example
`google.protobuf.Timestamp`	RFC 3339 string	`"2026-04-27T12:00:00Z"`
`google.type.Date`	Object with year/month/day	`{"year": 2026, "month": 4, "day": 27}`
`google.type.TimeOfDay`	Object with hours/minutes/seconds	`{"hours": 14, "minutes": 30}`

Wrapper Types¶

Optional scalar fields use wrapper types. In JSON, they're unwrapped:

Proto	JSON
`google.protobuf.StringValue name = 1;`	`"name": "value"` or `"name": null`
`google.protobuf.Int32Value count = 2;`	`"count": 42` or `"count": null`

Enum Values¶

Enums are serialized as strings (not integers):

{
  "issueAt": "SORT_DIRECTION_DESCENDING"
}

Using gRPC¶

For server-to-server integrations requiring maximum performance.

Proto Files¶

Proto definitions are published on the Buf Schema Registry (BSR):

Module	BSR URL
Common	`buf.build/invora/common`
Simple	`buf.build/invora/simple`
Invoicing	`buf.build/invora/invoicing`
Billing	`buf.build/invora/billing`
Identity	`buf.build/invora/identity`

The ergonomic invoice / credit-note / debit-note surface lives in the Simple module (invora.simple.*.v1). The Invoicing module holds the supporting tenant services (parties, branches, settings, regulations, and the full UBL document model used by power users).

Connection¶

Host: stg-gateway.invora.app:443
Protocol: gRPC over TLS (h2)

Code Generation¶

Generate typed clients in any language:

# Install buf CLI
buf generate buf.build/invora/invoicing

buf.gen.yaml

plugins:
  - remote: buf.build/grpc/csharp
    out: gen
  - remote: buf.build/protocolbuffers/csharp
    out: gen

Metadata (Headers)¶

gRPC uses metadata instead of HTTP headers:

Metadata Key	Value
`authorization`	`Bearer <JWT>`
`x-target-org-id`	Target org ID (for cross-org access)

Server Reflection¶

gRPC server reflection is enabled on all environments. Use tools like grpcurl or Evans:

grpcurl -H "Authorization: Bearer $TOKEN" \
  stg-gateway.invora.app:443 \
  list

grpcurl -H "Authorization: Bearer $TOKEN" \
  stg-gateway.invora.app:443 \
  invora.simple.invoices.v1.SimpleInvoiceService/List

API Versioning¶

APIs are versioned in the package name: invora.simple.invoices.v1, invora.billing.customers.v2. Breaking changes result in a new version (v3). Non-breaking additions (new fields, new RPCs) are made to the current version.