Getting Started with Invora API¶

Overview¶

Invora is a multi-tenant e-invoicing and billing platform. The API lets you:

Create and manage invoices — UBL 2.1 compliant, multi-country regulation support
Automate billing — subscription management, usage-based metering, dunning
Manage organizations — self-service registration, role-based access, multi-tier tenancy

Environments¶

Environment	Base URL	Purpose
Staging	`https://stg-gateway.invora.app`	API integration testing. Use this for development and QA.
Production	`https://gateway.invora.app`	Live environment. Real data and billing.

Use the Staging environment for all API integration work. It mirrors production but uses test data and sandbox regulation endpoints (e.g., ZATCA sandbox with OTP 123456).

Protocol¶

Invora uses gRPC with HTTP/JSON transcoding. Every API is available over both protocols:

REST/JSON — standard HTTP requests with JSON bodies (documented here)
gRPC — high-performance binary protocol for server-to-server integrations

All REST endpoints use camelCase field names in JSON (proto field freeze_immediately → JSON freezeImmediately).

Quick Start¶

Register — Create an account at https://dashboard.invora.app
Complete Business Profile — POST /api/identity/v2/registration/complete-profile
Get API credentials — The response includes clientId and clientSecret for M2M access
Authenticate — Exchange credentials for a JWT token via OIDC
Make API calls — Include the JWT in the Authorization: Bearer <token> header

Request Format¶

POST /api/v1/simple/invoices/list HTTP/1.1
Host: stg-gateway.invora.app
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
X-Target-Org-Id: <org-id>

{
  "filter": {
    "textSearch": "INV-2026"
  },
  "pagination": {
    "limit": "20"
  }
}

Response Format¶

All responses follow a consistent structure. List endpoints return:

{
  "items": [...],
  "totalCount": "42",
  "nextPageCursor": "eyJ..."
}

Error Handling¶

Errors use standard gRPC status codes mapped to HTTP:

gRPC Code	HTTP Status	Meaning
OK	200	Success
INVALID_ARGUMENT	400	Bad request (validation error)
UNAUTHENTICATED	401	Missing or invalid JWT
PERMISSION_DENIED	403	Insufficient scope/role
NOT_FOUND	404	Resource doesn't exist
ALREADY_EXISTS	409	Duplicate resource
RESOURCE_EXHAUSTED	429	Rate limit or plan limit reached

Pagination¶

All list endpoints use cursor-based pagination:

{
  "pagination": {
    "limit": "20",
    "cursor": "eyJ..."
  }
}

The nextPageCursor in the response is passed as pagination.cursor in the next request. When nextPageCursor is null, there are no more results.

Filtering¶

List endpoints support structured typed filters via the filter field:

{
  "filter": {
    "textSearch": "search term",
    "part": {
      "onlyFrozen": true
    }
  }
}

Each service defines its own filter part types, combined with nested and, or, and not. Check the specific endpoint documentation for the available filter fields.