API dei Dati

Endpoint di collezioni, template, estrazioni, record, report, report programmati e file.

Collezioni

Le collezioni sono contenitori di dati strutturati definiti dall'utente.

Metodo	Endpoint	Descrizione
`GET`	`/api/v1/data/collections`	Elenco collezioni
`POST`	`/api/v1/data/collections`	Crea collezione
`GET`	`/api/v1/data/collections/{collection_id}`	Ottieni collezione
`PUT`	`/api/v1/data/collections/{collection_id}`	Aggiorna collezione
`DELETE`	`/api/v1/data/collections/{collection_id}`	Elimina collezione

{
  "name": "Letture di Temperatura",
  "schema": {
    "sensor_id": "string",
    "value": "number",
    "unit": "string",
    "timestamp": "datetime"
  }
}

Template dei Dati

I template definiscono strutture riutilizzabili per le collezioni:

Metodo	Endpoint	Descrizione
`GET`	`/api/v1/data/templates`	Elenco template
`POST`	`/api/v1/data/templates`	Crea template
`GET`	`/api/v1/data/templates/{template_id}`	Ottieni template

I template includono validazioni, valori predefiniti e campi calcolati.

Estrazioni di Dati

Le estrazioni elaborano dati con IA per ottenere informazioni strutturate:

Metodo	Endpoint	Descrizione
`POST`	`/api/v1/data/extractions`	Crea estrazione
`GET`	`/api/v1/data/extractions/{extraction_id}`	Stato dell'estrazione

{
  "source": "file_id_or_url",
  "template_id": "template_abc",
  "extraction_type": "ai",
  "model": "gemini-2.0-flash"
}

Il processo e asincrono. Lo stato progredisce: pending > processing > completed / failed.

Record

I record sono le righe di dati all'interno di una collezione:

Metodo	Endpoint	Descrizione
`GET`	`/api/v1/data/collections/{collection_id}/records`	Elenco record
`POST`	`/api/v1/data/collections/{collection_id}/records`	Crea record
`PUT`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Aggiorna record
`DELETE`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Elimina record

I record vengono validati contro lo schema della collezione prima dell'archiviazione.

Report

Metodo	Endpoint	Descrizione
`GET`	`/api/v1/data/reports`	Elenco report
`POST`	`/api/v1/data/reports`	Genera report
`GET`	`/api/v1/data/reports/{report_id}`	Ottieni report

{
  "title": "Report Mensile Temperature",
  "collection_id": "col_abc123",
  "date_range": { "start": "2026-03-01", "end": "2026-03-31" },
  "format": "pdf",
  "include_charts": true
}

Report Programmati

Automatizza la generazione periodica dei report:

Metodo	Endpoint	Descrizione
`POST`	`/api/v1/data/reports/scheduled`	Crea report programmato
`GET`	`/api/v1/data/reports/scheduled`	Elenco programmati
`DELETE`	`/api/v1/data/reports/scheduled/{schedule_id}`	Cancella programmazione

{
  "report_config": { "collection_id": "col_abc123", "format": "pdf" },
  "frequency": "weekly",
  "day_of_week": "monday",
  "recipients": ["user_id_1", "user_id_2"],
  "notify_channels": ["email"]
}

File

Metodo	Endpoint	Descrizione
`POST`	`/api/v1/data/files`	Carica file
`GET`	`/api/v1/data/files/{file_id}`	Ottieni metadati
`GET`	`/api/v1/data/files/{file_id}/url`	URL di download
`DELETE`	`/api/v1/data/files/{file_id}`	Elimina file

I file vengono archiviati in GCS con crittografia a riposo. Formati supportati: PDF, CSV, XLSX, JSON, immagini (PNG, JPG). Dimensione massima: 50 MB per file.

Gli URL di download sono temporanei e scadono in 1 ora. Richiedi un nuovo URL se e scaduto.