REST API

DiKAS offre un'ampia REST API con oltre 500 endpoint pubblici in più di 60 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
/rest/disco/guest/pay/{key}[/{carta}]	Pagare e fare il check-out di una carta della discoteca (ad es. cassa automatica)

Casse automatiche: posto di lavoro e stampante

Per /rest/disco/guest/pay basta una API-Key per più casse automatiche. Il posto di lavoro viene dalla chiave (Admin → Impostazioni → API-Keys); nella chiamata non serve (WorkplaceId può essere null). Ogni cassa indica la propria stampante degli scontrini nel campo Printer dell’ordine di pagamento, come id della stampante o come IP, anche con porta (192.168.1.52:9100), senza distinguere maiuscole e minuscole. Se è sconosciuta o vuota, lo scontrino viene stampato sulla stampante di destinazione del posto di lavoro o su quella predefinita; il pagamento non fallisce per questo.

Articoli sconosciuti

Se la cassa non conosce un articolo di un ordine online (né id, né numero articolo, né nome), DiKAS lo crea da sé per order, open e pay, con il nome e il prezzo del negozio e l’aliquota IVA normale dell’esercizio, senza gruppo articoli. Senza nome non viene creato nulla, un articolo disattivato resta un rifiuto (Article not found) e per ordine vengono creati al massimo 20 nuovi articoli.

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 aggiornato con 565 endpoint pubblici (60 ambiti) e gli schemi è disponibile in inglese:

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

→ Riferimento tradotto precedente — 341 endpoint; conservato come supporto fino alla prossima rigenerazione tradotta

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

---

Passo successivo

→ Backup & Restore — Salvataggio dei dati

Endpoint dei moduli

HACCP, consegne e altri moduli usano percorsi propri. Consultare Swagger/OpenAPI del server e le tabelle complete in tedesco.