Guida all'Uso delle API

7 maggio 2026

Autenticazione, limiti, versioning e best practice.

Authentication

The Optiviera API uses JWT Bearer token authentication. Obtain a token via /api/auth/login and include it in the Authorization header of every request.

 Authorization: Bearer <your-jwt-token> 

Tokens are valid for 7 days by default
Multi-tenancy: token includes TenantId claim — all API calls are scoped to your tenant
Google OAuth login also available via /api/auth/google-login
Never share or expose your API tokens in client-side code

Rate Limits

WindowStatusLimitNotes

Per SecondActive20 requestsPer IP address

Per MinuteActive120 requestsPer IP address

Per HourActive2,000 requestsPer IP address

Auth EndpointsStrictTighter limitsLogin/register have stricter thresholds

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. A 429 Too Many Requests response means you have exceeded the limit.

Base URL & Versioning

Production base URL: https://app.optiviera.com/api
All endpoints are prefixed with /api/
API versioning is currently implicit — breaking changes will be communicated with advance notice
Swagger / OpenAPI documentation available to authenticated users at /swagger

Key API Endpoints

ModuleEndpoint PrefixKey Operations

Authentication/api/authLogin, register, Google OAuth, password reset

CRM/api/crmLeads, opportunities, customers

Finance/api/financeInvoices, payments, journal entries

HR/api/hrEmployees, leaves, payroll

Inventory/api/inventoryItems, stock movements

Files/api/filesUpload, download, delete

Settings/api/settingsTenant, users, roles, permissions

Error Handling

401

Unauthorized

Token missing, expired, or invalid. Re-authenticate and retry.

403

Forbidden

Authenticated but lacks required permission for this operation.

404

Not Found

Resource does not exist or is not accessible in your tenant.

429

Rate Limited

Too many requests. Wait for the window to reset before retrying.

5xx

Server Error

Platform-side error. Retry with exponential backoff. Contact support if persistent.

Best Practices

Implement exponential backoff for retries on 5xx errors
Cache responses where appropriate to reduce API load
Store tokens securely — never expose in URLs or logs
Use specific endpoint filters rather than fetching all records
Monitor your rate limit headers to avoid 429 errors proactively

Torna al Centro Assistenza