Indice
Tre canali Attivazione Autenticazione Creare un work order Leggere l'avanzamento Modificare Cambiare stato Eliminare Il work order restituito Errori Esempi Tabella di scambio MQTT Anagrafiche, consumi e magazzino Dalla versione 1Tre canali equivalenti
| Canale | Quando usarlo |
|---|---|
| API REST | Integrazioni nuove, da qualsiasi linguaggio. |
Tabella di scambio su database (writewo / readwo) | ERP che già scrivevano nel database della versione 1, o software che preferiscono scrivere in una tabella. |
| MQTT | Sistemi a messaggi, SCADA, gateway IoT. |
Tutti i canali applicano le stesse regole: validazione dei dati, coda massima di 15 work order da fare, un solo work order in lavorazione, stato della licenza. Ogni operazione, anche rifiutata, è registrata sulla postazione con il canale di provenienza, utile per il supporto.
Attivazione
I canali si attivano in Impostazioni › Integrazione work order, riservata all'amministratore. La chiave per REST e MQTT si genera nella stessa sezione.
API REST: autenticazione
- URL di base:
http://<pc-macchina>:1880/api/erp(oppurehttps://se sul PC è installato un certificato). - Formato: JSON UTF-8 in ingresso e in uscita.
- Date:
AAAA-MM-GGper la consegna; date e ore restituite comeAAAA-MM-GG HH:mm:ssnel fuso orario della macchina.
Ogni richiesta deve avere l'header:
X-Api-Key: rti_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
La chiave è mostrata una sola volta: RTIndustry ne conserva solo l'impronta, quindi una chiave persa non si recupera ma si rigenera. Rigenerarla o revocarla la invalida subito.
| Situazione | Risposta |
|---|---|
| Nessuna chiave generata | 503 API non attiva |
| Header assente o chiave errata | 401 |
| Configurazione iniziale non completata | 409 |
| Licenza in sola lettura o bloccata | 403 sulle scritture (le letture funzionano) |
Creare un work order — POST /workorders
{
"erp_id": "ODP-2026/0001",
"description": "Flangia DN80 acciaio",
"qty_requested": 50,
"item_code": "FL-DN80",
"program_name": "O1001",
"program_number": "1001",
"customer_code": "C-0042",
"customer_name": "Cliente di esempio",
"order_number": "ORD-778",
"operator_name": "Mario",
"target_time": 30,
"target_energy": 150,
"due_date": "2026-10-15",
"notes": "Priorità alta",
"extra": { "receipt": "BOLLA-77", "wo_value": 1250.50, "spare1": "lotto A" }
}
| Campo | Obbligatorio | Tipo | Note |
|---|---|---|---|
erp_id | Sì | testo (max 100: lettere, numeri, . _ / -) | Identificativo univoco del work order nel gestionale |
description | Sì | testo | |
qty_requested | Sì | intero ≥ 1 | Pezzi richiesti |
item_code, program_name, program_number, customer_code, customer_name, order_number, operator_name, notes | No | testo (max 500) | |
target_time | No | intero ≥ 0 | Tempo ciclo obiettivo (secondi per pezzo) |
target_energy | No | intero ≥ 0 | Energia obiettivo (Wh per pezzo) |
due_date | No | AAAA-MM-GG | Data di consegna |
extra | No | oggetto | Solo receipt, wo_value, spare1…spare5, restituiti invariati |
Risposta 201 con il work order completo (vedi sotto). Il work order entra nella colonna Da fare (status: "REQUESTED"); l'operatore lo avvia dal Kanban, oppure lo avvia il gestionale con un cambio di stato.
Leggere l'avanzamento — GET /workorders
| Parametro | Esempio | Significato |
|---|---|---|
status | RUNNING | Stato del work order |
column | in_progress | requested, in_progress, done |
source | erp | erp, manual (dal Kanban), machine (creati dalla macchina) |
updatedSince | 2026-09-27 08:00:00 | Solo work order aggiornati da questo momento (ora locale della macchina) |
limit, offset | 100, 0 | Paginazione (massimo 500 per pagina) |
Risposta: { "workorders": [ ... ], "total": 42, "limit": 100, "offset": 0 }. Per un aggiornamento incrementale conviene interrogare ogni 1–5 minuti con updatedSince uguale al last_update più recente ricevuto.
Dettaglio: GET /workorders/{erp_id}, con l'erp_id codificato nell'URL (per esempio ODP-2026%2F0001). 404 se non esiste.
Modificare — PUT /workorders/{erp_id}
Stessi campi della creazione, tutti facoltativi (erp_id non è modificabile). I campi extra si fondono con quelli esistenti. Si può modificare anche un work order in lavorazione, per esempio per aumentare la quantità: lo stato non cambia.
Cambiare stato — POST /workorders/{erp_id}/status
{ "status": "RUNNING" }
status:RUNNING,PAUSED,STOPPED,COMPLETED,SET-UP,REWORK,MAINTENANCE,CLEANING,FAULT, oppureREQUESTED(torna in «Da fare»);- in alternativa
column:requested,in_progress(=RUNNING),done(=COMPLETED).
RUNNING mette in pausa l'eventuale altro work order in lavorazione (uno solo alla volta); COMPLETED imposta la data di fine. Risposta: il work order aggiornato.
Eliminare — DELETE /workorders/{erp_id}
Eliminazione logica: il work order resta nello storico interno. 400 se è in lavorazione.
Il work order restituito
{
"erp_id": "ODP-2026/0001", "id": "ERP-ODP-2026_0001", "source": "erp",
"status": "RUNNING", "column": "in_progress",
"description": "Flangia DN80 acciaio", "item_code": "FL-DN80",
"qty_requested": 50, "qty_done": 18, "qty_scrap": 1, "qty_good": 17, "qty_rework": 0,
"target_time": 30, "cycletime_avg": 28.4, "production_time": 511,
"mwt_total": 640, "mwt_running": 540, "mwt_paused": 60, "mwt_stopped": 0, "mwt_alarm": 0,
"mwt_maintenance": 0, "mwt_cleaning": 0, "mwt_reworked": 0, "mwt_setup": 40,
"energy_quantity": 2150.5, "energy_pieces": 119.5, "energy_saving": 20.3,
"due_date": "2026-10-15", "start_date": "2026-09-27 08:02:11", "end_date": null,
"creation_date": "2026-09-27 07:55:00", "last_update": "2026-09-27 08:13:40",
"extra": { "receipt": "BOLLA-77", "wo_value": 1250.5, "spare1": "lotto A" }
}
| Campo | Significato |
|---|---|
qty_done / qty_scrap / qty_good | Pezzi prodotti / scartati dall'operatore / buoni |
mwt_* | Secondi trascorsi dal work order in ciascuno stato impostato dall'operatore (lavorazione, pausa, fermo, guasto, manutenzione, pulizia, rilavorazione, attrezzaggio); mwt_total è la somma |
production_time | Secondi di macchina in lavorazione per il work order |
cycletime_avg | Tempo ciclo medio (secondi per pezzo) |
energy_* | Energia consumata (Wh), Wh per pezzo, risparmio % rispetto a target_energy |
I contatori sono salvati ogni 5 secondi: una lettura può essere indietro al massimo di 5 secondi.
Errori
Tutti gli errori hanno la forma { "error": "messaggio in italiano", ... }.
| Codice | Quando | Dettagli |
|---|---|---|
400 | Dati non validi | dettagli: [{ "campo": "qty_requested", "messaggio": "deve essere almeno 1" }]: sono elencati tutti i campi errati |
400 | Eliminazione di un work order in lavorazione | codice: "in_lavorazione" |
401 | Chiave assente o errata | |
403 | Licenza scaduta o bloccata (scritture) | |
404 | Work order inesistente o endpoint sconosciuto | |
409 | erp_id già esistente | codice: "erp_id_duplicato" |
409 | Più di 15 work order in «Da fare» sulla postazione | codice: "coda_piena" |
503 | API non attiva (nessuna chiave) |
Esempi
curl -X POST http://pc-macchina:1880/api/erp/workorders \
-H "X-Api-Key: $RTI_KEY" -H "Content-Type: application/json" \
-d '{"erp_id":"ODP-1001","description":"Albero motore","qty_requested":200}'
curl "http://pc-macchina:1880/api/erp/workorders?source=erp&updatedSince=2026-09-27%2008:00:00" \
-H "X-Api-Key: $RTI_KEY"
$h = @{ "X-Api-Key" = $env:RTI_KEY }
Invoke-RestMethod -Uri "http://pc-macchina:1880/api/erp/workorders/ODP-1001" -Headers $h
Tabella di scambio su database
Stesso contratto della versione 1: il sistema esterno scrive in writewo, RTIndustry elabora le righe e aggiorna readed; l'avanzamento si legge da readwo. Le tabelle possono stare:
- nel database di RTIndustry, per software installati sullo stesso PC (
readwoè una vista sempre aggiornata); - in un MySQL aziendale: RTIndustry si collega al database indicato, legge
writewoe riscrive l'avanzamento inreadwo. Il pulsante «Crea tabelle mancanti» crea le due tabelle con lo schema della versione 1. La password è conservata cifrata sulla postazione.
Il controllo avviene ogni 10 secondi (configurabile).
Ciclo di una riga
readed scritto dall'ERP | Significato | Esito scritto da RTIndustry |
|---|---|---|
0 | Nuovo work order | 1 e kanbanwoid = id del work order in RTIndustry |
2 | Work order modificato (anche se in lavorazione) | 1 |
5 (nuovo nella 2.0) | Eliminare il work order | 1 |
3+rejectedreason: rifiuto della postazione (coda piena, work order in lavorazione non eliminabile, licenza in sola lettura). RTIndustry ritenta da sé ogni minuto.4+rejectedreason: dati non validi (per esempiodescriptionmancante). L'ERP corregge la riga e rimettereaded = 2.
L'identificativo del work order (erp_id) è l'id della riga di writewo. Le righe con serial o workstation valorizzati vengono elaborate solo dalla postazione corrispondente (tabella condivisa tra più macchine); se vuoti, le elabora qualsiasi postazione.
Cambiare stato
- colonna
status(nuova nella 2.0, facoltativa):RUNNING,PAUSED,COMPLETED,REQUESTED… conreaded = 2. È un comando: dopo l'esecuzione RTIndustry la riporta aNULL, così una modifica successiva (per esempio della quantità) non annulla una pausa decisa dall'operatore; - colonna
columndella versione 1:in_progressodone. Per riportare in «Da fare» un work order già avviato usarestatus = 'REQUESTED'.
-- Nuovo work order
INSERT INTO writewo (readed, description, itemcode, quantity, duedate)
VALUES (0, 'Albero motore', 'AX-12', 200, '2026-10-15');
-- Avviarlo
UPDATE writewo SET status = 'RUNNING', readed = 2 WHERE id = 42;
-- Avanzamento
SELECT id, status, qty_done, qty_scrap, mwt_running FROM readwo WHERE id = 'ERP-42';
MQTT
Broker integrato sulla porta 1883 della postazione.
| Topic | Direzione | Contenuto |
|---|---|---|
{deviceSN}/read | uscita | Telemetria (leggibile senza credenziali) |
{deviceSN}/write | ingresso | Comandi sui work order (solo client autenticati) |
{deviceSN}/write/result | uscita | Esito di ogni comando |
{deviceSN}/wo | uscita | Evento a ogni variazione di un work order esterno (anche dall'operatore o dalla produzione) |
Autenticazione: nome utente libero (per esempio erp), password = chiave API (la stessa della REST). Credenziali errate: connessione rifiutata. Un client senza credenziali può leggere la telemetria, ma i suoi comandi vengono scartati. Nessun client può pubblicare su /read, /write/result o /wo.
Comandi
{ "id": "c-1", "action": "create", "erp_id": "ODP-1", "data": { "description": "Albero", "qty_requested": 10 } }
{ "id": "c-2", "action": "update", "erp_id": "ODP-1", "data": { "qty_requested": 12 } }
{ "id": "c-3", "action": "status", "erp_id": "ODP-1", "status": "RUNNING" }
{ "id": "c-4", "action": "delete", "erp_id": "ODP-1" }
{ "id": "c-5", "action": "get", "erp_id": "ODP-1" }
{ "id": "c-6", "action": "list", "data": { "status": "RUNNING" } }
data ha gli stessi campi della REST; id è un identificativo a scelta del mittente, restituito nell'esito.
Esiti ed eventi
{ "id": "c-1", "action": "create", "erp_id": "ODP-1", "ok": true, "status": 201, "result": { "erp_id": "ODP-1", "status": "REQUESTED" } }
{ "id": "c-4", "action": "delete", "erp_id": "ODP-1", "ok": false, "status": 400, "error": "Work order in lavorazione: impossibile eliminarlo", "codice": "in_lavorazione" }
{ "evento": "status", "eliminato": false, "workorder": { "erp_id": "ODP-1", "status": "RUNNING", "qty_done": 3 } }
mosquitto_pub -h pc-macchina -u erp -P "$RTI_KEY" -t "RTI-XXXX/write" \
-m '{"id":"1","action":"status","erp_id":"ODP-1001","status":"RUNNING"}'
mosquitto_sub -h pc-macchina -u erp -P "$RTI_KEY" -t "RTI-XXXX/write/result" -t "RTI-XXXX/wo"
Anagrafiche, consumi e magazzino
Dalla versione 2.5 RTIndustry tiene un'anagrafica di clienti, materiali e articoli con distinta base e calcola il materiale consumato da ogni work order; dalla 2.7 gestisce anche le giacenze. Il contratto dei work order descritto sopra non cambia: le novità si aggiungono. Senza il modulo nella licenza queste chiamate rispondono 403 con codice: "modulo_assente", mentre i work order funzionano come prima.
Codici dei work order in ingresso
Su tutti i canali (REST, tabella di scambio, MQTT), quando un work order arriva con customer_code, customer_name o item_code:
| Situazione | Cosa fa RTIndustry |
|---|---|
| Codice già in anagrafica | Collega il WO al cliente o all'articolo (maiuscole e minuscole indifferenti) |
Solo customer_name | Cerca il cliente per nome, senza badare a maiuscole, accenti e punteggiatura |
| Codice sconosciuto | Censisce il cliente o l'articolo con i dati del WO, segnato «da completare» |
| Censimento spento (Impostazioni › Integrazione work order) | Il WO entra scollegato, come nella 2.4 |
Nessun work order viene rifiutato per un problema di anagrafica, e i testi inviati restano esattamente come sono.
Clienti, materiali e articoli via REST
| Endpoint | Funzione |
|---|---|
GET /customers?q=&page=&pageSize=&to_complete=1 | Elenco clienti |
GET /customers/{code} · PUT /customers/{code} | Lettura · upsert per codice |
GET /materials · GET/PUT /materials/{code} | Materiali |
GET /articles · GET/PUT /articles/{code} | Articoli con distinta |
PUT crea il record se il codice non esiste (201), altrimenti modifica solo i campi inviati (200). Gli errori sono elencati tutti in dettagli (400).
PUT /customers/C-0042
{ "name": "Meccanica Rossi S.r.l.", "vat_number": "IT01234567890", "city": "Palermo" }
PUT /materials/LAM-304-20
{ "description": "Lamiera inox AISI 304 sp. 2 mm", "uom_stock": "kg", "uom_use": "m2", "conversion": 15.86, "unit_cost": 4.20 }
PUT /articles/FL-DN80
{ "description": "Flangia DN80 inox", "type": "Lamiera tagliata", "default_customer_code": "C-0042",
"program_name": "O1001", "target_time": 42,
"bom": [ { "material_code": "LAM-304-20", "qty": 0.35, "scrap_pct": 8 }, { "material_code": "GUA-EPDM-80", "qty": 1 } ] }
uom_stockè l'unità di acquisto e di magazzino,uom_usequella di consumo usata nella distinta;conversion= quanteuom_stockvale 1uom_use(obbligatoria tra grandezze diverse). Unità:pz,g,kg,t,mm,m,mm2,m2,cm3,dm3,l,m3.bomè la distinta: quantità per un pezzo nell'unità di consumo, sfrido in percentuale. Inviandola si sostituisce quella esistente.
Consumi di materiale
GET /workorders/{erp_id}/consumi: consumo del work order, in_corso (sui pezzi fatti finora, con il previsto per la quantità richiesta) o consolidato (WO completato). GET /consumi?dateFrom=&dateTo=&customer_code=&item_code=: consumi dei work order chiusi nel periodo.
{ "erp_id": "ODP-1001", "stato": "in_corso", "righe": [
{ "material_code": "LAM-304-20", "uom_use": "m2", "qty_use": 12.096, "uom_stock": "kg", "qty_stock": 191.84,
"cost": 805.74, "qty_use_expected": 18.9 } ] }
Pezzi consumati = contapezzi della macchina + pezzi aggiunti a mano (gli scarti sono già compresi). Gli stessi consumi sono nella tabella readconsumi (accanto a readwo, con i nomi in stile versione 1) e sul topic MQTT {deviceSN}/consumi alla chiusura di ogni work order.
Magazzino
GET /giacenze?q=&sottoscorta=1: giacenza di ogni materiale nell'unità di magazzino, con gestore (rtindustry se RTIndustry scarica da solo il materiale alla chiusura dei WO, erp se lo scarico lo fa il gestionale con i consumi). POST /movimenti: carico o rettifica dal gestionale.
POST /movimenti
{ "material_code": "LAM-304-20", "kind": "load", "qty": 2, "uom": "m2", "document": "DDT 99", "lot": "L-2610" }
→ 201 { "material_code": "LAM-304-20", "kind": "load", "qty": 31.72, "uom_stock": "kg", "giacenza": 291.769, ... }
kind: load (carico, quantità positiva) o adjust (rettifica con segno). uom è facoltativa: un'unità della stessa grandezza o l'unità di consumo, convertita con il fattore del materiale. La giacenza può essere negativa: si segnala, non si blocca.
Dalla versione 1
Chi non può adeguare l'ERP continua a usare le tabelle. Per passare all'API REST:
| Prima (versione 1, tabelle MySQL) | Ora (2.0, API) |
|---|---|
INSERT INTO writewo (...) con readed = 0 | POST /api/erp/workorders |
UPDATE writewo ... readed = 2 (modifica) | PUT /api/erp/workorders/{erp_id} |
Attendere readed = 1 | Risposta 201 immediata: il work order è già in «Da fare» |
readed = 3 (troppi work order / errore postazione) | 409 con codice: "coda_piena" (o altro messaggio) |
readed = 4 (errore di lettura) | 400 con l'elenco dei campi errati in dettagli |
SELECT * FROM readwo | GET /api/erp/workorders (+ updatedSince) |
column in writewo | POST /api/erp/workorders/{erp_id}/status |
| Nessun equivalente | DELETE /api/erp/workorders/{erp_id} |
Campo writewo | Campo API |
|---|---|
kanbanwoid / id ERP | erp_id |
programname, programnumber | program_name, program_number |
description, itemcode | description, item_code |
quantity | qty_requested |
customername, customercode | customer_name, customer_code |
operatorname, notes | operator_name, notes |
duedate, targettime, targetenergy | due_date, target_time, target_energy |
receipt, wovalue, spare1…spare5 | extra.receipt, extra.wo_value, extra.spare1…spare5 |
client, plant, workstation, serial | Non servono: li assegna la postazione che riceve la chiamata |
In readwo e nella risposta API qty_done, qty_scrap, qty_requested, mwt_*, cycletime_avg, start_date, end_date e status hanno lo stesso nome; mwt_downtime non esiste più (è la somma di mwt_stopped e mwt_alarm).