API Integrazione cliente

Dopo l'acquisto della sottoscrizione, gli utenti possono: caricare documenti in Upload, vedere e modificare i documenti parsati (Parsed file), assegnare codici EER, esportare le tabelle (parsed, history, validated), inviare i dati in History assegnandoli a un cliente, usare Validate/HP Finder e le funzioni di HP Finder. Questa documentazione elenca gli endpoint necessari per integrare il tuo software con HSE Genius.

Base URL e autenticazione

Base URL dell'API:

https://kaimakicloud.hsegenius.com/api

Le richieste devono includere l'header JWT:

Authorization: Bearer <access_token>

Login (ottenere il token)

POST /api/user/token/

Body (schema richiesto):

{
  "email": str,
  "password": str
}

Risposta: {"access": "<JWT>", "refresh": "<refresh_token>"}. Usa access nell'header Authorization: Bearer <access>.

POST /api/user/token/refresh/

Restituisce un nuovo access quando il token è scaduto.

Body (schema richiesto):

{
  "refresh": str
}
Per l'integrazione bastano token e refresh.

Upload file

Caricamento di file PDF e conferma per l'avvio del processamento. Tutti gli endpoint sotto /api/files/.

GET /api/files/upload/

Elenco dei documenti caricati (stato created) dell'utente.

POST /api/files/upload/

Body: multipart/form-data. Schema:

{
  "pdf": file,          // opzionale
  "eer_codes": [str]    // opzionale
}

Risposta: dati del documento creato (es. id, filename).

POST /api/files/upload/confirm/

Conferma i file caricati e avvia il processamento (task asincrono). Richiede sottoscrizione attiva.

Body: nessuno.

Risposta: task_id, message: "Processing started!".

DELETE /api/files/upload/{id}/

Elimina un documento caricato.

POST /api/files/upload/{id}/eer/

Aggiunge uno o più codici EER al documento.

Body (schema richiesto):

{
  "eer_codes": [str]
}
DELETE /api/files/upload/{id}/eer/{eer_code}/

Rimuove un codice EER dal documento.

POST /api/files/upload/eer/

Aggiunge un codice EER a tutti i documenti attualmente in upload.

Body (schema richiesto):

{
  "eer_code": str
}

Parsed file (dati parsati)

Documenti elaborati dopo la conferma (stato confirmed): visualizzazione, ricerca, modifica, assegnazione EER, invio a History con cliente, validazione verso HP Finder. Endpoint sotto /api/files/imported/.

Schema record: campi del record parsato usati nei body dei POST validate-constraint, validate, history, hp-finder/proceed e hp-finder/export. Tutti i campi sono opzionali.
{
  "nome_file": str|null,
  "nome_del_prodotto": str|null,
  "cod_art": str|null,
  "produttore": str|null,
  "zdhc": str|null,
  "data_di_revisione": str|null,
  "uso_appropriato": str|null,
  "stato_fisico": str|null,
  "h_punto_2": [int],
  "precautionary_statements": [str],
  "user_document_item_details": [{
    "composizione_punto_3": str|null,
    "cas": str|null,
    "ce_no": str|null,
    "reach": str|null,
    "h_punto_3": [int],
    "concentrazione": str|null,
    "svch": obj|null,
    "allegato_xiv": obj|null
  }],
  "ghs": [int],
  "pericoloso_per_lambiente": bool|null,
  "numero_onu": str|null,
  "gruppo_di_imballaggio": str|null,
  "classe": str|null,
  "punto_di_ebollizione": str,
  "ph": str,
  "cov": str,
  "notes": str|null,
  "seveso_code_h2": str,
  "seveso_code_p15": str,
  "sds_8_2_technical_controls": str|null,
  "sds_8_2_ppe_hands": str|null,
  "sds_8_2_ppe_skin": str|null,
  "sds_8_2_ppe_body": str|null,
  "sds_8_2_ppe_eyes": str|null,
  "sds_8_2_ppe_respiratory": str|null,
  "sds_8_2_hygiene_other": str|null,
  "sds_8_2_ppe_environmental_exposure": str|null,
  "sds_8_2_ppe_complementary_emergency_measures": str|null,
  "sds_8_2_ppe_thermal_risk": str|null
}
GET /api/files/imported/

Elenco record parsati. Query: eer_codes (filtro).

GET /api/files/imported/{id}/

Dettaglio di un singolo record parsato.

PATCH /api/files/imported/{id}/

Modifica dati del record (es. nome prodotto, composizione, campi item). Body: campi da aggiornare, parziali (vedi Schema record sopra).

POST /api/files/imported/{id}/eer/{eer_code}/

Aggiunge un codice EER al documento associato al record parsato.

Body: nessuno (parametri nel path).

DELETE /api/files/imported/{id}/eer/{eer_code}/

Rimuove un codice EER dal documento del record.

POST /api/files/imported/validate-constraint/

Verifica se i record selezionati possono essere validati (es. controllo EER già in HP Finder).

Body (schema): campi del record, tutti opzionali (vedi Schema record sopra).

POST /api/files/imported/validate/

Sposta i record da Parsed a Validated (HP Finder). Richiede EER assegnati.

Body (schema):

{
  "id": [int],       // opzionale, id dei record da validare
  ...campi record    // opzionali, vedi "Schema record"
}
POST /api/files/imported/history/

Assegna i record a un cliente e li invia in History.

Body (schema):

