L'API Novadesko

Genera le tue credenziali dal tuo spazio Novadesko su web.novadesko.com/integrations/api. Due tipi di credenziali, revocabili in qualsiasi momento:

• nvk_… — Chiave utente: copre tutte le aziende del tuo account.
• nvt_… — Token azienda: limitato a una sola azienda.

https://web.novadesko.com/api/v1

Sono accettati tre formati di autenticazione:

// 1. Bearer
Authorization: Bearer CLE.SECRET

// 2. Basic
Authorization: Basic base64(CLE:SECRET)

// 3. Header dedicati
X-Api-Key: CLE
X-Api-Secret: SECRET

Il segreto viene mostrato una sola volta, alla creazione. La revoca è immediata dalla stessa pagina. I vecchi token Sanctum e le chiavi nsk_ restano accettati.

Esempio

curl https://web.novadesko.com/api/v1/me \
  -H "Authorization: Bearer nvk_xxx.SECRET"

Identifica chi effettua la chiamata ed elenca le aziende accessibili con il tuo identificativo.

curl https://web.novadesko.com/api/v1/me \
  -H "Authorization: Bearer nvk_xxx.SECRET"

{
  "user": { "id": 1, "name": "John Doe", "email": "john@doe.com" },
  "credential": { "kind": "user_key", "name": "Zapier", "shop_id": null },
  "companies": [
    {
      "id": 1,
      "name": "Demo SPRL",
      "vat_number": "BE0123456789",
      "email": "info@demo.com",
      "phone": "+32 2 123 45 67",
      "city": "Bruxelles",
      "country": "Belgique"
    }
  ]
}

Cifre chiave di un'azienda in un periodo: fatturato IVA inclusa, note di credito, acquisti, risultato lordo, insoluti di clienti e fornitori, contatori.

Date nel formato YYYY-MM-DD. Per impostazione predefinita: anno in corso.

curl "https://web.novadesko.com/api/v1/companies/1/stats?from=2026-01-01" \
  -H "Authorization: Bearer nvk_xxx.SECRET"

{
  "company": { "id": 1, "name": "Demo SPRL" },
  "period": { "from": "2026-01-01", "to": "2026-08-17" },
  "revenue_ttc": 17077.46,
  "credit_notes_ttc": 250.00,
  "net_revenue_ttc": 16827.46,
  "purchases_ttc": 6420.35,
  "gross_result_ttc": 10407.11,
  "invoices_count": 34,
  "purchases_count": 21,
  "estimates_count": 8,
  "unpaid_invoices": { "count": 6, "total_ttc": 11769.28, "overdue_count": 6 },
  "unpaid_purchases": { "count": 2, "total_ttc": 840.50 },
  "customers_count": 57,
  "products_count": 112
}

Cerca e consulta i documenti di ogni azienda, di qualsiasi tipo.

Filtri disponibili:

?type=&paid=&from=&to=&q=&page=&per_page=

Tipi di documento:

invoice · purchase · estimate · order · credit_note · proforma · receipt

