API pubblica v1

L’API REST pubblica è pensata per integrazioni server-to-server, ad esempio con software CRM o di fatturazione.

URL di base: https://auto.manisma.com/api/v1

Non usare direttamente l’API Directus e non inserire mai una chiave API in JavaScript frontend.

Creare una chiave API

Apri come Admin Gestione → Chiavi API. Dai alla chiave un nome riconoscibile e scegli gli scope:

• read: contrassegna una chiave destinata alla lettura;
• write: crea o modifica le risorse scrivibili e usa gli endpoint di pianificazione.
• plan: richiede una proposta di pianificazione.

Per una normale integrazione in lettura/scrittura seleziona entrambi gli scope. Nota: il backend v1 attuale verifica write esplicitamente per POST/PATCH, ma consente GET per qualsiasi chiave attiva valida; read è quindi attualmente un’indicazione amministrativa e non ancora un blocco tecnico separato. La chiave grezza inizia con msk_, viene mostrata una sola volta e non può essere recuperata. In caso di smarrimento, crea una nuova chiave e disattiva o elimina quella vecchia.

Autenticazione

Usa una di queste intestazioni:

Authorization: Bearer msk_...

X-API-Key: msk_...

Tutti i risultati sono limitati server-side all’organizzazione della chiave. Un id di un altro tenant restituisce lo stesso 404 di un id sconosciuto.

Risorse e metodi

In v1 non esiste un endpoint DELETE.

Elenchi e paginazione

GET /clients?limit=50&page=1

• limit: da 1 a 100, predefinito 50;
• page: inizia da 1.
• search: per gli elenchi di clienti e materiali, ricerca parziale senza distinzione tra maiuscole e minuscole di testo letterale. Un segno di percentuale cerca un segno di percentuale. I clienti corrispondono per nome, e-mail o numero cliente; i materiali per SKU o nome.

{
  "data": [],
  "meta": { "total": 0, "page": 1, "limit": 50 }
}

Una risposta di dettaglio o scrittura usa { "data": { ... } }.

Clienti

Campi di lettura: id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients richiede name. I campi di scrittura consentiti sono name, customer_number, client_type, email, phone, vat_number e status. Con PATCH sono tutti opzionali, ma deve essere presente almeno un campo valido. I campi sconosciuti e un tenant_id fornito vengono ignorati.

POST /addresses crea un indirizzo per un cliente e richiede client_id. Il cliente deve appartenere allo stesso tenant.

curl -X POST 'https://auto.manisma.com/api/v1/clients' \
  -H 'Authorization: Bearer msk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bakkerij Peeters","client_type":"b2b","email":"info@example.com"}'

Commesse

I campi di lettura includono id, tenant, numero di commessa, id cliente, titolo, descrizione, priorità, stato, durata prevista, id tecnico principale, numero di tecnici richiesti, pianificazione, id indirizzo di servizio, id tipo di attività, competenze richieste e timestamp. Le note interne e del tecnico non sono esposte.

POST /jobs richiede title. Campi consentiti:

job_number, client_id, title, description, priority, status, estimated_duration_minutes, required_technicians, scheduled_date, scheduled_start, scheduled_end, service_address_id, task_type_id, required_skills.

Quando status manca, viene usato unplanned. Quando job_number manca, Manisma genera un numero con il prefisso del tenant configurato. Con PATCH job_number, status e assigned_technician_id non sono modificabili.

Le chiavi esterne per cliente, indirizzo di servizio e tipo di attività devono appartenere allo stesso tenant.

POST /jobs/:id/assign pianifica una commessa con technician_id, scheduled_start e scheduled_end. POST /jobs/:id/unassign rimuove la sua assegnazione e la riporta nella coda non pianificata; non elimina la commessa.

Proposta di pianificazione

POST /plan restituisce una proposta di pianificazione e non modifica nulla: non crea né sposta alcuna commessa. Richiede lo scope separato plan ed è limitato a 3 chiamate per organizzazione ogni 10 minuti; le chiamate successive restituiscono un chiaro errore 429. Non usa l’IA di Manisma e non consuma le azioni IA incluse nel tuo piano Manisma, perché il tuo assistente chiamante fornisce il ragionamento.

Altre risorse

• assets: dispositivi installati presso un cliente; scrivibili con POST e PATCH.

• task_types: scrivibili con POST e PATCH.

• materials: scrivibili con POST e PATCH; il prezzo di acquisto e la scorta sono leggibili e scrivibili.

• asset_models: sola lettura.

• technicians: nome, e-mail, telefono, stato attivo e competenze. Orari di lavoro, indirizzi e id utente non sono pubblici.

Errori e limiti

L’API è limitata a 600 richieste al minuto per IP di origine. Costruisci i retry con backoff esponenziale per 429, 502 ed errori di rete temporanei. Non rieseguire i retry per errori di validazione senza correggere la richiesta.