API aberta

OpenAGROs

Os dados da sua operação em OData e REST, no grão certo para somar.

O OpenAGROs entrega os dados do AGROs em OData v4 e REST, prontos para o Power BI, o Excel ou qualquer ferramenta de BI.

São 50 coleções modeladas em estrela — poucas tabelas de medida ligadas a várias de cadastro: 35 de fatos (o que você mede) e 12 de dimensões (por onde você fatia). Cada uma já vem na granularidade certa, com as regras de negócio da agricultura aplicadas, para que a soma feche sem você precisar corrigir.

Para começar, crie um token em Configurações → Integrações, no AGROs. O acesso é self-service: quem administra a organização cria, revoga e audita os tokens sem depender da gente. Como criar o token.

O modelo em um desenho

Dimensões

Farms Fazendas

Areas Áreas por fazenda

Subareas Talhões área em hectares

Crops Culturas

Fatos

Activities Apontamentos custo

Harvest Colheita peso e quantidade

Payables Contas a pagar valor

…e mais 12 fatos

Fato é o que você soma. Dimensão é por onde você fatia. Cada fato traz as chaves das dimensões, e o Power BI monta os relacionamentos sozinho.

É só isso: você escolhe um fato, liga às dimensões que interessam e o BI faz o resto.

Custo e produção vivem em coleções diferentes

Uma operação de campo acontece uma vez, mas cobre vários talhões. O custo é da operação; a produção é de cada talhão. Como as duas medidas têm granularidades diferentes, elas moram em coleções diferentes:

Activities Apontamentos custo total

1 linha por operação

talhão A peso colhido

talhão B peso colhido

talhão C peso colhido

ActivityAreas — 1 linha por talhão

O custo pertence à operação; a produção pertence ao talhão. Some cada um na sua própria coleção e relacione por activityId — assim o total sai certo dos dois lados.

É por isso que Activities e ActivityAreas são separados — e o mesmo vale para mão de obra, insumos e máquinas, que abrem o custo da operação em mais detalhe.

Território

Quase todo relatório fatia por fazenda, área ou talhão. A hierarquia é a mesma do AGROs:

Farms fazenda Areas área Subareas subárea, ou talhão

O relacionamento usa o caminho completo como chave. Nos fatos ele vem pronto em subareaKey, e na dimensão em id:

Fazenda|Área|Talhão

Nomes de área e de talhão se repetem entre fazendas, então o caminho inteiro é o que identifica sem ambiguidade.

Escolher a superfície

Os mesmos dados, duas portas. A escolha é sobre quem consome:

	OData	REST
Para quem	Power BI, Excel, ferramentas de BI	Scripts e integrações
Filtra no servidor	Sim	Não — só paginação
Descoberta automática	Sim (`$metadata`)	Não

Na dúvida, OData: ele aplica o filtro no servidor, e num volume grande isso é a diferença entre transferir uma safra e transferir o histórico inteiro.

Leia antes de montar o primeiro relatório

O modelo resolve quase tudo, mas quatro decisões continuam sendo suas — e são as que mais causam número inesperado. Como modelar sem errar tem as quatro, em uma página curta.

Começar

Autenticação Criar o token e fazer a primeira consulta. Conectar o Power BI Do endereço OData ao modelo pronto. Como modelar sem errar As quatro decisões que continuam sendo suas. Referência OData As 50 coleções, campo a campo. Erros O formato do erro e o que fazer com cada código. Versionamento O que a v1 garante e o que pode mudar.

O que a API não faz

Não escreve. As duas superfícies são somente leitura, e o $metadata declara isso.
Não agrega por você. As coleções são planas e já na granularidade certa; quem soma e cruza é o seu BI.
Não deriva o que depende da sua regra. Conciliação financeira, por exemplo, varia de operação para operação — expomos os sinais e você aplica a sua regra.