Convenzioni API

Questa pagina descrive le convenzioni utilizzate in tutte le API Elerama.

Response Format

Tutte le risposte seguono una struttura standard:

{
  "success": true,
  "message": "Messaggio opzionale",
  "context": "resource_name",
  "status": "action_name",
  "data": { ... }
}

Campi

Campo	Tipo	Descrizione
success	boolean	true se l'operazione e riuscita
message	string | null	Messaggio descrittivo (errore o conferma)
context	string	Identifica la risorsa (es. brands, articles)
status	string	Identifica l'azione (es. list, create, error)
data	object | array	Dati della risposta

HTTP Status Codes

Code	Significato	Uso
200	OK	Richiesta completata con successo
201	Created	Risorsa creata con successo
400	Bad Request	Parametri mancanti o non validi
401	Unauthorized	Autenticazione richiesta
403	Forbidden	Permessi insufficienti
404	Not Found	Risorsa non trovata
409	Conflict	Conflitto (es. risorsa in uso)
422	Unprocessable Entity	Validazione fallita
500	Internal Server Error	Errore server

Error Response

In caso di errore, la risposta include dettagli:

{
  "success": false,
  "message": "Descrizione dell'errore",
  "context": "brands",
  "status": "duplicateCode",
  "data": {
    "field": "code",
    "value": "EXISTING_CODE"
  }
}

Error Status Comuni

Status	HTTP	Descrizione
notFound	404	Risorsa non trovata
unauthorized	401	Non autenticato
forbidden	403	Non autorizzato
validation	422	Errore di validazione
conflict	409	Conflitto
serverError	500	Errore interno

Request Headers

Headers richiesti per ogni richiesta:

Content-Type: application/json
Daisy-Erp: frontend

Query Parameters

Per le liste, sono disponibili parametri comuni:

Parametro	Tipo	Descrizione
search	string	Ricerca testuale
page	integer	Numero pagina (default: 1)
per_page	integer	Elementi per pagina (default: 10)

Convenzioni di Naming

• Endpoint: kebab-case plurale (/brands, /warehouse-movements)
• Campi JSON response: camelCase (idBrand, createdAt)
• Query params: snake_case (per_page, include_deleted)

Multi-tenancy

Tutte le operazioni sono automaticamente filtrate per l'azienda attiva in sessione. Non e necessario passare l'ID azienda nelle richieste.

Cambio Azienda

Per operare su un'altra azienda, usa l'endpoint /erp_auth/switch_company prima di effettuare le richieste.

Soft Delete

Le risorse che supportano soft delete includono:

{
  "id": 123,
  "name": "Risorsa",
  "isDeleted": false,
  "deletedAt": null,
  "deletedBy": null
}

Per includere risorse eliminate nelle liste, usa:

GET /resource?includeDeleted=true