API de Datos

Endpoints de colecciones, plantillas, extracciones, registros, reportes, reportes programados y archivos.

Colecciones

Las colecciones son contenedores de datos estructurados definidos por el usuario.

Metodo	Endpoint	Descripcion
`GET`	`/api/v1/data/collections`	Listar colecciones
`POST`	`/api/v1/data/collections`	Crear coleccion
`GET`	`/api/v1/data/collections/{collection_id}`	Obtener coleccion
`PUT`	`/api/v1/data/collections/{collection_id}`	Actualizar coleccion
`DELETE`	`/api/v1/data/collections/{collection_id}`	Eliminar coleccion

{
  "name": "Lecturas de Temperatura",
  "schema": {
    "sensor_id": "string",
    "value": "number",
    "unit": "string",
    "timestamp": "datetime"
  }
}

Plantillas de Datos

Las plantillas definen estructuras reutilizables para colecciones:

Metodo	Endpoint	Descripcion
`GET`	`/api/v1/data/templates`	Listar plantillas
`POST`	`/api/v1/data/templates`	Crear plantilla
`GET`	`/api/v1/data/templates/{template_id}`	Obtener plantilla

Las plantillas incluyen validaciones, valores por defecto y campos calculados.

Extracciones de Datos

Las extracciones procesan datos con IA para obtener informacion estructurada:

Metodo	Endpoint	Descripcion
`POST`	`/api/v1/data/extractions`	Crear extraccion
`GET`	`/api/v1/data/extractions/{extraction_id}`	Estado de extraccion

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

El proceso es asincrono. El estado progresa: pending > processing > completed / failed.

Registros

Los registros son las filas de datos dentro de una coleccion:

Metodo	Endpoint	Descripcion
`GET`	`/api/v1/data/collections/{collection_id}/records`	Listar registros
`POST`	`/api/v1/data/collections/{collection_id}/records`	Crear registro
`PUT`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Actualizar registro
`DELETE`	`/api/v1/data/collections/{collection_id}/records/{record_id}`	Eliminar registro

Los registros se validan contra el schema de la coleccion antes de almacenarse.

Reportes

Metodo	Endpoint	Descripcion
`GET`	`/api/v1/data/reports`	Listar reportes
`POST`	`/api/v1/data/reports`	Generar reporte
`GET`	`/api/v1/data/reports/{report_id}`	Obtener reporte

{
  "title": "Reporte Mensual de Temperatura",
  "collection_id": "col_abc123",
  "date_range": { "start": "2026-03-01", "end": "2026-03-31" },
  "format": "pdf",
  "include_charts": true
}

Reportes Programados

Automatiza la generacion periodica de reportes:

Metodo	Endpoint	Descripcion
`POST`	`/api/v1/data/reports/scheduled`	Crear reporte programado
`GET`	`/api/v1/data/reports/scheduled`	Listar programados
`DELETE`	`/api/v1/data/reports/scheduled/{schedule_id}`	Cancelar programacion

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

Archivos

Metodo	Endpoint	Descripcion
`POST`	`/api/v1/data/files`	Subir archivo
`GET`	`/api/v1/data/files/{file_id}`	Obtener metadatos
`GET`	`/api/v1/data/files/{file_id}/url`	URL de descarga
`DELETE`	`/api/v1/data/files/{file_id}`	Eliminar archivo

Los archivos se almacenan en GCS con cifrado en reposo. Formatos soportados: PDF, CSV, XLSX, JSON, imágenes (PNG, JPG). Tamaño maximo: 50 MB por archivo.

Las URLs de descarga son temporales y expiran en 1 hora. Solicita una nueva URL si ha expirado.