Desenvolvedores — visão geral da API

O feed OData v4 (Power BI/Excel) e o Embed SDK estão disponíveis. A API de consulta REST (/api/v1/query, /api/v1/tables) está em acesso antecipado e ainda não está aberta para uso externo.

Esta seção documenta como integrar sistemas externos ao seu datalake do ingestia.io: autenticação por chave, os feeds de dados (OData/Power BI/Excel), o SDK de embed de painéis, o formato de erros, paginação, limites e o estado de cada superfície.

Mapa da seção#

Estados — o que cada um significa#

• Disponível — funciona, é documentado e pode ser usado em produção. Mudança de contrato é avisada com antecedência. A disponibilidade da plataforma segue o SLA de 99,5% mensal a partir do plano Growth (veja /legal/sla); acompanhe em /status.
• Acesso antecipado — a capacidade existe, mas ainda não está aberta para uso externo: o contrato pode mudar com aviso. Não construa integrações críticas sobre ela ainda. É o caso da API de consulta REST.
• Planejado — ainda não disponível (ex.: assinatura de webhooks).

Convenções gerais#

• Base: https://ingestia.io. Todas as rotas de dados ficam sob /api/v1.
• Escopo por workspace (inviolável): toda credencial é escopada ao workspace que a emitiu. A API nunca cruza datasets/buckets entre clientes e só expõe os marts publicados (*_gold e *_silver) — nunca a camada bronze.
• Somente leitura: não existe API de escrita. Toda rota é GET (ou POST apenas para enviar um SELECT). Por isso, as chamadas são idempotentes por natureza (ver Erros e limites).
• Formato de resposta: JSON (application/json; charset=utf-8); o OData responde JSON e $metadata em XML (EDMX).
• Formato de erro: sempre { "error": "mensagem em português" } com o código HTTP correspondente. O catálogo completo está em Erros e limites.
• CORS: as rotas de dados respondem a OPTIONS (pré-flight) e liberam Authorization e Content-Type.
• Cabeçalho de escopo: toda resposta traz X-Ingestia-Access-Scope: workspace — lembrete de que a credencial lê o workspace inteiro, não um usuário.
• Custo transparente: cada extração paga devolve x-ingestia-cost-brl com o valor da chamada. O valor em BRL é uma projeção, não um preço faturado garantido hoje.
• Compatibilidade N−1: formatos versionados (widgets, filtros, tema, estado de URL, token de embed) preservam a leitura da versão anterior; um campo desconhecido nunca é descartado silenciosamente.

Suporte ao desenvolvedor#

Dúvidas de integração, inclusão do domínio na allowlist de embed ou relato de erro: veja Central de Suporte e Troubleshooting.

Próximos passos: Autenticação → OData/Power BI.