REST API

DiKAS offre un'ampia REST API con oltre 340 endpoint pubblici in 34 ambiti. In questo modo è possibile integrare DiKAS nella propria infrastruttura esistente. (Gli endpoint interni e legacy /rest/ sono volutamente nascosti nel riferimento pubblico.)

Autenticazione

L'API utilizza token JWT Bearer per l'autenticazione.

Richiedere un token

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin"
}

Risposta:

{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIH...",
    "expiresIn": 3600
  },
  "isSuccess": true
}

Utilizzare il token

Impostare il token nell'header Authorization:

GET /api/v1/articles
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Rinnovare il token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "accessToken": "eyJhbGciOiJI...",
  "refreshToken": "dGhpcyBpcyBh..."
}

Formato dell'API

Tutte le risposte seguono lo schema:

{
  "data": { ... },
  "isSuccess": true,
  "message": null,
  "errors": null
}

In caso di errore:

{
  "data": null,
  "isSuccess": false,
  "message": "Articolo non trovato",
  "errors": ["L'articolo con ID 'art_123' non esiste"]
}

Panoramica degli endpoint

Articoli

Metodo	Endpoint	Descrizione
GET	/api/v1/articles	Recuperare tutti gli articoli
GET	/api/v1/articles/{id}	Recuperare un singolo articolo
POST	/api/v1/articles	Creare un articolo
PUT	/api/v1/articles/{id}	Aggiornare un articolo
DELETE	/api/v1/articles/{id}	Eliminare un articolo
GET	/api/v1/article-groups	Recuperare tutti i gruppi
POST	/api/v1/article-groups	Creare un gruppo

Esempio: creare un articolo

POST /api/v1/articles
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "name": "Cola 0,3l",
  "price": 3.50,
  "taxClass": 0,
  "groupId": "artgrp_abc123"
}

Risposta (201 Created):

{
  "data": {
    "id": "art_def456",
    "name": "Cola 0,3l",
    "price": 3.50,
    "taxClass": 0,
    "groupId": "artgrp_abc123",
    "isActive": true,
    "createdDate": "2026-03-05T18:30:00Z",
    "changedDate": "2026-03-05T18:30:00Z"
  },
  "isSuccess": true
}

Clienti

Metodo	Endpoint	Descrizione
GET	/api/v1/customers	Tutti i clienti
GET	/api/v1/customers/{id}	Singolo cliente
POST	/api/v1/customers	Creare un cliente
PUT	/api/v1/customers/{id}	Aggiornare un cliente
DELETE	/api/v1/customers/{id}	Eliminare un cliente
POST	/api/v1/customers/{id}/credit	Ricaricare il credito
POST	/api/v1/customers/{id}/payout	Liquidare il credito
GET	/api/v1/customers/{id}/transactions	Cronologia del credito

Tavoli

Metodo	Endpoint	Descrizione
GET	/api/v1/tables	Tutti i tavoli
GET	/api/v1/tables/{id}	Singolo tavolo
POST	/api/v1/tables	Creare un tavolo
POST	/api/v1/tables/{id}/gang	Cambiare portata
POST	/api/v1/tables/{id}/cleaned	Contrassegnare come pulito

Ordini e pagamenti

Metodo	Endpoint	Descrizione
POST	/api/v1/open-bons	Effettuare un ordine
POST	/api/v1/open-bons/batch	Più ordini
POST	/api/v1/payments/direct-sale	Vendita diretta
POST	/api/v1/payments/table	Pagamento al tavolo
GET	/api/v1/receipts	Recuperare gli scontrini
POST	/api/v1/receipts/{id}/void	Stornare uno scontrino

Personale

Metodo	Endpoint	Descrizione
GET	/api/v1/staff	Tutti i dipendenti
POST	/api/v1/staff	Creare un dipendente
POST	/api/v1/staff/switch	Cambio cameriere

Chiusura giornaliera

Metodo	Endpoint	Descrizione
POST	/api/v1/day-close	Eseguire la chiusura giornaliera
GET	/api/v1/day-close	Tutte le chiusure giornaliere
GET	/api/v1/day-close/{id}	Singola chiusura giornaliera

Report

Metodo	Endpoint	Descrizione
GET	/api/v1/reports/revenue	Report fatturato
GET	/api/v1/reports/top-articles	Più e meno venduti
GET	/api/v1/reports/wgr	Gruppi merceologici
GET	/api/v1/reports/weekly	Analisi settimanale

Altri endpoint

Ambito	Prefisso	Endpoint
Buoni	/api/v1/vouchers	CRUD, Riscatto
Banking	/api/v1/bank-transfers	CRUD, Importazione
FinTS	/api/v1/fints	Recupero, TAN
DATEV	/api/v1/datev	Esportazione, Invio
Fatture	/api/v1/invoices	CRUD, PDF
Abbonamenti	/api/v1/subscriptions	CRUD, Fatturazione
Solleciti	/api/v1/dunning	Creazione, Invio
Spese	/api/v1/spendings	CRUD, Allegati
Rilevazione presenze	/api/v1/time-tracking	Timbratura, Report
Officina	/api/v1/work-orders	CRUD, Stato
Backup	/api/v1/restore	Caricamento
Config	/api/v1/config	Lettura, Scrittura

API Legacy

Per la compatibilità con le integrazioni esistenti sono disponibili endpoint legacy sotto /rest/:

Endpoint	Descrizione
/rest/cp/add/{key}/{plu}	Registrare un articolo
/rest/extern/customer/{key}/...	CRUD clienti
/rest/extern/voucher/{key}/...	CRUD buoni
/rest/online/{key}/...	Ordini online

Gli endpoint legacy utilizzano chiavi API anziché token JWT.

SignalR (tempo reale)

Per aggiornamenti in tempo reale (monitor cucina, officina, stato dei tavoli):

const connection = new signalR.HubConnectionBuilder()
  .withUrl("/hubs/dikas", {
    accessTokenFactory: () => jwtToken
  })
  .build();

connection.on("OrderCreated", (data) => {
  console.log("Neue Bestellung:", data);
});

connection.on("TableStatusChanged", (data) => {
  console.log("Tisch-Status:", data);
});

await connection.start();

Swagger / OpenAPI

Il riferimento API completo con tutti i 341 endpoint pubblici (34 ambiti) e gli schemi:

→ Riferimento API (Swagger) — Documentazione interattiva con funzione di ricerca

Su un'istanza DiKAS in esecuzione, Swagger è raggiungibile anche direttamente all'indirizzo https://<server>/swagger.

---

Passo successivo

→ Backup & Restore — Salvataggio dei dati