Integrazione ERP e MES

Come un gestionale (ERP), un sistema di produzione (MES) o un PLC di linea crea, modifica, avvia ed elimina i work order di una postazione RTIndustry 2.0 e ne legge l'avanzamento.

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 1

Tre canali equivalenti

CanaleQuando usarlo
API RESTIntegrazioni 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.
MQTTSistemi 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

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.

SituazioneRisposta
Nessuna chiave generata503 API non attiva
Header assente o chiave errata401
Configurazione iniziale non completata409
Licenza in sola lettura o bloccata403 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" }
}
CampoObbligatorioTipoNote
erp_idSìtesto (max 100: lettere, numeri, . _ / -)Identificativo univoco del work order nel gestionale
descriptionSìtesto
qty_requestedSìintero ≥ 1Pezzi richiesti
item_code, program_name, program_number, customer_code, customer_name, order_number, operator_name, notesNotesto (max 500)
target_timeNointero ≥ 0Tempo ciclo obiettivo (secondi per pezzo)
target_energyNointero ≥ 0Energia obiettivo (Wh per pezzo)
due_dateNoAAAA-MM-GGData di consegna
extraNooggettoSolo 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

ParametroEsempioSignificato
statusRUNNINGStato del work order
columnin_progressrequested, in_progress, done
sourceerperp, manual (dal Kanban), machine (creati dalla macchina)
updatedSince2026-09-27 08:00:00Solo work order aggiornati da questo momento (ora locale della macchina)
limit, offset100, 0Paginazione (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" }

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" }
}
CampoSignificato
qty_done / qty_scrap / qty_goodPezzi 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_timeSecondi di macchina in lavorazione per il work order
cycletime_avgTempo 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", ... }.

CodiceQuandoDettagli
400Dati non valididettagli: [{ "campo": "qty_requested", "messaggio": "deve essere almeno 1" }]: sono elencati tutti i campi errati
400Eliminazione di un work order in lavorazionecodice: "in_lavorazione"
401Chiave assente o errata
403Licenza scaduta o bloccata (scritture)
404Work order inesistente o endpoint sconosciuto
409erp_id già esistentecodice: "erp_id_duplicato"
409Più di 15 work order in «Da fare» sulla postazionecodice: "coda_piena"
503API 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:

Il controllo avviene ogni 10 secondi (configurabile).

Ciclo di una riga

readed scritto dall'ERPSignificatoEsito scritto da RTIndustry
0Nuovo work order1 e kanbanwoid = id del work order in RTIndustry
2Work order modificato (anche se in lavorazione)1
5 (nuovo nella 2.0)Eliminare il work order1

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

-- 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.

TopicDirezioneContenuto
{deviceSN}/readuscitaTelemetria (leggibile senza credenziali)
{deviceSN}/writeingressoComandi sui work order (solo client autenticati)
{deviceSN}/write/resultuscitaEsito di ogni comando
{deviceSN}/wouscitaEvento 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:

SituazioneCosa fa RTIndustry
Codice già in anagraficaCollega il WO al cliente o all'articolo (maiuscole e minuscole indifferenti)
Solo customer_nameCerca il cliente per nome, senza badare a maiuscole, accenti e punteggiatura
Codice sconosciutoCensisce 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

EndpointFunzione
GET /customers?q=&page=&pageSize=&to_complete=1Elenco 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 } ] }

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 = 0POST /api/erp/workorders
UPDATE writewo ... readed = 2 (modifica)PUT /api/erp/workorders/{erp_id}
Attendere readed = 1Risposta 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 readwoGET /api/erp/workorders (+ updatedSince)
column in writewoPOST /api/erp/workorders/{erp_id}/status
Nessun equivalenteDELETE /api/erp/workorders/{erp_id}
Campo writewoCampo API
kanbanwoid / id ERPerp_id
programname, programnumberprogram_name, program_number
description, itemcodedescription, item_code
quantityqty_requested
customername, customercodecustomer_name, customer_code
operatorname, notesoperator_name, notes
duedate, targettime, targetenergydue_date, target_time, target_energy
receipt, wovalue, spare1…spare5extra.receipt, extra.wo_value, extra.spare1…spare5
client, plant, workstation, serialNon 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).

Hai bisogno di aiuto con l'integrazione? Scrivi a assistenza@rtindustry.it. Per valutare RTIndustry con il tuo gestionale: demo@rtindustry.it.