eSuite API

API REST per integrare sistemi esterni con eSuite. Gestisci aziende, sedi, prodotti e ordini.

Base URL
https://cdn.vanillainnovations.com/api/v1
Authentication
API Key (X-Api-Key header)

Authentication

Autenticazione tramite API Key. Includi l'header X-Api-Key in ogni richiesta.

Tutte le richieste API richiedono l'header X-Api-Key. La chiave si genera dalla sezione Settings > API Keys di eSuite. Rate limit: 60 richieste al minuto per API key. Formato risposte: JSON con envelope {"data": ...} per successo e {"error": ...} per errori.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite
Accept application/json Optional Formato risposta

Responses

JSON 
{
    "data": [
        "..."
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 97
    }
}

Companies

Gestione delle aziende clienti/fornitori.

Restituisce la lista paginata delle aziende. Supporta ricerca su legal_name, code, brand, email, vat_id.

Parameters

Name Type In Required Description Default
page integer query Optional Numero pagina 1
per_page integer query Optional Elementi per pagina (max 100) 20
search string query Optional Testo di ricerca -
sort string query Optional Campo di ordinamento -
direction string query Optional Direzione ordinamento: asc o desc asc
include string query Optional Relazioni da includere. Valore supportato: venues -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

JSON 
{
    "data": [
        {
            "id": 1,
            "code": "CLI001",
            "brand": "Acme",
            "legal_name": "Acme SRL",
            "vat_id": "01234567890",
            "tax_id": "01234567890",
            "email": "info@acme.it",
            "phone": "+39 02 1234567",
            "mobile": null,
            "website": "https://acme.it",
            "pec": "acme@pec.it",
            "sdi": "0000000",
            "fiscal_position": "national",
            "note": null,
            "language": "it",
            "currency": "EUR",
            "created_at": "2026-01-15T10:30:00+00:00",
            "updated_at": "2026-03-20T14:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1,
        "from": 1,
        "to": 1
    }
}

Restituisce i dettagli di una singola azienda. Usa ?include=venues per includere le sedi.

Parameters

Name Type In Required Description Default
id integer path Required ID dell'azienda -
include string query Optional Relazioni da includere: venues -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Crea una nuova azienda. Viene automaticamente creata una sede predefinita "Sede principale".

Parameters

Name Type In Required Description Default
legal_name string body Required Ragione sociale -
code string body Optional Codice cliente (max 50 car.) -
brand string body Optional Nome commerciale -
vat_id string body Optional Partita IVA -
tax_id string body Optional Codice fiscale -
email string body Optional Email -
phone string body Optional Telefono -
pec string body Optional PEC -
sdi string body Optional Codice SDI (max 10 car.) -
fiscal_position string body Optional Posizione fiscale: national, eu, extra_eu -
language string body Optional Lingua (es. it, en) -
currency string body Optional Valuta (es. EUR) -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Request Body

JSON 
{
    "legal_name": "Acme SRL",
    "code": "CLI001",
    "vat_id": "01234567890",
    "tax_id": "01234567890",
    "email": "info@acme.it",
    "phone": "+39 02 1234567",
    "sdi": "0000000",
    "pec": "acme@pec.it",
    "fiscal_position": "national"
}

Responses

Aggiorna i campi di un'azienda. Tutti i campi sono opzionali.

Parameters

Name Type In Required Description Default
id integer path Required ID dell'azienda -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Elimina un'azienda (soft delete).

Parameters

Name Type In Required Description Default
id integer path Required ID dell'azienda -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

Venues

Sedi e indirizzi delle aziende. Ogni azienda ha almeno una sede predefinita.

Restituisce tutte le sedi di un'azienda, ordinate per sede predefinita e poi per nome.

Parameters

Name Type In Required Description Default
companyId integer path Required ID dell'azienda -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

JSON 
{
    "data": [
        {
            "id": 1,
            "company_id": 1,
            "name": "Sede principale",
            "address": "Via Roma 1",
            "city": "Milano",
            "zip": "20100",
            "province": "MI",
            "country": "IT",
            "phone1": "+39 02 1234567",
            "email1": "sede@acme.it",
            "is_default": true,
            "created_at": "2026-01-15T10:30:00+00:00",
            "updated_at": "2026-01-15T10:30:00+00:00"
        }
    ]
}

Aggiunge una nuova sede all'azienda.

Parameters

Name Type In Required Description Default
name string body Required Nome della sede -
address string body Optional Indirizzo -
city string body Optional Citta -
zip string body Optional CAP -
province string body Optional Provincia (sigla) -
country string body Optional Paese -
phone1 string body Optional Telefono -
email1 string body Optional Email -
is_default boolean body Optional Sede predefinita -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Request Body

JSON 
{
    "name": "Magazzino Nord",
    "address": "Via Industria 5",
    "city": "Bergamo",
    "zip": "24100",
    "province": "BG",
    "country": "IT"
}

Responses

Aggiorna i campi di una sede. Tutti i campi sono opzionali.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Elimina una sede.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

Products

Catalogo prodotti e servizi.

Restituisce la lista paginata dei prodotti con categoria, tipo, brand, IVA e unita di misura.

Parameters

Name Type In Required Description Default
page integer query Optional Numero pagina 1
per_page integer query Optional Elementi per pagina (max 100) 20
search string query Optional Testo di ricerca -
sort string query Optional Campo di ordinamento -
direction string query Optional Direzione ordinamento: asc o desc asc
is_active boolean query Optional Filtra per stato attivo/inattivo -
category_id integer query Optional Filtra per categoria -
brand_id integer query Optional Filtra per brand -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

JSON 
{
    "data": [
        {
            "id": 1,
            "code": "PROD001",
            "name": "Prodotto Test",
            "description": "Descrizione prodotto",
            "product_kind": "good",
            "price": "25.00",
            "cost": "10.00",
            "stock_qty": "100.00",
            "weight": "0.50",
            "is_active": true,
            "image": null,
            "category": {
                "id": 1,
                "name": "Categoria"
            },
            "type": {
                "id": 1,
                "name": "Tipo"
            },
            "brand": {
                "id": 1,
                "name": "Brand"
            },
            "vat": {
                "id": 1,
                "rate": "22.00",
                "name": "22%"
            },
            "unit": {
                "id": 1,
                "name": "Pezzi",
                "code": "PZ"
            },
            "created_at": "2026-01-15T10:30:00+00:00",
            "updated_at": "2026-03-20T14:00:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 20,
        "total": 1,
        "from": 1,
        "to": 1
    }
}

Restituisce i dettagli di un prodotto con le relazioni.

Parameters

Name Type In Required Description Default
id integer path Required ID del prodotto -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Crea un nuovo prodotto nel catalogo.

Parameters

Name Type In Required Description Default
code string body Required Codice prodotto (obbligatorio, max 50 car.) -
name string body Required Nome prodotto -
description string body Optional Descrizione -
product_kind string body Optional Tipo: good o service good
price number body Optional Prezzo di vendita -
cost number body Optional Costo di acquisto -
stock_qty number body Optional Quantita in magazzino -
category_id integer body Optional ID categoria -
type_id integer body Optional ID tipo -
brand_id integer body Optional ID brand -
vat_id integer body Optional ID aliquota IVA -
unit_id integer body Optional ID unita di misura -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Request Body

JSON 
{
    "code": "PROD001",
    "name": "Prodotto Test",
    "price": 25,
    "cost": 10,
    "is_active": true,
    "category_id": 1,
    "vat_id": 1,
    "unit_id": 1,
    "stock_qty": 100
}

Responses

Aggiorna i campi di un prodotto. Tutti i campi sono opzionali.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Elimina un prodotto dal catalogo.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

Orders

Gestione ordini cliente. I totali vengono calcolati automaticamente dalle righe.

Restituisce la lista paginata degli ordini con azienda e righe.

Parameters

Name Type In Required Description Default
page integer query Optional Numero pagina 1
per_page integer query Optional Elementi per pagina (max 100) 20
search string query Optional Testo di ricerca -
sort string query Optional Campo di ordinamento -
direction string query Optional Direzione ordinamento: asc o desc asc
status string query Optional Filtra per stato: draft, confirmed, sent, cancelled -
company_id integer query Optional Filtra per azienda -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Restituisce i dettagli di un ordine con azienda e righe.

Parameters

Name Type In Required Description Default
id integer path Required ID dell'ordine -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

JSON 
{
    "data": {
        "id": 1,
        "number": "001/2026",
        "date": "2026-03-22",
        "due_date": null,
        "status": "draft",
        "fulfillment_status": "unfulfilled",
        "company_id": 1,
        "company": {
            "id": 1,
            "legal_name": "Acme SRL",
            "code": "CLI001"
        },
        "currency": "EUR",
        "net": "100.00",
        "tax": "22.00",
        "gross": "122.00",
        "shipping": "0.00",
        "note_public": null,
        "items": [
            {
                "id": 1,
                "product_id": 1,
                "code": "PROD001",
                "name": "Prodotto Test",
                "description": null,
                "qty": "2.00",
                "price": "50.00",
                "discount_percent": "0.00",
                "net": "100.00",
                "tax_percent": "22.00",
                "tax": "22.00",
                "gross": "122.00"
            }
        ],
        "created_at": "2026-03-22T10:00:00+00:00",
        "updated_at": "2026-03-22T10:00:00+00:00"
    }
}

Crea un nuovo ordine. I totali (net, tax, gross) vengono calcolati automaticamente dalle righe. L'ordine viene creato in stato 'draft'. Usa PATCH /orders/{id}/confirm per confermarlo.

Parameters

Name Type In Required Description Default
company_id integer body Required ID dell'azienda cliente -
date date body Optional Data ordine (YYYY-MM-DD) oggi
due_date date body Optional Data scadenza -
currency string body Optional Valuta EUR
note_public string body Optional Note pubbliche -
shipping number body Optional Costo spedizione -
items array body Required Righe ordine (obbligatorio, min 1) -
items[].product_id integer body Optional ID prodotto (se specificato, prende codice e nome dal prodotto) -
items[].name string body Required Descrizione riga -
items[].qty number body Required Quantita -
items[].price number body Required Prezzo unitario -
items[].tax_percent number body Optional Aliquota IVA % 22
items[].discount_percent number body Optional Sconto riga % -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Request Body

JSON 
{
    "company_id": 1,
    "date": "2026-03-22",
    "note_public": "Ordine urgente",
    "items": [
        {
            "product_id": 1,
            "name": "Prodotto Test",
            "qty": 2,
            "price": 50,
            "tax_percent": 22
        },
        {
            "name": "Servizio personalizzato",
            "qty": 1,
            "price": 100,
            "tax_percent": 22
        }
    ]
}

Responses

Aggiorna un ordine. Se vengono fornite le righe (items), sostituiscono completamente quelle esistenti e i totali vengono ricalcolati. Non e possibile aggiornare un ordine annullato.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Elimina un ordine e tutte le sue righe.

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Responses

Cambia lo stato dell'ordine a "confirmed". Non e possibile confermare un ordine annullato.

Parameters

Name Type In Required Description Default
id integer path Required ID dell'ordine -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite

Cambia lo stato dell'ordine a "cancelled".

Parameters

Name Type In Required Description Default
id integer path Required ID dell'ordine -

Headers

Name Value Required Description
X-Api-Key YOUR_API_KEY Required La tua API key generata dalla sezione Settings > API Keys di eSuite