Loading Optiviera...

REST API

Riferimento API REST Optiviera

JSON · Auth JWT · Multi-tenant

Integra qualsiasi sistema con Optiviera tramite una API REST completamente documentata. Tutti gli endpoint richiedono un token JWT Bearer e sono automaticamente limitati al tuo tenant.

Avvio rapido

Da zero alla tua prima chiamata API in tre passaggi

1

Autenticarsi

Invia le tue credenziali a POST /api/auth/login. La risposta contiene un token JWT valido per 24 ore.

2

Aggiungere l'intestazione Auth

Allega il token ad ogni richiesta: Authorization: Bearer [token]

3

Chiamare l'API

Tutti gli endpoint si trovano sotto https://optiviera.com/api e rispondono in JSON. Il contesto tenant è derivato automaticamente dal tuo token.

Autenticazione

Ogni richiesta deve portare un token JWT Bearer valido ottenuto dall'endpoint di login

Come funziona

  • POST a /api/auth/login con email e password
  • Conserva il token in modo sicuro (cookie httpOnly o in memoria)
  • Includi Authorization: Bearer [token] in ogni richiesta successiva
  • I token scadono dopo 24 ore — aggiorna con POST /api/auth/refresh
Richiesta di loginbash
curl -X POST https://optiviera.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••"}'
Risposta riuscitajson
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400,
  "tokenType": "Bearer"
}
Usare il tokenhttp
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

URL base & Formato

Tutto ciò che devi sapere prima della tua prima chiamata

URL base: https://optiviera.com/api — Tutti gli endpoint sono relativi a questo URL base. Usa sempre HTTPS.

Formato JSON

Tutte le richieste e risposte usano application/json. Imposta Content-Type: application/json nelle operazioni di scrittura.

Scoping tenant

I dati sono automaticamente filtrati alla tua organizzazione tramite il TenantId incorporato nel tuo JWT.

Paginazione

Gli endpoint lista supportano ?page=1&pageSize=20. La risposta include totalCount, page e pageSize.

Filtraggio & Ordinamento

La maggior parte degli endpoint lista accetta parametri come ?status=Open&sortBy=createdAt&sortDir=desc.

Gruppi di endpoint API

12 gruppi di risorse che coprono tutti i moduli della piattaforma

Autenticazione

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

Ticket & HelpDesk

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

Finanza & Contabilità

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

HR & Dipendenti

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

Buste paga

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

Vendite & Ordini

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

Approvvigionamento

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

Magazzino

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

CRM & Lead

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

Ordini di lavoro

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

Report & Analisi

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

Impostazioni

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

Codici di stato HTTP

La semantica HTTP standard è usata in modo coerente in tutta l'API

200OK

Richiesta riuscita. Il corpo contiene il risultato.

201Creato

Risorsa creata. Il corpo contiene il nuovo oggetto con ID.

204Nessun contenuto

Richiesta riuscita. Nessun corpo (usato per DELETE).

400Richiesta non valida

Richiesta malformata o campi obbligatori mancanti.

401Non autorizzato

Token JWT mancante, scaduto o non valido.

403Vietato

Token valido ma permessi insufficienti per questa azione.

404Non trovato

La risorsa non esiste o appartiene a un altro tenant.

422Errore di validazione

La validazione dell'input è fallita. Vedi l'array details nel corpo della risposta.

500Errore del server

Errore imprevisto del server. Contatta il supporto con l'ID della richiesta.

Formato delle risposte di errore

Tutte le risposte di errore seguono una struttura JSON coerente

Quando una richiesta fallisce, l'API restituisce un corpo JSON strutturato. Usa l'array details per il feedback di validazione a livello di campo.

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

Pronto per integrare?

Esplora la documentazione Swagger interattiva completa o contatta il nostro team per l'accesso API.