{
  "id": [int],                 // opzionale, id dei record
  "customer": int|null,        // id cliente
  "remove_from_parsed": bool,  // true per spostarli in history e toglierli da parsed
  ...campi record              // opzionali, vedi "Schema record"
}
GET /api/files/imported/export/

Export Excel della tabella parsed file (con filtri). Query: language (opzionale).

Validated / HP Finder

Dati validati (dopo validate da Parsed): elenco, export tabella, marcare come processati e spostare in History.

GET /api/files/hp-finder/

Elenco record validati. Query: eer_codes (filtro per EER).

POST /api/files/hp-finder/proceed/

Marca i record come processati e sposta in cronologia. Query obbligatoria: eer_codes.

Body (schema):

{
  "id": [int],                   // opzionale, id dei record
  "language": enum("it", "en"),  // opzionale
  "customer": int|null,          // opzionale, id cliente
  ...campi record                // opzionali, vedi "Schema record"
}
POST /api/files/hp-finder/export/

Export in Excel dei dati validati filtrati. Query: eer_codes (obbligatorio), language (opzionale, default en). Risposta: file Excel in attachment.

Body (schema):

{
  "id": [int],                   // opzionale, id dei record
  "language": enum("it", "en"),  // opzionale
  "customer": int|null,          // opzionale, id cliente
  ...campi record                // opzionali, vedi "Schema record"
}

HP Finder (codici H/P)

Elenco dei codici Hazard/Process usati per ricerche e funzioni HP Finder.

GET /api/files/hp/

Lista di tutti gli HP ordinati per h_punto.

Cronologia

Cronologia documenti (company-wide: tutti gli utenti dell'azienda).

GET /api/files/archive/

Elenco documenti in cronologia.

GET /api/files/archive/export/

Export in Excel della cronologia filtrata. Query: language (opzionale). Risposta: file Excel in attachment.

DELETE /api/files/archive/{id}/

Elimina un record dalla cronologia. Endpoint disponibile solo per admin.

Export

Export Excel da dati parsati, validati e cronologia.

GET /api/files/imported/export/

Export Excel dei dati parsati (stato confirmed). Query: language (opzionale). Risposta: attachment Excel.

GET /api/files/archive/export/

Export Excel cronologia. Query: language. Risposta: attachment Excel.

POST /api/files/hp-finder/export/

Export Excel dati validati. Query: eer_codes, language. Body: vedi schema nella sezione Validated / HP Finder. Risposta: attachment Excel.

Codici EER

Elenco dei codici EER disponibili (per upload, filtri e validazione). Sotto /api/eer/.

GET /api/eer/eer/

Lista codici EER. Utile per popolare selettori quando si assegnano EER a documenti o si filtrano parsed/validated.

Clienti

Clienti dell'azienda: per assegnare i documenti inviati in History. Sotto /api/customer/.

GET /api/customer/

Elenco clienti della company. Usare l'id nel body di POST /api/files/imported/history/ (campo customer).

Utenti

Gestione utenti dell'azienda (solo admin azienda). Sotto /api/company/.

GET /api/company/user/

Elenco utenti della company dell'utente autenticato.

POST /api/company/user/

Creazione o invito utente.

Body (schema richiesto):

{
  "email": str,
  "first_name": str,
  "last_name": str,
  "phone": str,
  "country_code": str,
  "role": enum("admin", "employee", "viewer", "auditor")
}
GET /api/company/user/{id}/

Dettaglio di un singolo utente.

PATCH /api/company/user/{id}/

Aggiorna utente (es. ruolo).

DELETE /api/company/user/{id}/

Rimuovi utente dall'azienda.

Sottoscrizione

Dettaglio della sottoscrizione attiva dell'azienda.

GET /api/payment/subscription/

Restituisce la sottoscrizione attiva della company (piano, limiti, stato). 404 se nessuna sottoscrizione attiva.

Analytics (solo admin)

Dashboard analitica sull'inventario SDS della company. Accessibile solo agli admin aziendali (CompanyAdminPermission). Tutti gli endpoint sotto /api/files/.

Questi endpoint richiedono che l'utente autenticato sia admin della propria company. Rispondono 403 Forbidden per utenti con ruolo employee o viewer.
GET /api/files/analytics/

Restituisce le metriche aggregate dell'inventario SDS. Query opzionale: user_id (filtra per singolo utente della company).

Risposta (oggetto JSON):

  • kpi — totale, validate, in_progress, svch, this_month, trend
  • ghs — top pittogrammi GHS con conteggio documenti
  • hp — top classi HP (sezione 2) con conteggio
  • dpi — % SDS per tipo DPI richiesto (sez. 8.2)
  • clienti — distribuzione SDS per cliente/cantiere
  • heatmap — upload mensili ultimi 12 mesi
  • alerts — alert normativi (svch, allegato_xiv, env_hazard)
  • extra_alerts — alert speciali: cmr, alert_conc, seveso, old_sds
  • eer — conteggio rifiuti pericolosi vs non pericolosi
  • produttori — top produttori per numero SDS
  • users — lista utenti della company con conteggio documenti (per filtro)
GET /api/files/analytics/export/

Esporta le stesse metriche della dashboard in formato file scaricabile.

Query:

  • format — csv (default) oppure xlsx
  • user_id — opzionale, filtra per utente

Risposta: attachment .csv o .xlsx con fogli separati per KPI, GHS, HP, DPI, Clienti, Upload, Conformità, EER, Produttori.