Loading Optiviera...

REST API

Optiviera REST API Reference

JSON · JWT Auth · Multi-tenant

Integrate any system with Optiviera via a fully documented REST API. All endpoints require a JWT Bearer token and are automatically scoped to your tenant.

Quick Start

Get from zero to your first API call in three steps

1

Authenticate

Send your credentials to POST /api/auth/login. The response contains a JWT token valid for 24 hours.

2

Add Auth Header

Attach the token to every request using the Authorization: Bearer [token] header.

3

Call the API

All endpoints live under https://optiviera.com/api and respond with JSON. Tenant context is derived automatically from your token.

Authentication

Every request must carry a valid JWT Bearer token obtained from the login endpoint

How it works

  • POST to /api/auth/login with your email and password
  • Store the returned token securely (httpOnly cookie or in-memory)
  • Include Authorization: Bearer [token] in every subsequent request
  • Tokens expire after 24 hours — refresh with POST /api/auth/refresh
Login Requestbash
curl -X POST https://optiviera.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••"}'
Successful Responsejson
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}
Using the Tokenhttp
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Base URL & Format

Everything you need to know before your first call

Base URL: https://optiviera.com/api — All endpoints below are relative to this base URL. Always use HTTPS.

JSON Format

All requests and responses use application/json. Set Content-Type: application/json on write operations (POST, PUT).

Tenant Scoping

Data is automatically filtered to your organization using the TenantId embedded in your JWT. You cannot access another tenant's data.

Pagination

List endpoints support ?page=1&pageSize=20. The response includes totalCount, page, and pageSize fields.

Filtering & Sorting

Most list endpoints accept query params like ?status=Open&sortBy=createdAt&sortDir=desc for flexible data retrieval.

API Endpoint Groups

12 resource groups covering every module of the platform

Authentication

  • POST/api/auth/login
  • POST/api/auth/refresh
  • POST/api/auth/logout

Tickets & HelpDesk

  • GET/api/tickets
  • POST/api/tickets
  • GET/api/tickets/{id}
  • PUT/api/tickets/{id}
  • DELETE/api/tickets/{id}
  • POST/api/tickets/{id}/comments

Finance & Accounting

  • GET/api/invoices
  • POST/api/invoices
  • GET/api/journal-entries
  • POST/api/journal-entries
  • GET/api/balance-sheet
  • GET/api/trial-balance

HR & Employees

  • GET/api/employees
  • POST/api/employees
  • GET/api/employees/{id}
  • PUT/api/employees/{id}
  • GET/api/positions
  • GET/api/departments

Payroll

  • GET/api/payroll
  • POST/api/payroll/run
  • GET/api/payroll/{id}
  • PUT/api/payroll/{id}/approve

Sales & Orders

  • GET/api/orders
  • POST/api/orders
  • GET/api/quotations
  • POST/api/quotations
  • GET/api/customers
  • POST/api/customers

Procurement

  • GET/api/purchase-orders
  • POST/api/purchase-orders
  • GET/api/suppliers
  • POST/api/suppliers
  • GET/api/purchase-orders/{id}

Inventory

  • GET/api/products
  • POST/api/products
  • GET/api/stock-movements
  • POST/api/stock-movements
  • GET/api/warehouses

CRM & Leads

  • GET/api/leads
  • POST/api/leads
  • GET/api/contacts
  • POST/api/contacts
  • GET/api/pipeline-stages

Work Orders

  • GET/api/work-orders
  • POST/api/work-orders
  • GET/api/work-orders/{id}
  • PUT/api/work-orders/{id}
  • DELETE/api/work-orders/{id}

Reports & Analytics

  • GET/api/reports/tickets
  • GET/api/reports/finance
  • GET/api/reports/hr
  • GET/api/reports/sales
  • GET/api/reports/inventory

Settings

  • GET/api/settings/tenant
  • PUT/api/settings/tenant
  • GET/api/settings/users
  • GET/api/sla-configs
  • POST/api/sla-configs

HTTP Status Codes

Standard HTTP semantics are used consistently throughout the API

200OK

Request succeeded. Body contains the result.

201Created

Resource created. Body contains the new object with its ID.

204No Content

Request succeeded. No body returned (used for DELETE).

400Bad Request

Malformed request or missing required fields.

401Unauthorized

Missing, expired, or invalid JWT token.

403Forbidden

Valid token but insufficient permissions for this action.

404Not Found

Resource does not exist or belongs to another tenant.

422Validation Error

Input validation failed. See the details array in the response body.

500Server Error

Unexpected server error. Contact support with the request ID from the response.

Error Response Format

All error responses follow a consistent JSON structure for easy parsing

When a request fails, the API returns a structured JSON body. Use the details array for field-level validation feedback in forms.

  • status — HTTP status code
  • error — Error type identifier
  • message — Human-readable description
  • details — Field-level validation errors (array)
Example Error Responsejson
{
  "status": 422,
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    { "field": "email", "message": "Email is required" },
    { "field": "password", "message": "Minimum 8 characters" }
  ]
}

Ready to integrate?

Explore the full interactive Swagger documentation or contact our team for API access and support.