API REST per Manutenzione: Documentazione per Fornitori MES

Quando avvii un'integrazione MES-CMMS, la prima cosa che ti chiede il fornitore MES è "dammi la documentazione delle API". Senza un documento ben strutturato, lo scambio di informazioni dura settimane: il fornitore chiede, tu rispondi via email, lui chiede chiarimenti, tu rispondi di nuovo, l'integrazione partirà dopo 4-8 settimane di ping-pong. Vediamo come fornire una documentazione che riduce i tempi di integrazione a 3-5 giorni.

Cosa deve contenere la documentazione API

I 7 elementi essenziali:

1. Base URL: l'indirizzo HTTPS dell'azienda (es. https://manutentya.tuoazienda.it).
2. Autenticazione: come ottenere e usare il token.
3. Lista endpoint: tutti i POST/GET disponibili con descrizione.
4. Schema payload: per ogni endpoint, struttura JSON di richiesta e risposta.
5. Esempi cURL: chiamate complete da copia/incollare.
6. Codici di errore: cosa significa ogni HTTP status restituito.
7. Mappatura macchinari: tabella codice MES → codice CMMS.

Esempio struttura documentazione

1. Introduzione

Spiegazione del flusso: il MES chiama l'API quando rileva eventi (fermi, allarmi, ripartenze). Il CMMS gestisce ticket di manutenzione di conseguenza.

2. Autenticazione

Tutte le chiamate richiedono header HTTP:

Authorization: Bearer {API_KEY}
Content-Type: application/json

L'API_KEY è generata dal pannello admin del CMMS e fornita al fornitore MES tramite canale sicuro (PEC, file cifrato, password manager condiviso).

3. Endpoint disponibili

POST /api/mes/fermo

Notifica fermo macchina. Apre ticket di manutenzione (se policy lo permette).

Request body:

{
  "codice_mes": "string (richiesto)",
  "timestamp": "string ISO 8601 (richiesto)",
  "motivo": "string (opzionale)",
  "durata_prevista_sec": "integer (opzionale)",
  "operatore_segnalante": "string (opzionale)"
}

Response 201 Created:

{
  "success": true,
  "ticket_id": 12345,
  "ticket_code": "#TCK/2026/000123",
  "anti_flapping_delay_sec": 60
}

Response 200 OK (anti-flapping attivo):

{
  "success": true,
  "queued": true,
  "evaluation_in_sec": 60
}

POST /api/mes/ripartenza

Notifica ripartenza macchina. Se ticket auto-creato non ancora preso in carico → chiusura automatica. Se ticket ancora in coda anti-flapping → cancellazione senza apertura.

Request body:

{
  "codice_mes": "string (richiesto)",
  "timestamp": "string ISO 8601 (richiesto)",
  "fermo_durata_sec": "integer (opzionale)"
}

GET /api/mes/test

Verifica connettività e autenticazione. Risposta 200 = tutto OK.

4. Esempi cURL completi

Per ogni endpoint, esempio completo da copiare:

curl -X POST https://manutentya.tuoazienda.it/api/mes/fermo \
  -H "Authorization: Bearer abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "codice_mes": "PRESSA-A1",
    "timestamp": "2026-05-01T14:23:45Z",
    "motivo": "Anomalia pressione iniezione",
    "durata_prevista_sec": 600
  }'

5. Codici di errore

6. Mappatura macchinari

Tabella esportabile in Excel:

Auto-apertura "No" significa: il MES manda comunque la chiamata, ma il CMMS non crea ticket automatico (il fermo è considerato troppo "rumoroso" per gestione automatica, l'operatore decide manualmente).

7. FAQ e troubleshooting

Le 5-10 domande più frequenti del fornitore MES, con risposta.

Best practice per la documentazione

• Versionata: ogni release del CMMS ha una versione documentazione (es. v1.2.0).
• Versioni "con chiave" e "senza chiave": la prima da consegnare via canale sicuro, la seconda da inviare via email per discussioni.
• Auto-generata idealmente: documentazione mantenuta in sync con il codice tramite OpenAPI/Swagger.
• Esempio funzionante: alla fine, tre chiamate cURL completi che il fornitore può eseguire in 2 minuti.
• Contatto supporto: chi chiamare in caso di problemi durante l'integrazione.

OpenAPI/Swagger come standard

OpenAPI 3.0 (ex Swagger) è lo standard moderno per documentare API REST. Vantaggi:

• File YAML/JSON leggibile da macchine.
• UI interattiva (Swagger UI) per testing senza scrivere codice.
• Generazione automatica di SDK in vari linguaggi (Python, Node.js, Java, C#).
• Standard riconosciuto a livello mondiale.

Se il CMMS espone OpenAPI, il fornitore MES può importare la specifica e generare SDK in 5 minuti. Tempo di integrazione totale: 3-5 giorni.

Come fa Manutentya

Il modulo Integrazione MES di Manutentya genera automaticamente:

• PDF documentazione con tutti gli endpoint, esempi cURL, mappatura macchinari, policy.
• Versione "con chiave" per consegna via canale sicuro.
• Versione "senza chiave" per discussioni email.
• Compatibilità OpenAPI 3.0 per generazione SDK.

Per approfondire l'integrazione, leggi anche come integrare MES e CMMS per apertura ticket automatica.

Richiedi una demo di Manutentya.