{
  "data": [
    {
      "id": 123,
      "number": "FAC-2026-0042",
      "type": "invoice",
      "date": "2026-06-12",
      "due_date": "2026-07-12",
      "customer": "ACME SRL",
      "amount_ttc": 1200.00,
      "is_paid": false
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 34 }
}

{
  "id": 123,
  "number": "FAC-2026-0042",
  "type": "invoice",
  "amount_ttc": 1200.00,
  "is_paid": false,
  "customer": {
    "id": 7,
    "name": "ACME SRL",
    "vat_number": "BE0987654321"
  },
  "lines": [
    {
      "product_name": "Abonnement Pro",
      "quantity": 2,
      "unit_amount": 495.87,
      "tax_rate": 21
    }
  ]
}

Consulta le schede dei clienti e il catalogo prodotti di ogni azienda, con ricerca e paginazione.

{
  "data": [
    {
      "id": 7,
      "name": "ACME SRL",
      "email": "contact@acme.be",
      "phone": "+32 2 555 12 34",
      "city": "Bruxelles"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 57 }
}

{
  "data": [
    {
      "id": 42,
      "name": "Abonnement Pro",
      "reference": "ABO-PRO",
      "sale_price": 49.99,
      "tax_included": true,
      "stock_quantity": 0
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 112 }
}

Fatture non pagate di un'azienda, raggruppate per cliente, con ritardi e totale.

{
  "count": 6,
  "total_ttc": 11769.28,
  "invoices": [
    {
      "id": 118,
      "number": "FAC-2026-0031",
      "customer": "ACME SRL",
      "date": "2026-03-02",
      "due_date": "2026-04-01",
      "amount_ttc": 3025.00,
      "overdue": true
    }
  ]
}

Pagamenti e movimenti di cassa di un'azienda in un periodo (500 al massimo).

{
  "period": { "from": "2026-01-01", "to": "2026-08-17" },
  "count": 1,
  "data": [
    {
      "id": 88,
      "date": "2026-06-12",
      "amount": 1200.00,
      "type": "payment",
      "direction": "in",
      "source": "bank"
    }
  ]
}

Endpoint storici legati a un'azienda: crea e modifica documenti di ogni tipo (slug: invoices, quotes, orders…). La numerazione è automatica alla creazione.

Esempio: fatture

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/documents/invoices

[
  {
    "id": 123,
    "number": "FAC-2026-0042",
    "date": "2026-06-12",
    "client": { "id": 1, "name": "ACME Sarl" },
    "total": 1200.00,
    "status": "paid"
  }
]

{
  "client_id": 1,
  "date": "2026-06-12",
  "lines": [
    { "product_id": 15, "qty": 2, "price": 100 }
  ]
}

Gestisci la tua anagrafica clienti: creazione, consultazione e aggiornamento.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/customers

{
  "name": "Société Demo",
  "email": "contact@demo.com",
  "phone": "+32 2 123 45 67"
}

{
  "id": 2,
  "name": "Société Demo",
  "email": "contact@demo.com",
  "created_at": "2026-06-12T16:10:00Z"
}

Gestisci i tuoi fornitori e le loro informazioni.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/suppliers

{
  "company": "Fournisseur SARL",
  "vat_number": "FR123456789",
  "email": "info@fournisseur.com"
}

{
  "id": 5,
  "company": "Fournisseur SARL",
  "created_at": "2026-06-12T16:22:00Z"
}

Gestisci il tuo catalogo prodotti.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/products

{
  "name": "Abonnement Pro",
  "price": 49.99,
  "category_id": 1
}

{
  "id": 42,
  "name": "Abonnement Pro",
  "price": 49.99
}

Elenco dei tipi di documento attivi e dei relativi slug da usare negli endpoint /documents/{slug}.

curl -H "Authorization: Bearer nvk_xxx.SECRET" \
  https://web.novadesko.com/api/v1/document-types

[
  { "id": 2, "name": "Factures", "slug": "invoices", "prefix": "FAC" },
  { "id": 6, "name": "Devis", "slug": "quotes", "prefix": "DEV" }
]

Collega Claude ai tuoi dati Novadesko: fai le tue domande in linguaggio naturale, Claude accede in lettura alle tue aziende (cifre, documenti, clienti, insoluti).

1. 1 Genera un URL segreto dal tuo spazio Novadesko su web.novadesko.com/integrations/claude.
2. 2 In claude.ai: Impostazioni › Connettori › Aggiungi connettore personalizzato, poi incolla l'URL.
3. 3 Claude può così interrogare le tue aziende in sola lettura, direttamente nelle tue conversazioni.

Protocollo MCP (JSON-RPC: initialize, tools/list, tools/call) · 9 strumenti disponibili, tra cui get_company_overview.

// JSON-RPC (MCP)
{ "jsonrpc": "2.0", "method": "tools/call",
  "params": { "name": "get_company_overview", "arguments": { "company_id": 1 } },
  "id": 1 }