El feed OData v4 (Power BI/Excel) y el Embed SDK están disponibles. La API de consulta REST (
/api/v1/query,/api/v1/tables) está en acceso anticipado y todavía no está abierta para uso externo.
Esta sección documenta cómo integrar sistemas externos con tu datalake de ingestia.io: autenticación por clave, los feeds de datos (OData/Power BI/Excel), el SDK de embed de paneles, el formato de errores, la paginación, los límites y el estado de cada superficie.
Mapa de la sección#
| Página | Qué incluye | Estado |
|---|---|---|
| Autenticación | Claves de API, alcance, roles, revocación | Disponible |
| API de consulta (REST) | /api/v1/query y /api/v1/tables | Acceso anticipado |
| OData v4 · Power BI · Excel | Feed nativo para Power BI/Excel | Disponible |
| Embed SDK | Panel dentro de tu sistema (token firmado) | Disponible |
| Errores, límites y rate limit | Códigos HTTP, paginación, idempotencia, webhooks | Disponible |
Estados — qué significa cada uno#
- Disponible — funciona, está documentado y puede usarse en producción. Los cambios de contrato se avisan con antelación. La disponibilidad de la plataforma sigue el SLA de 99,5% mensual a partir del plan Growth (consulta /legal/sla); acompáñala en /status.
- Acceso anticipado — la capacidad existe, pero todavía no está abierta para uso externo: el contrato puede cambiar con aviso. No construyas integraciones críticas sobre ella todavía. Es el caso de la API de consulta REST.
- Planificado — todavía no disponible (p. ej.: suscripción a webhooks).
Convenciones generales#
- Base:
https://ingestia.io. Todas las rutas de datos están bajo/api/v1. - Alcance por workspace (inviolable): toda credencial tiene alcance limitado al workspace
que la emitió. La API nunca cruza datasets/buckets entre clientes y solo expone
los marts publicados (
*_goldy*_silver) — nunca la capa bronze. - Solo lectura: no existe API de escritura. Toda ruta es
GET(oPOSTsolo para enviar unSELECT). Por eso, las llamadas son idempotentes por naturaleza (ver Errores y límites). - Formato de respuesta: JSON (
application/json; charset=utf-8); OData responde JSON y$metadataen XML (EDMX). - Formato de error: siempre
{ "error": "mensagem em português" }(un mensaje en portugués) con el código HTTP correspondiente. El catálogo completo está en Errores y límites. - CORS: las rutas de datos responden a
OPTIONS(preflight) y permitenAuthorizationyContent-Type. - Encabezado de alcance: toda respuesta incluye
X-Ingestia-Access-Scope: workspace— recordatorio de que la credencial lee el workspace entero, no un usuario. - Costo transparente: cada extracción pagada devuelve
x-ingestia-cost-brlcon el valor de la llamada. El valor en BRL es una proyección, no un precio facturado garantizado hoy. - Compatibilidad N−1: los formatos versionados (widgets, filtros, tema, estado de URL, token de embed) mantienen la lectura de la versión anterior; un campo desconocido nunca se descarta en silencio.
Soporte al desarrollador#
Dudas de integración, inclusión de tu dominio en la allowlist de embed o reporte de errores: consulta el Centro de Soporte y Solución de problemas.
Próximos pasos: Autenticación → OData/Power BI.