Public API

Integrate Renaska with your systems

Access products, inventory, clients, orders, quotations, payments, and shipping from any external service. The API is server-to-server: the key lives on your server, never in the browser.

Server-to-server onlyYour API Key is a secret. Never include it in frontend code, mobile apps, or public environment variables.
Go to Settings → API Keys

Quickstart

Authenticate with your key in the Authorization header:

# Example: list clients
curl https://bk.renaska.com/api/external/v1/clients \
  -H "Authorization: Bearer rnk_live_<key>"

Base URL: https://bk.renaska.com/api/external/v1

The OpenAPI spec is public and requires no key — add ?lang=es or ?lang=en to get it in your language.

Scopes and permissions

Each key grants one or more scopes in the format resource:action (e.g. orders:write).

Use * for full access or resource:* to read and write an entire resource.

Resource groups

Each group is gated by its own scope.

ProductsRead and write
InventoryRead and write
InputsRead and write
ClientsRead and write
OrdersRead and write
QuotationsRead and write
PaymentsRead and write
ShippingRead and write
LeadsWrite only

Plus utility endpoints: GET /catalog and GET /ping.

  • An API key reaches every location on the account — keys have no per-location scoping, so even a team member limited to one location is more restricted than any key. This is by design.
  • Order reads include POS sales and their unit prices. The dashboard hides these from non-admin roles; the API does not.

Side effects to know about

  • POST /orders and POST /quotations/:id/convert deduct stock and post the accounting entry — they do not notify the client.
  • POST /shipments does not deduct stock.

Operational details

  • Send an Idempotency-Key header (max 255 characters) to avoid duplicates: optional on POST /orders and other older POST endpoints, REQUIRED on the product, inventory, and input write routes and on PATCH /orders/:id/status and PATCH /orders/:id/stage, which return 400 without it. On PUT and PATCH it acts as a concurrency lock rather than a cache — a later retry runs again.
  • Per-key limits: 120 reads/min and 30 writes/min.
  • Lists are paginated with data + meta (page, limit, total, totalPages) — 20 items per page by default, 100 max.
  • Errors respond with an error object (code, message) — e.g. 403 insufficient_scope, 429 rate_limited, or 409 conflict.

Endpoint reference

Explore all endpoints and download the OpenAPI 3.1 spec.

Download OpenAPI 3.1 (JSON)