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

Documentazione interattiva (Swagger): /api/docs/

Le richieste devono includere l'header JWT:

Authorization: Bearer <access_token>

Login (ottenere il token)

POST /api/user/token/

Body: {"email": "utente@esempio.com", "password": "***"}

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

POST /api/user/token/refresh/

Body: {"refresh": "<refresh_token>"}. Restituisce un nuovo access quando il token è scaduto.

Profilo, reset password e attivazione account sono sotto /api/user/ (vedi Swagger). 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 uploaded) dell'utente.

POST /api/files/upload/

Body: multipart/form-data — campi pdf (file), title (opzionale), eer_codes (opzionale, separati da virgola).

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.

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: {"eer_codes": "code1,code2"}.

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: {"eer_code": "..."}.

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

GET /api/files/imported/

Elenco record parsati. Query: eer_codes (filtro). Filtri aggiuntivi tramite filterset (vedi Swagger).

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 Swagger per gli schemi.

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

Aggiunge un codice EER al documento associato al record parsato.

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: filtri come in list.

POST /api/files/imported/validate/

Sposta i record da Parsed a Validated (HP Finder). Body: filtri per selezionare i record. Richiede EER assegnati.

POST /api/files/imported/history/

Assegna i record a un cliente e li invia in History. Body: customer (id cliente), filtri, remove_from_parsed (true per spostarli in history e toglierli da parsed).

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 opzionale: language (es. en).

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.

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

Cronologia

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

GET /api/files/archive/

Elenco documenti in cronologia. Filtri tramite filterset (vedi Swagger per i campi).

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.

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: filtri (vedi Swagger). 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/

Body (es.): {"email": "...", "name": "...", "role": "..."}. Creazione o invito utente.

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.