# OpenAGROs — referência completa

Gerado de https://docs-v1.agrosti.com.br, do mesmo contrato que gera o site e a skill. Três
partes: como consultar e modelar, receitas de ponta a ponta, e as coleções
campo a campo.

## Como consultar e modelar

A API pública do AGROs. Somente leitura, OData v4 e REST sobre o mesmo modelo,
autenticada por token de integração.

```
Base OData  https://service.agrosti.com.br/odata/v1/
Base REST   https://service.agrosti.com.br/api/v1/
Auth        Authorization: Bearer oag_...
Docs        https://docs-v1.agrosti.com.br
```

O trabalho aqui quase nunca falha por HTTP. Falha por **modelagem**: os números
saem, parecem certos e estão dobrados. Por isso a ordem abaixo importa — entender
o grão antes de escrever a consulta economiza a retificação depois.

### Como conduzir uma tarefa

**0. Veja se a pergunta já tem receita.** `references/receitas.md` traz catorze
tarefas de ponta a ponta — produtividade, custo por talhão, abrir o custo,
colheita por unidade, produção por pessoa, estriagem, contas a pagar, carga
incremental, refresh incremental no Power BI, fechamento de safra, fluxo de
estoque, agregação no servidor, auditoria de abastecimento por tanque e saldo de
tanque de combustível —, cada uma com as consultas prontas, o relacionamento certo e a
armadilha que ela evita. Todas conferidas contra uma base real. Se a tarefa se
parece com alguma delas, comece por lá em vez de derivar do zero.

**1. Descubra o grão antes de escolher a coleção.** Pergunte-se de que é uma
linha: um apontamento? um talhão? uma pessoa? um título? A resposta decide a
coleção e evita 90% dos erros. `references/colecoes.md` lista as 60 coleções com
essa informação — leia a seção da que você vai usar, campo a campo, antes de
escrever a consulta. Chutar nome de campo é a causa mais comum de 400.

**2. Confirme contra o serviço, não contra a memória.** `/odata/v1/` devolve as
coleções que o token abre; `/odata/v1/$metadata` devolve tipos e allowlists.
Quando a referência e o `$metadata` discordarem, o `$metadata` vence — ele é o
serviço falando. Comece toda tarefa nova com uma chamada à raiz: ela valida
token, escopo e licença de uma vez.

**3. Puxe pequeno primeiro.** `$top=5` e olhe o formato antes de programar a
carga inteira. Descobrir que `date` vem nulo em metade das linhas custa uma
requisição agora e um retrabalho depois.

**4. Reduza no servidor.** `$filter` e `$select` transformam dezenas de páginas
numa; e quando a pergunta é um número agregado, `$apply` faz a soma no servidor
e devolve uma linha por grupo — veja a receita 12. O limite é por token, por
minuto (240 por padrão e como teto da superfície aberta) — quem estoura
normalmente está paginando o que poderia ter filtrado.

Nas coleções agrícolas de maior volume, siga sempre o `@odata.nextLink`: ele
usa `$skiptoken` para continuar pela última chave lida, sem o custo crescente
de páginas profundas com `$skip`. O valor é opaco; não monte nem altere à mão.

**5. Diga em voz alta como somou.** Ao entregar um número, declare de que
coleção veio a medida e por qual chave você relacionou. É assim que a pessoa
percebe uma dupla contagem antes de o número virar decisão.

### As armadilhas que dão número errado com cara de certo

Estas cinco produzem resultado plausível, não erro. Nenhuma ferramenta avisa.

**Custo mora no apontamento; produção mora no talhão.** Um apontamento tem um
custo e vários talhões. `Activities` tem o custo (uma linha por apontamento),
`ActivityAreas` tem a produção (uma linha por talhão). Junte as duas numa tabela
só e o custo se repete uma vez por talhão. Relacione por `activityId` →
`Activities.id` e some cada medida na coleção dela.

**O detalhe já está dentro do total.** `ActivityLabor`, `ActivityInputs` e
`ActivityMachines` abrem o custo por pessoa, insumo e máquina — e o `totalCost`
de cada uma já está dentro do `totalCost` de `Activities`. Servem para abrir o
custo, nunca para compô-lo.

**`Harvest` é um recorte de `ActivityAreas`, não um complemento.** Toda linha de
`Harvest` também está em `ActivityAreas`. Use uma das duas; se precisar das
duas, exclua a colheita da outra filtrando `Activities.application` diferente de
`'M'`.

**Quantidade não soma entre unidades diferentes.** O produtor conta em caixa,
saca ou tambor, e a unidade muda por fazenda e por cultura. Onde há quantidade
há uma coluna de unidade ao lado (`harvestUnit`, `unit`). Some fatiando pela
unidade; para um total que atravesse tudo, use quilos (`grossWeightKg`) ou reais
(`grossAmount`).

**Área vem da dimensão.** `Subareas.areaHa` é a área física, e só ali. Os fatos
não trazem área de propósito: um talhão aparece uma vez por operação, então
somar área pelo fato conta a mesma terra várias vezes. Produtividade é
`SUM(Harvest[grossWeightKg]) / SUM(Subareas[areaHa])`, com os filtros do
relatório valendo dos dois lados.

Duas medidas mais recentes seguem a mesma lógica invertida: em `ActivityLabor`,
`harvestValue` e `serviceValue` são remuneração por produção e ficam **fora** do
`totalCost` — são medidas próprias, não parcelas do custo.

### Escrever a consulta

```
/odata/v1/Harvest?$filter=season eq '2025' and date ge 2025-01-01&$select=id,date,farm,grossWeightKg&$orderby=date desc&$top=100&$count=true
```

O que costuma morder:

- **Data vai sem aspas** (`date ge 2025-01-01`), texto vai com aspas simples
  (`crop eq 'LARANJA'`). É a regra do OData v4 e é o que o Power BI envia.
- **Nem todo campo filtra.** Filtra-se dimensão, agrega-se medida — medidas
  ficam fora da allowlist de propósito. A referência marca campo a campo; um
  campo de fora responde 400 `FilterFieldNotAllowed`, nunca um resultado
  silenciosamente não filtrado.
- **A chave sempre volta**, mesmo fora do `$select` — sem ela o BI não relaciona.
- **`$count=true` traz o total da coleção filtrada**, não o da página: pagine com
  `$skip` até alcançá-lo.
- **`PestScoutings` e `MarketQuotes` exigem filtro** (janela de data e nome,
  respectivamente). Sem ele, 400 `FilterRequired` — e só a superfície OData
  permite declará-lo.
- **As coleções legadas** (`Employees`, `Operations`, `Animals`) não filtram nem
  ordenam: pagine e recorte do seu lado.

Para puxar dados, prefira `scripts/consultar.py` a escrever um cliente do zero —
ele já trata paginação, o 429 e o formato de erro:

```bash
python scripts/consultar.py Harvest --filter "season eq '2025'" --select id,date,farm,grossWeightKg --csv colheita.csv
```

O token sai de `OPENAGROS_TOKEN` no ambiente. Nunca escreva um token no código,
no repositório ou numa consulta salva — ele vale para a organização inteira e é
rastreado em auditoria pelo nome com que foi criado.

### Erros

O corpo é sempre `{ error, code, requestId }`. Trate pelo `code`, que é estável
dentro da v1; o texto de `error` pode ser reescrito.

| Código                        | O que fazer                                                                                              |
| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
| `Unauthorized` (401)          | Token ausente, inválido, revogado ou expirado. Confira o header; se estiver certo, o token não vale mais |
| `ScopeMissing` (403)          | O token não tem o escopo daquela coleção. Escopo não se acrescenta depois: é preciso criar outro token   |
| `OpenAGROsNotLicensed` (403)  | A organização não contratou o OpenAGROs. Nenhum token funciona até isso mudar                            |
| `RateLimited` (429)           | Espere a virada do minuto e repita. Se acontece sempre, filtre mais em vez de paginar mais               |
| `FilterRequired` (400)        | A coleção exige janela de filtro — veja a referência dela                                                |
| `FilterFieldNotAllowed` (400) | O campo existe mas não é filtrável                                                                       |
| `FilterInvalid` (400)         | Expressão OData inválida: aspas simples em texto, data sem aspas                                         |
| `ErpQueryError` (500)         | Falha na origem. A mensagem traz uma referência — repasse-a ao suporte                                   |

Ao relatar qualquer erro à pessoa, inclua o `requestId`: é por ele que o suporte
encontra a requisição.

### Power BI

O conector é **Feed OData** com o endereço `https://service.agrosti.com.br/odata/v1`
e autenticação **Básica** — usuário qualquer, o token na senha. Anônimo, Windows
e Conta organizacional falham com "não foi possível autenticar": nenhum deles
manda o token. Se uma credencial errada já foi salva, o Power BI a reusa em
silêncio; limpe em Arquivo → Opções e configurações → Configurações da fonte de
dados.

Em M, o `Implementation = "2.0"` não é opcional — sem ele o conector cai no modo
v1–v3 e recusa o serviço:

```
let
    Fonte = OData.Feed("https://service.agrosti.com.br/odata/v1", null, [Implementation = "2.0"])
in
    Fonte
```

Ao montar o modelo:

- **Comece pequeno**: um fato e as dimensões dele. Um painel de safra é
  `Harvest`, `Subareas`, `Areas`, `Farms`, `Crops`. Carregar as 60 coleções
  deixa o modelo lento sem ficar mais útil.
- **Relacione por chave de território**: todo fato traz `farmKey`, `areaKey` e
  `subareaKey`, no formato `fazenda|área|subárea`, apontando para o `id` da
  dimensão correspondente (muitos para um).
- **Use floco de neve, com caminho único**: fato → `Subareas` → `Areas` →
  `Farms`. Ligar o fato direto a `Areas` _e_ a `Subareas` cria dois caminhos até
  a mesma dimensão; o Power BI ou recusa por ambiguidade ou escolhe um e o total
  muda sem aviso.
- **Desligue a soma do que não é aditivo**: razões (`*PerHa`, fatores de
  conversão) e `areaHa` entram com "Não resumir". O padrão do Power BI é somar
  tudo que é numérico, e é daí que sai a maior parte dos números absurdos.

Existe um template pronto com esse recorte, os relacionamentos e as somas já
configuradas: `https://docs-v1.agrosti.com.br/openagros.pbit`. Ofereça-o quando
a pessoa estiver começando um modelo do zero — sai na frente de qualquer
instrução escrita.

### Referência

- `references/receitas.md` — catorze tarefas resolvidas de ponta a ponta, com a
  consulta, o relacionamento, a medida e a armadilha de cada uma. É o caminho
  mais curto para acertar de primeira.
- `references/colecoes.md` — as 60 coleções, campo a campo: tipo, se filtra, se
  ordena, o que cada campo é, e a nota de modelagem de cada uma. Gerado do
  contrato da API. Leia a seção da coleção que a tarefa usa; não tente carregar
  o arquivo inteiro na cabeça.
- `scripts/consultar.py` — cliente de linha de comando: paginação, retry no 429,
  saída em JSON ou CSV.
- `https://docs-v1.agrosti.com.br` — a documentação completa, com a referência
  navegável e os guias.
- `https://docs-v1.agrosti.com.br/llms-full.txt` — esta mesma referência,
  servida pelo site. A cópia instalada envelhece; a servida, não. Se um campo
  daqui não aparecer no `$metadata` (ou o contrário), busque esta URL — ela é
  gerada a cada publicação.

## Receitas

Perguntas que aparecem de verdade, com o caminho inteiro: de que coleção sai a
medida, por qual chave se relaciona, como se soma e o que dá errado.

Cada receita foi **conferida contra uma base de produção real**. Onde há um
número, ele é a razão medida ali (nunca o valor do cliente) — serve para você
saber o tamanho do erro que a armadilha causa, não para conferir o seu total.

A ordem é útil: a receita 1 ensina o relacionamento de que quase todas as
outras dependem.

### Índice

1. [Produtividade em kg/ha, por talhão e safra](#1-produtividade-em-kgha-por-talhão-e-safra)
2. [Custo por talhão e por hectare](#2-custo-por-talhão-e-por-hectare)
3. [Abrir o custo de uma operação em mão de obra, insumo e máquina](#3-abrir-o-custo-de-uma-operação-em-mão-de-obra-insumo-e-máquina)
4. [Colheita por fazenda, na unidade da fazenda](#4-colheita-por-fazenda-na-unidade-da-fazenda)
5. [Produção e remuneração por pessoa](#5-produção-e-remuneração-por-pessoa)
6. [Operações de estriagem (resina)](#6-operações-de-estriagem-resina)
7. [Contas a pagar em aberto](#7-contas-a-pagar-em-aberto)
8. [Carga incremental por data](#8-carga-incremental-por-data)
9. [Refresh incremental no Power BI](#9-refresh-incremental-no-power-bi)
10. [Fechar uma safra sem transformar ausência em zero](#10-fechar-uma-safra-sem-transformar-ausência-em-zero)
11. [Fluxo de estoque não é posição](#11-fluxo-de-estoque-não-é-posição)
12. [Somar no servidor com `$apply`](#12-somar-no-servidor-com-apply)
13. [Auditoria de abastecimento por tanque](#13-auditoria-de-abastecimento-por-tanque)
14. [Saldo de um tanque de combustível](#14-saldo-de-um-tanque-de-combustível)

[Medidas prontas em DAX](#medidas-prontas-em-dax)

---

### 1. Produtividade em kg/ha, por talhão e safra

**Pergunta.** "Quanto cada talhão produziu por hectare nesta safra?"

**Grão.** O numerador é uma linha por talhão colhido; o denominador é uma linha
por talhão cadastrado. São grãos diferentes, e é isso que a receita resolve.

**Coleções.** `Harvest` (produção) + `Subareas` (área).

```
/odata/v1/Harvest?$filter=season eq '2025'&$select=subareaKey,crop,season,grossWeightKg
/odata/v1/Subareas?$select=id,farm,area,subarea,areaHa
```

**Relacione** `Harvest.subareaKey` → `Subareas.id`, muitos para um. A chave é o
caminho `fazenda|área|subárea`, montado dos dois lados pela API — não tente
remontá-la você.

**Some.**

```
Produtividade = SUM(Harvest[grossWeightKg]) / SUM(Subareas[areaHa])
```

Com os filtros do relatório valendo dos dois lados; o relacionamento faz isso
sozinho.

**Armadilha.** Não tire a área do fato. Um talhão aparece uma vez por operação,
então somar área pelo fato conta a mesma terra várias vezes: na base conferida,
a área somada pelo fato ficou **32% maior** que a área real do cadastro — e
produtividade com denominador inflado sai baixa, o que parece um problema de
lavoura em vez de um problema de modelo.

**Conferido.** A chave territorial casou em **100,00%** das linhas da safra
(47.618 de 47.619), e a dimensão não tem chave repetida (347 subáreas, 347
chaves distintas) — ou seja, o relacionamento não multiplica o fato.

---

### 2. Custo por talhão e por hectare

**Pergunta.** "Quanto custou cada talhão neste ano?"

**Grão.** Aqui mora o erro mais caro da API: **o custo é do apontamento, não do
talhão**. Uma operação custa uma vez e acontece em vários talhões.

**Coleções.** `Activities` (custo) + `ActivityAreas` (talhões) + `Subareas`
(área).

```
/odata/v1/Activities?$filter=date ge 2025-01-01 and date le 2025-12-31&$select=id,date,phase,operation,application,totalCost
/odata/v1/ActivityAreas?$filter=date ge 2025-01-01 and date le 2025-12-31&$select=id,activityId,subareaKey,crop,season
```

**Relacione** `ActivityAreas.activityId` → `Activities.id` e
`ActivityAreas.subareaKey` → `Subareas.id`. Duas tabelas, dois relacionamentos —
nunca um `merge` das duas numa só.

**Some.** `SUM(Activities[totalCost])` é o custo total, e ele responde
corretamente a qualquer filtro de território, porque o filtro chega nele pelo
relacionamento.

Se você precisa do custo **atribuído** a cada talhão, há duas rotas, e as duas
são explícitas:

- `ActivityAreas.operationCost` — a parcela que o **próprio ERP** já rateou para
  aquele talhão. É o número que o sistema de origem mostra. Não o some junto com
  `Activities.totalCost`: é o mesmo dinheiro nos dois grãos.
- Ratear você mesmo por área, com `ActivityAreas.reportedAreaHa /
ActivityAreas.totalAreaHa` — a proporção da operação que coube àquele talhão.
  `totalAreaHa` é a área da operação inteira, repetida em cada linha dela: use
  como divisor, nunca como soma. E `reportedAreaHa` só presta como numerador
  desse rateio — não como "área trabalhada": ela é re-apontada a cada passada, e
  na base conferida somá-la deu 152.036 ha num talhão de 36,97 ha.

O que a API continua **não** fazendo é escolher a regra por você. Rateio por
área e rateio por igual dão números diferentes, e a escolha pertence ao
relatório.

**Armadilha.** Juntar `Activities` e `ActivityAreas` numa tabela só repete o
custo uma vez por talhão. Na base conferida, cada apontamento tem em média
**3,82 talhões** (o maior tem 143), e o custo do ano somado dessa forma ficou
**39% maior** que o real. Ele não dá erro: dá um total plausível e alto.

---

### 3. Abrir o custo de uma operação em mão de obra, insumo e máquina

**Pergunta.** "Do que é feito o custo da pulverização?"

**Grão.** Uma linha por pessoa, por insumo e por implemento do apontamento.

**Coleções.** `ActivityLabor`, `ActivityInputs`, `ActivityMachines` — três fatos
irmãos, todos ligados a `Activities` por `activityId`.

```
/odata/v1/ActivityInputs?$filter=date ge 2025-01-01&$select=activityId,input,group,quantity,totalCost
/odata/v1/ActivityLabor?$filter=date ge 2025-01-01&$select=activityId,worker,hours,totalCost
```

**Some.** Cada um no seu grão: `SUM(ActivityInputs[totalCost])` responde "quanto
de insumo", `SUM(ActivityLabor[totalCost])` responde "quanto de gente".

**Armadilha.** O `totalCost` dos três **já está dentro** do `totalCost` de
`Activities`. Eles servem para abrir o custo, nunca para compô-lo — somar pai e
filhos dobra o valor.

**Conferido.** Na base real, a mão de obra dos filhos fecha com o componente de
pessoas do pai em **99,87%**, e o insumo em **99,998%**. Ou seja: é a mesma
grandeza vista em outro grão, não uma parcela adicional.

`ActivityMachines` não tem data própria — é filho do apontamento e herda a dele.
Recorte pelo período em `Activities` e deixe o relacionamento propagar.

---

### 4. Colheita por fazenda, na unidade da fazenda

**Pergunta.** "Quantas caixas cada fazenda colheu?"

**Grão.** Uma linha por talhão colhido.

**Coleções.** `Harvest`, sozinha (ela já traz território, cultura e safra).

```
/odata/v1/Harvest?$filter=season eq '2025'&$select=farm,crop,season,quantityHarvestUnit,harvestUnit,grossWeightKg&$orderby=farm asc
```

**Some.** `SUM(Harvest[quantityHarvestUnit])` **sempre fatiado por**
`harvestUnit`. A unidade é uma coluna, não uma constante da fazenda.

**Armadilha.** Um total geral de "quantidade" mistura grandezas e não significa
nada. Na base conferida convivem seis unidades de colheita — sacola de 27,2 kg,
caixa de 22 kg, quilo, e outras — e uma delas é o próprio quilo: somar tudo junto
soma caixas com quilos. Quando você precisa de um número único que atravesse a
fazenda inteira, use `grossWeightKg` (peso) ou o valor em reais.

`harvestFactor` é a razão de conversão da unidade. Razão não soma: entre com ela
como "não resumir" no Power BI.

---

### 5. Produção e remuneração por pessoa

**Pergunta.** "Quanto cada pessoa colheu, e quanto isso rendeu a ela?"

**Grão.** Uma linha por pessoa por apontamento.

**Coleções.** `ActivityLabor`.

```
/odata/v1/ActivityLabor?$filter=date ge 2025-01-01 and date le 2025-12-31&$select=worker,team,hours,totalCost,harvestQuantity,harvestUnitPrice,harvestValue,serviceQuantity,serviceValue
```

**Some.** Três medidas **distintas**, que respondem a perguntas diferentes:

| Medida         | O que é                                               |
| -------------- | ----------------------------------------------------- |
| `totalCost`    | Hora × valor-hora. É o que compõe o custo da operação |
| `harvestValue` | Remuneração por colheita — produção, não hora         |
| `serviceValue` | Remuneração por serviço — idem                        |

**Armadilha.** `harvestValue` e `serviceValue` **não estão** dentro de
`totalCost` nem do custo do apontamento: são a remuneração por produção, medida
à parte. Somá-las ao custo duplica a mão de obra; ignorá-las subestima o que a
pessoa recebeu. Diga no relatório qual das três você está mostrando.

Para a quantidade da operação inteira, some `harvestQuantity` (ou
`serviceQuantity`) por `activityId` — é a soma das pessoas que dá o total do
apontamento. `harvestQuantityConverted` é a mesma colheita já convertida pelo
fator da unidade: use uma OU outra, nunca as duas.

---

### 6. Operações de estriagem (resina)

**Pergunta.** "Quais apontamentos são de estria?"

**Grão.** `Operations` é cadastro: uma linha por operação.

**Coleções.** `Operations` (marca de estria) + `Activities` (os apontamentos).

```
/odata/v1/Operations
```

`Operations` é uma coleção legada: **não aceita `$filter` nem `$orderby`**.
Traga-a inteira — são poucas centenas de linhas — e filtre `estrias eq true` do
seu lado.

**Relacione** pelo nome da operação: `Activities.operation` casa com
`Operations.nome`. Não há id compartilhado, porque o apontamento guarda o nome
da operação como texto.

**Some.** Filtre os apontamentos pelas operações marcadas e use
`Activities.totalCost` normalmente — as regras da receita 2 valem igual.

**Conferido.** O nome da operação casou em **100%** dos apontamentos do ano, e
`Operations.nome` não se repete no cadastro — o relacionamento por texto é
seguro aqui. Já a marca `estrias` não pôde ser medida: a base usada na
verificação é de citros e não tem operação de estria. O caminho está certo; num
cliente de resina, confira primeiro quantas operações voltam marcadas.

---

### 7. Contas a pagar em aberto

**Pergunta.** "O que vence este mês e ainda não foi pago?"

**Grão.** Uma linha por título.

**Coleções.** `Payables` (a mesma forma vale para `Receivables`).

```
/odata/v1/Payables?$filter=dueDate ge 2025-01-01 and dueDate le 2025-12-31&$select=id,dueDate,paymentDate,counterparty,group,amount,finalAmount,paid
```

**Some.** `SUM(Payables[finalAmount])` para o valor líquido (já com juros e
desconto) e `SUM(Payables[amount])` para o valor do título. São medidas
diferentes — escolha uma e diga qual.

**"Em aberto" é uma regra sua, não da API.** Não existe campo de situação de
propósito: a regra de baixa varia por operação. O que a API entrega são os
sinais como informados. Na prática, **título em aberto é aquele com
`paymentDate` vazio** — data de pagamento ausente ou sentinela chega como nulo.

**Armadilha.** `paymentDate` e `paid` **não são filtráveis** — só dimensão
filtra. Recorte no servidor pelo que dá (`dueDate`, `counterparty`, `group`,
`account`) e resolva o "em aberto" do seu lado, depois de carregar.

**Conferido.** Nos títulos de um ano inteiro da base real, `paid` e
`paymentDate` concordaram em **100%** — nenhum título pago sem data, nenhum com
data sem estar pago. Use qualquer um dos dois; o que não dá é filtrar por eles no
servidor.

---

### 8. Carga incremental por data

**Pergunta.** "Como manter uma cópia dos dados sem baixar tudo toda noite?"

**Grão.** O que muda é o dia; carregue por janela de data e não por coleção
inteira.

**Como fazer.** Guarde a maior data já carregada e peça só o que veio depois,
com uma folga para trás — apontamento é lançado com atraso, e sem a folga você
perde o que foi digitado ontem sobre anteontem:

```bash
python scripts/consultar.py Activities \
  --filter "date ge 2025-11-01 and date le 2025-11-30" \
  --csv apontamentos-2025-11.csv
```

O script já pagina até o fim e já espera a virada do minuto quando bate no
limite do token. Se você escrever o seu próprio cliente, `$count=true` traz o
total da coleção **filtrada** — pagine com `$skip` até alcançá-lo.

**Ordem de grandeza.** Na base conferida, um mês tem cerca de 2.500
apontamentos, que puxam por volta de 4.000 linhas de talhão e 5.000 de mão de
obra — pouco mais de dez páginas de 1.000. É carga de segundos por mês, contra
minutos se você baixar a coleção inteira toda vez.

**Armadilha.** Duas coleções exigem filtro e recusam a consulta sem ele:
`PestScoutings` (janela de data) e `MarketQuotes` (nome). Elas respondem 400
`FilterRequired` — não é falha de rede, é o recorte obrigatório que mantém a
consulta rápida.

Os filhos sem data própria (`ActivityMachines`, `LivestockActivityCosts`)
recortam-se pelo pai: carregue os apontamentos da janela e depois os filhos
daqueles `activityId`.

---

### 9. Refresh incremental no Power BI

**Pergunta.** "O refresh do painel demora e puxa tudo de novo toda vez. Dá para
trazer só o que mudou?"

**Grão.** O que muda é o dia. O Power BI particiona a tabela por data e só
recarrega as partições recentes.

**Serve para** qualquer coleção com `date` filtrável — `Activities`,
`ActivityAreas`, `ActivityLabor`, `ActivityInputs`, `Harvest`, `Payables`
(por `dueDate`), entre outras. **Não serve** para as que não têm data própria
(`ActivityMachines`, `LivestockActivityCosts`): elas herdam a data do pai, e o
recorte tem de ir pelo pai.

**Passo 1 — os dois parâmetros.** Em Página Inicial → Transformar dados →
Gerenciar Parâmetros, crie `RangeStart` e `RangeEnd`, tipo **Data/Hora**. Os
nomes são exigência do Power BI, não escolha nossa.

**Passo 2 — o filtro que dobra.** Na consulta da tabela:

```
let
    Fonte = OData.Feed("https://service.agrosti.com.br/odata/v1", null, [Implementation = "2.0"]),
    Tabela = Fonte{[Name = "Activities"]}[Data],
    Janela = Table.SelectRows(
        Tabela,
        each [date] >= DateTime.Date(RangeStart) and [date] < DateTime.Date(RangeEnd)
    )
in
    Janela
```

O intervalo é **semiaberto** — `>=` no início e `<` no fim. Com `<=` dos dois
lados, o último dia de uma partição também é o primeiro da seguinte e os valores
dele contam duas vezes.

**Passo 3 — a política.** Clique com o botão direito na tabela → Refresh
incremental. Arquive o que fizer sentido (três anos costuma bastar) e **atualize
os últimos 2 meses**.

**Por que 2 meses e não 1.** Apontamento é lançado com atraso: na base
conferida, o atraso médio entre o dia do trabalho e o dia do lançamento é de
**0,89 dia**, mas o máximo observado no ano foi de **75 dias**. Uma janela de um
mês perderia o que foi digitado depois da virada — e perderia em silêncio, que é
o pior tipo de perda. Dois meses cobrem 99,8% dos casos; o resto entra no refresh
completo que você fizer de tempos em tempos.

Deixe **"Detectar alterações de dados" desligado**: ele depende de uma coluna de
última modificação confiável, e a origem não tem uma.

**Armadilha.** Se o filtro não dobrar, o Power BI baixa a coleção inteira e
filtra localmente — o refresh continua correto e continua lento, sem avisar.
Confira no Editor do Power Query: clique com o botão direito no último passo e
veja se **"Exibir Consulta Nativa"** ou o indicador de folding aparece ativo. Na
dúvida, olhe o tempo: se um mês demora o mesmo que o histórico inteiro, não
dobrou.

**Conferido.** A API aceita as duas formas que o Power Query emite contra uma
coluna de data: `date ge 2025-11-01` e `date ge 2025-11-01T00:00:00Z` (com ou
sem fração de segundo, com `Z` ou com deslocamento de fuso). Quando o literal
tem hora depois da meia-noite, a comparação é ajustada para não incluir nem
excluir um dia a mais — `ge 2025-11-01T10:30` vira "depois de 2025-11-01", não
"a partir de 2025-11-01".

---

### 10. Fechar uma safra sem transformar ausência em zero

**Pergunta.** "A safra está pronta para fechar?"

**Grão.** Planejamento, execução, colheita e área são leituras diferentes. Não
há um registro único que prove que a safra inteira foi encerrada.

**Coleções.** `Harvest` (o que foi colhido) + `ActivityAreas` (apontamentos por
talhão) + `Subareas` (área física). Use `Activities` apenas para o custo do
apontamento.

```text
/odata/v1/Harvest?$filter=season eq '2025'&$select=activityId,subareaKey,crop,grossWeightKg,harvestUnit
/odata/v1/ActivityAreas?$filter=season eq '2025'&$select=activityId,subareaKey,crop,grossWeightKg
/odata/v1/Subareas?$select=id,farm,area,subarea,areaHa
```

**Faça os checks separadamente.** Conte talhões planejados em `Subareas`,
talhões com apontamento em `ActivityAreas` e talhões colhidos em `Harvest`.
Relacione cada fato à dimensão por `subareaKey` → `Subareas.id`, sem somar
`areaHa` dentro de `ActivityAreas` ou `Harvest`.

**Ausência não é zero.** Um talhão sem linha de colheita pode estar pendente,
fora do recorte, sem lançamento ou sem cobertura do ERP. Mostre a cobertura
(`colhidos / planejados`) e a lista de faltantes; só chame de zero quando uma
fonte de negócio confirmar zero.

**Armadilha.** `Harvest` é um recorte de `ActivityAreas`: juntar as duas e
somar `grossWeightKg` duplica a colheita. Escolha uma para a medida e use a
outra somente para o check de cobertura.

---

### 11. Fluxo de estoque não é posição

**Pergunta.** "Quanto entrou e saiu de estoque nesta janela?"

**Grão.** Uma linha por movimento de entrada ou saída.

**Coleção.** `InventoryMovements`.

```text
/odata/v1/InventoryMovements?$filter=date ge 2025-01-01 and date le 2025-12-31&$select=date,input,inputId,type,documentNumber,inQuantity,outQuantity,totalCost,averageCost&$orderby=date asc
```

**Some no grão certo.** `SUM(inQuantity)` e `SUM(outQuantity)` respondem ao
fluxo físico da janela. Para valor, use `SUM(totalCost)` e declare se a leitura
é entrada, saída ou ambos. Fatie por `inputId` e por unidade/insumo; não misture
produtos com grandezas diferentes.

**Não derive posição final automaticamente.** O saldo depende do estoque
inicial, ajustes, transferências e da regra de cada ERP. Movimentações são fluxo;
uma soma acumulada não é inventário certificado. Se a posição não estiver numa
fonte própria, diga "posição indisponível" e leve a pessoa ao detalhe dos
movimentos.

**Armadilha.** Somar `inQuantity - outQuantity` sem conferir `type`, documento,
cancelamentos e unidade cria um saldo plausível e não auditável. Para
reconciliação, compare uma posição de referência do ERP por produto e local com
o fluxo, sempre com a data de corte explícita.

---

### 12. Somar no servidor com `$apply`

**Pergunta.** "Quanto custou cada fase este ano?" — quando você quer o número,
não a tabela.

**Grão.** O resultado é uma linha por grupo, não por evento. Por isso a chave da
coleção não volta: grupo não é entidade.

**Coleções.** As que trazem `agrega` na referência: `Activities`,
`ActivityAreas`, `ActivityInputs` e `Harvest`.

```
/odata/v1/Activities?$filter=date ge 2025-01-01 and date le 2025-12-31&$apply=groupby((phase),aggregate(totalCost with sum as custo,$count as apontamentos))
```

Devolve uma linha por fase, com o custo somado e a contagem — em vez das dezenas
de milhares de linhas que a mesma pergunta baixa hoje. Na base conferida, custo
por fase e mês num ano sai de **26.032 linhas para 172**.

**A regra é a mesma de sempre, escrita de outro jeito:** agrupe pelo que é
dimensão (marcado `filtra`) e agregue o que é medida (marcado `agrega`). Campo
fora dessas listas responde 400 dizendo qual foi.

Métodos: `sum`, `min`, `max`, `average`, `countdistinct`, mais `$count as alias`.

```
$apply=groupby((farm,season),aggregate(grossWeightKg with sum as kg))
$apply=aggregate(totalCost with sum as custo)
$apply=groupby((crop))
```

O segundo é o total geral, sem agrupar. O terceiro lista as culturas distintas.

**Combina com `$filter`**, que vira o filtro da agregação — recorte primeiro,
agregue depois. **Não combina** com `$top`, `$skip`, `$orderby` nem `$select`:
todos respondem 501, porque paginar ou ordenar um grupo que não tem chave
devolveria resultado instável. Ordene do seu lado; a resposta é curta por
construção.

**Armadilha.** As armadilhas de dupla contagem **continuam valendo**. Agregar no
servidor não conserta grão errado: `$apply` sobre `ActivityAreas` soma o custo
uma vez por talhão do mesmo jeito que somar no Power BI somaria. O servidor faz
a conta que você pediu, mais rápido — não a conta certa.

**Teto.** A resposta traz no máximo 5.000 grupos. Se você bater nele, está
agrupando por algo de alta cardinalidade (um id, uma data por dia) — agrupe por
mês ou recorte mais no `$filter`.

---

### 13. Auditoria de abastecimento por tanque

**Pergunta.** "Todo litro que saiu da bomba foi apontado? Faltou registro ou
algum foi contado duas vezes?"

**Grão.** Aqui está a receita inteira: o grão do dado **não é** o grão da
pergunta. `ActivityInputs` é uma linha por insumo apontado, mas um único
abastecimento atende vários apontamentos — na base conferida, 64.746 linhas de
diesel correspondem a **25.762 abastecimentos**, 2,5 linhas por evento. A
auditoria acontece no grão do evento.

**Coleção.** `ActivityInputs`, filtrada pela conta de combustível.

```text
/odata/v1/ActivityInputs?$filter=subaccount eq '01. Diesel' and refuelDate ge 2025-01-01&$select=activityId,date,location,refuelDate,refuelTime,meterStart,meterEnd,meterTotal,quantity
```

**Deduplique antes de qualquer conta.** A chave do abastecimento é
`location` + `refuelDate` + `refuelTime` + `meterStart` + `meterEnd`. Agrupe por
ela; `quantity` soma dentro do grupo (é do grão da linha), `meterTotal` não —
pegue o valor, não a soma.

```text
Abastecimentos =
SUMMARIZE(
    ActivityInputs,
    ActivityInputs[location],
    ActivityInputs[refuelDate],
    ActivityInputs[refuelTime],
    ActivityInputs[meterStart],
    ActivityInputs[meterEnd],
    "Litros medidos", MAX(ActivityInputs[meterTotal]),
    "Litros apontados", SUM(ActivityInputs[quantity])
)
```

**Compare a série do totalizador, por tanque.** Ordene os eventos de um mesmo
`location` por data e hora. O `meterEnd` de um evento deve ser o `meterStart` do
seguinte:

- `meterStart` do próximo **maior** que o `meterEnd` do anterior → litros
  saíram da bomba sem registro (pulo);
- `meterStart` do próximo **menor** → o mesmo intervalo foi contado duas vezes
  (sobreposição).

Sempre dentro do mesmo tanque: bombas diferentes têm totalizadores
independentes, e misturar as séries produz pulos que não existem.

**Duas medidas, de propósito.** `meterTotal` é o litro que a bomba mediu;
`quantity` é o litro que o apontamento declarou. Elas **não** são a mesma
grandeza e a API não as reconcilia — a diferença é justamente o que o relatório
procura. Na base conferida, os dois fecham em 22.839 dos 25.762 eventos, e no
agregado saudável divergem 2,7% (1.109.655 L medidos contra 1.080.530 L
apontados).

**Armadilhas.**

- **Não some `meterTotal` cru.** Sem deduplicar por evento dá 12.806.089 L
  contra 4.249.887 L reais: **3× de inflação**. É a mesma regra do saldo de
  estoque e da chuva acumulada.
- **`refuelDate` não é `date`.** `date` é a data do cabeçalho do apontamento;
  `refuelDate`/`refuelTime` são o momento real do bombeio, capturado no campo.
  Quando o apontamento é lançado à mão os dois últimos vêm vazios — use
  `COALESCE(refuelDate, date)` e marque a linha, porque a precisão cai de hora
  para dia e a ordenação dentro do dia deixa de ser confiável.
- **Leitura 0 é dado, não ausência.** Bomba trocada ou zerada registra 0, e a
  API preserva. É uma descontinuidade legítima — trate como reset da série, não
  como pulo.
- **Frota vem do cabeçalho.** O equipamento abastecido está em
  `Activities.equipment` (com `Activities.hourMeterTotal` para o horímetro), não
  em `ActivityInputs`. Relacione `ActivityInputs.activityId` →
  `Activities.id`, muitos para um. Não confunda com `ActivityMachines`, que é
  outro grão (apontamento × implemento).
- **Pendência de apontamento** está em `Activities.status`. É texto do ERP, não
  um enum nosso: leia os valores que o seu tenant grava antes de filtrar.

---

### 14. Saldo de um tanque de combustível

**Pergunta.** "Quanto tem hoje no tanque X?"

**Grão.** Três fontes com grãos diferentes, unidas por local. Nenhuma delas é
uma posição de estoque — vale tudo que a receita 11 diz.

**Coleções.**

| Movimento               | Coleção              | Local          | Quantidade   | Sinal |
| ----------------------- | -------------------- | -------------- | ------------ | ----- |
| Compra (entrada)        | `InventoryMovements` | `location`     | `inQuantity` | +     |
| Abastecimento (saída)   | `ActivityInputs`     | `location`     | `quantity`   | −     |
| Transferência (saída)   | `InventoryTransfers` | `fromLocation` | `quantity`   | −     |
| Transferência (chegada) | `InventoryTransfers` | `toLocation`   | `quantity`   | +     |

```text
/odata/v1/InventoryMovements?$filter=location eq '02 - TANQUE BOA ESPERANÇA' and date ge 2025-01-01&$select=date,input,location,inQuantity,outQuantity,totalCost
/odata/v1/InventoryTransfers?$filter=subaccount eq '01. Diesel' and date ge 2025-01-01&$select=date,input,fromLocation,toLocation,quantity,unit,totalCost
```

**Monte a tabela de sinais** unindo os quatro blocos acima com a mesma coluna de
local, e acumule por data. A transferência entra **duas vezes** — uma negativa
na origem, uma positiva no destino — e é por isso que ela é coleção própria:
achatá-la numa linha por local obrigaria a duplicar o registro, e a quantidade
seria contada duas vezes ao agregar.

**Armadilhas.**

- **`InventoryTransfers.quantity` é a única medida somável da coleção.** O saldo
  do local antes e depois do movimento não é exposto: é acumulado e se repete.
- **`location` e `type` em `InventoryMovements` leem a mesma coluna.** Ela é o
  local de estoque; `type` é nome herdado, mantido para não quebrar relatório em
  produção. Use `location`.
- **Isto continua sendo fluxo.** Sem o estoque inicial certificado, o acumulado
  é variação, não posição. Declare a data de corte e o ponto de partida no
  relatório.

---

### Medidas prontas em DAX

As medidas das receitas acima, escritas. Copie para o Power BI e ajuste os
nomes das tabelas se você as renomeou na importação.

O ponto de todas elas é o mesmo: cada medida soma **na coleção dona da
grandeza**, e deixa o relacionamento propagar o filtro. Nenhuma soma coluna de
tabela relacionada.

```dax
Peso colhido (kg) = SUM(Harvest[grossWeightKg])

Área (ha) = SUM(Subareas[areaHa])

Produtividade (kg/ha) =
DIVIDE([Peso colhido (kg)], [Área (ha)])

Custo de produção =
SUM(Activities[totalCost])

Custo por hectare =
DIVIDE([Custo de produção], [Área (ha)])

Custo de insumo = SUM(ActivityInputs[totalCost])
Custo de mão de obra = SUM(ActivityLabor[totalCost])
Custo de máquina = SUM(ActivityMachines[totalCost])

Remuneração por colheita = SUM(ActivityLabor[harvestValue])
Remuneração por serviço = SUM(ActivityLabor[serviceValue])

A pagar em aberto =
CALCULATE(
    SUM(Payables[finalAmount]),
    ISBLANK(Payables[paymentDate])
)

A pagar vencido =
CALCULATE(
    [A pagar em aberto],
    Payables[dueDate] < TODAY()
)
```

**Quantidade colhida** não vira uma medida só, e é de propósito:

```dax
Quantidade colhida =
IF(
    HASONEVALUE(Harvest[harvestUnit]),
    SUM(Harvest[quantityHarvestUnit]),
    BLANK()
)
```

O `HASONEVALUE` faz a medida **apagar** quando o contexto mistura unidades, em
vez de devolver a soma de caixa com quilo. Um total em branco faz o analista
fatiar por `harvestUnit`; um total errado faz ele publicar o painel.

**Não crie medida de soma** para razões e fatores — `harvestFactor`,
`grossWeightPerHaKg`, `quantityPerHa`, `hourlyRate`, `harvestUnitPrice`,
`freightRate`. Some o numerador e o denominador e divida, como em
**Produtividade**. Marque essas colunas como "Não resumir" no modelo para que
ninguém as arraste para um visual por engano.

## Coleções

Gerado do contrato da API. Não edite à mão: a edição é desfeita na próxima
geração e, pior, faz esta referência prometer campo que a API não tem.

64 coleções. Consulte a que você vai usar antes de escrever a consulta:
nome de campo chutado é a causa mais comum de 400 e de coluna vazia no
relatório.

Na coluna **Consulta**: `filtra` aceita `$filter`, `ordena` aceita
`$orderby`, `agrega` aceita `$apply`. Campo marcado `—` só volta no
resultado. Medida (peso, custo,
valor) fica fora do filtro de propósito — filtra-se dimensão, agrega-se
medida.

### Índice

- **Fatos**: Activities (apontamentos), ActivityAreas (apontamentos por talhão), AgriculturalCostRows (custos agrícolas por talhão), ActivityLabor (mão de obra), ActivityInputs (insumos), ActivityMachines (máquinas e implementos), Harvest (colheita), HarvestPlantPeriods (produção e plantas por período), Sales (vendas), SalesPerformancePeriods (desempenho de vendas por período), WeighingTickets (pesagens e transporte), Payables (contas a pagar), LivestockActivities (manejos pecuários), LivestockActivityCosts (custo por animal), LedgerEntries (lançamentos), PestScoutings (monitoramento de pragas), WeatherReadings (leituras de estação), Receivables (contas a receber), Budgets (orçamentos), BudgetAreas (orçamento por talhão), PlantingCharacteristics (características de plantio), MaintenanceEntries (manutenção e oficina), LedgerDocuments (cabeçalho de lançamento), ActivityPauses (pausas), ActivityIssues (ocorrências), HarvestPoints (colheita por ponto), WorkOrders (ordens de serviço), WorkOrderHeaders (cabeçalho da ordem de serviço), WorkOrderInputs (receita da ordem de serviço), WorkOrderTargets (alvos da ordem de serviço), SprayReconciliation (conciliação da pulverização), InventoryMovements (movimentação de estoque), InventoryTransfers (transferência entre locais de estoque), Timesheets (ponto), BankEntries (movimentação bancária), CashBalancePeriods (saldos mensais por conta), CashPlanEntries (plano de caixa), MarketQuotes (cotações), WaterReadings (leituras de hidrômetro), TrapReadings (leituras de armadilha), FeedIngredients (ingredientes da ração), FeedProducts (produtos da ração), BreedingProtocols (protocolos reprodutivos), AnimalSales (histórico comercial), AnimalValuations (valores por animal), LivestockInputs (insumos do manejo), ResinRamals (ramais de resina)
- **Dimensões**: Farms (fazendas), Areas (áreas), Subareas (subáreas), AnimalRegistry (cadastro de animais), Workers (funcionários), Teams (equipes), Crops (culturas), Units (unidades), CostCenters (centros de custo), ChartAccounts (plano de contas), Assets (frota e bens), WeatherStations (estações meteorológicas), Traps (armadilhas), AnimalLineage (genealogia)
- **Legado**: Employees (funcionários (legado)), Operations (operações (legado)), Animals (animais (legado))

### Fatos

O que você soma. Cada linha é um evento — um apontamento, uma colheita, um título.

#### Activities — Apontamentos

O registro de uma operação no campo: quando foi, em que fase e quanto custou. Uma linha por apontamento.

OData: `/odata/v1/Activities` · REST: `/api/v1/openagros/activities` · chave: `id` · escopo: `agriculture.read`

Aceita `$apply`: agregue no servidor em vez de baixar a coleção para somar. Agrupe pelos campos marcados `filtra` e agregue os marcados `agrega`.

**Cuidado.** O custo pertence à operação, não ao talhão. Não junte esta coleção com ActivityAreas numa tabela só — relacione por id e deixe o BI cruzar.

ActivityLabor, ActivityInputs e ActivityMachines abrem este custo em detalhe. Somá-los ao totalCost daqui dobra o valor. equipment e hourMeterTotal são a frota e o horímetro do cabeçalho, preenchidos só no apontamento mecanizado — não confunda com ActivityMachines, que é o grão de implemento.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `phase` | texto | filtra, ordena | Fase da operação. |
| `operation` | texto | filtra, ordena | Operação executada. |
| `application` | texto | filtra, ordena | Marca de aplicação do apontamento. 'M' indica colheita. |
| `status` | texto | filtra, ordena | Situação. |
| `equipment` | texto | filtra, ordena | Equipamento apontado no cabeçalho — a frota. |
| `hourMeterTotal` | número | — | Horímetro total apontado no cabeçalho. |
| `totalCost` | número | agrega | Custo total. |

#### ActivityAreas — Apontamentos por talhão

Onde cada apontamento aconteceu e quanto produziu. Uma linha por talhão trabalhado.

OData: `/odata/v1/ActivityAreas` · REST: `/api/v1/openagros/activity-areas` · chave: `id` · escopo: `agriculture.read`

Aceita `$apply`: agregue no servidor em vez de baixar a coleção para somar. Agrupe pelos campos marcados `filtra` e agregue os marcados `agrega`.

**Cuidado.** Se você também usa Harvest, exclua a colheita daqui filtrando Activities.application diferente de 'M' — senão o peso colhido conta duas vezes.

A área em hectares não vem aqui: ela é atributo do território e vive em Subareas, onde cada talhão aparece uma vez só.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `phase` | texto | filtra, ordena | Fase da operação, no grão do talhão. |
| `operation` | texto | filtra, ordena | Operação executada, no grão do talhão. |
| `grossWeightKg` | número | agrega | Peso bruto, em quilos. |
| `quantityHarvestUnit` | número | — | Quantidade na unidade da fazenda. |
| `quantityCommercialUnit` | número | — | Produção convertida para a unidade comercial. |
| `reportedAreaHa` | número | — | Área desta subárea coberta pela operação, em hectares. Serve como numerador do rateio, dividida por totalAreaHa da mesma linha — não como área trabalhada: ela é re-apontada a cada passada e somá-la deu 152.036 ha num talhão de 36,97 ha na base conferida. |
| `totalAreaHa` | número | — | Área somada da operação inteira, em hectares, repetida em cada linha dela. Somar entre linhas conta a mesma área uma vez por talhão. |
| `operationCost` | número | — | Custo da operação já rateado para este talhão. Somar junto com o custo total do apontamento dobra o valor. |
| `budgetNumber` | número | filtra, ordena | Número do orçamento. |
| `budgetControl` | número | filtra, ordena | Revisão do orçamento. É o que desempata quando o mesmo número de orçamento aparece mais de uma vez para o mesmo talhão — relacionar sem ele multiplica as linhas. |
| `budgetName` | texto | — | Nome da ordem de produção associada. |
| `ledgerDocumentId` | número | filtra, ordena | Chave do cabeçalho de lançamento gerado pelo apontamento, quando existir. |
| `harvestUnit` | texto | — | Unidade em que a fazenda conta a colheita. |
| `harvestFactor` | número | — | Quantos quilos cabem em uma unidade da fazenda. |
| `commercialUnit` | texto | — | Unidade comercial em que a produção é negociada. |
| `commercialFactor` | número | — | Quantos quilos cabem em uma unidade comercial. |

#### AgriculturalCostRows — Custos agrícolas por talhão

Custo operacional já rateado por apontamento e talhão, com população de plantas e área física para indicadores por planta e hectare.

OData: `/odata/v1/AgriculturalCostRows` · REST: `/api/v1/openagros/agricultural-cost-rows` · chave: `id` · escopo: `agriculture.read`

**Exige filtro** em `date` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `periodStart` | data | filtra, ordena | Primeiro dia do mês do modelo agregado. Os modelos derivados exigem filtro por este campo. |
| `phase` | texto | filtra, ordena | Fase da operação. |
| `operation` | texto | filtra, ordena | Operação executada. |
| `costGroup` | texto | filtra, ordena | Grupo operacional derivado de fase e operação. Não é grupo contábil. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `budgetNumber` | número | filtra, ordena | Número do orçamento. |
| `budgetControl` | número | filtra, ordena | Revisão do orçamento. É o que desempata quando o mesmo número de orçamento aparece mais de uma vez para o mesmo talhão — relacionar sem ele multiplica as linhas. |
| `reportedAreaHa` | número | — | Área desta subárea coberta pela operação, em hectares. Serve como numerador do rateio, dividida por totalAreaHa da mesma linha — não como área trabalhada: ela é re-apontada a cada passada e somá-la deu 152.036 ha num talhão de 36,97 ha na base conferida. |
| `totalAreaHa` | número | — | Área total, em hectares. |
| `physicalAreaHa` | número | — | Área física do talhão no cadastro, em hectares. |
| `operationCost` | número | — | Custo da operação já rateado para este talhão. Somar junto com o custo total do apontamento dobra o valor. |
| `plantCount` | número | — | Total de plantas do talhão. É atributo: a mesma subárea aparece em várias ordens de produção, então somar entre elas conta a mesma planta de novo. |
| `costPerPlant` | número | — | Custo da operação dividido pela população de plantas do talhão. É razão: não some entre linhas. |
| `costPerHa` | número | — | Custo total por hectare efetivamente apontado. É razão: recalcule a partir dos componentes em vez de somar. |

#### ActivityLabor — Mão de obra

Quem trabalhou em cada apontamento, por quantas horas e a que custo.

OData: `/odata/v1/ActivityLabor` · REST: `/api/v1/openagros/activity-labor` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** O totalCost daqui já está dentro do totalCost de Activities. Serve para abrir o custo por pessoa, nunca para somar ao custo da operação.

harvestValue e serviceValue são a remuneração por produção e ficam FORA do totalCost — são medidas próprias, não parcelas do custo. As quantidades ao lado delas (harvestQuantity, serviceQuantity) são a quantidade apontada por pessoa; somadas por apontamento, dão a quantidade da operação. Para indicadores somente de trabalhadores, filtre isPointer e isLeader como false: o apontador replica a produção da turma e o líder é uma linha separada.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `worker` | texto | filtra, ordena | Pessoa que executou. |
| `team` | texto | filtra, ordena | Equipe. |
| `isPointer` | booleano | filtra, ordena | Se a linha representa o apontador da equipe. |
| `isLeader` | booleano | filtra, ordena | Se a linha representa o líder da equipe. |
| `hours` | número | — | Horas trabalhadas. |
| `hourlyRate` | número | — | Valor por hora. |
| `totalCost` | número | — | Custo total. |
| `harvestQuantity` | número | — | Quantidade colhida apontada para a pessoa, na unidade em que ela é paga. |
| `harvestQuantityConverted` | número | — | A mesma colheita convertida pelo fator da unidade — some esta ou a anterior, nunca as duas. |
| `harvestUnitPrice` | número | — | Valor pago por unidade colhida. |
| `harvestValue` | número | — | Remuneração por colheita. É medida à parte: não está dentro do custo total. |
| `serviceQuantity` | número | — | Quantidade de serviço apontada para a pessoa. |
| `serviceUnitPrice` | número | — | Valor pago por unidade de serviço. |
| `serviceValue` | número | — | Remuneração por serviço. É medida à parte: não está dentro do custo total. |

#### ActivityInputs — Insumos

O que foi aplicado em cada apontamento: produto, quantidade e valor.

OData: `/odata/v1/ActivityInputs` · REST: `/api/v1/openagros/activity-inputs` · chave: `id` · escopo: `agriculture.read`

Aceita `$apply`: agregue no servidor em vez de baixar a coleção para somar. Agrupe pelos campos marcados `filtra` e agregue os marcados `agrega`.

**Cuidado.** O totalCost daqui já está dentro do totalCost de Activities. Serve para abrir o custo por insumo, nunca para somar ao custo da operação.

Os campos de abastecimento (meterStart, meterEnd, meterTotal, refuelDate, refuelTime) descrevem o evento da bomba, e um mesmo abastecimento se repete em todas as linhas de insumo que ele atendeu. Some quantity; para os litros medidos, agrupe antes por location + refuelDate + refuelTime + meterStart + meterEnd.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `inputCode` | texto | filtra, ordena | Código do insumo. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `location` | texto | filtra, ordena | Local de estoque de onde o insumo sai — o tanque, no combustível. |
| `quantity` | número | agrega | Quantidade. |
| `quantityPerHa` | número | — | Quantidade por hectare. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | agrega | Custo total. |
| `refuelDate` | data | filtra, ordena | Data real do abastecimento, capturada no campo. Em branco quando o apontamento foi lançado à mão — aí use a data do apontamento. |
| `refuelTime` | texto | — | Hora real do abastecimento (texto HH:MM:SS). |
| `meterStart` | número | — | Leitura do totalizador da bomba no início do abastecimento. |
| `meterEnd` | número | — | Leitura do totalizador da bomba no fim do abastecimento. |
| `meterTotal` | número | — | Litros medidos pela bomba (leitura final menos inicial). NÃO some: um mesmo abastecimento se repete em todas as linhas de insumo que ele atendeu. Agrupe por local + data + hora + leituras antes de totalizar. |

#### ActivityMachines — Máquinas e implementos

Que equipamento rodou em cada apontamento, por quantas horas e com que telemetria.

OData: `/odata/v1/ActivityMachines` · REST: `/api/v1/openagros/activity-machines` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** O totalCost daqui já está dentro do totalCost de Activities. Serve para abrir o custo por implemento, nunca para somar ao custo da operação.

Sem campo de data própria: o recorte temporal vai por Activities.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `implement` | texto | filtra, ordena | Implemento utilizado. |
| `assetType` | texto | filtra, ordena | Tipo do bem. |
| `hours` | número | — | Horas trabalhadas. |
| `hourlyRate` | número | — | Valor por hora. |
| `totalCost` | número | — | Custo total. |
| `rpm` | número | — | Rotação do motor. |
| `gear` | texto | — | Marcha. |
| `distanceM` | número | — | Distância percorrida, em metros. |
| `flowRate` | número | — | Vazão. |
| `operator` | texto | filtra, ordena | Operador da máquina. |
| `operatorCost` | número | — | Custo do operador na linha da máquina. |
| `operatorHours` | número | — | Horas do operador, em decimal. |

#### Harvest — Colheita

A produção colhida por talhão, em quilos e na unidade da fazenda (caixa, saca, tambor).

OData: `/odata/v1/Harvest` · REST: `/api/v1/openagros/harvest` · chave: `id` · escopo: `agriculture.read`

Aceita `$apply`: agregue no servidor em vez de baixar a coleção para somar. Agrupe pelos campos marcados `filtra` e agregue os marcados `agrega`.

**Cuidado.** Esta coleção é um recorte de ActivityAreas — toda linha daqui também está lá. Use uma das duas, ou exclua a colheita da outra por Activities.application.

quantityHarvestUnit traz a produção já convertida para a unidade da fazenda (caixa, saca, tambor). Só some fatiando por harvestUnit; para um total geral use grossWeightKg.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | filtra, ordena | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | filtra, ordena | Chave de relacionamento com a área. |
| `subareaKey` | texto | filtra, ordena | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `variety` | texto | filtra, ordena | Variedade. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `grossWeightKg` | número | agrega | Peso bruto, em quilos. |
| `quantityHarvestUnit` | número | agrega | Quantidade na unidade da fazenda. |
| `harvestUnit` | texto | filtra, ordena | Unidade em que a fazenda conta a colheita. |
| `harvestFactor` | número | — | Quantos quilos cabem em uma unidade da fazenda. |
| `grossWeightPerHaKg` | número | — | Peso bruto por hectare. É média, não soma. |
| `cutNumber` | número | — | Número do corte. |

#### HarvestPlantPeriods — Produção e plantas por período

Peso colhido agregado por mês, território e safra, com população deduplicada para calcular kg por planta.

OData: `/odata/v1/HarvestPlantPeriods` · REST: `/api/v1/openagros/harvest-plant-periods` · chave: `id` · escopo: `agriculture.read`

**Exige filtro** em `periodStart` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | — | Identificador da linha. |
| `periodStart` | data | filtra, ordena | Primeiro dia do mês do modelo agregado. Os modelos derivados exigem filtro por este campo. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `grossWeightKg` | número | — | Peso bruto, em quilos. |
| `plantCount` | número | — | Total de plantas do talhão. É atributo: a mesma subárea aparece em várias ordens de produção, então somar entre elas conta a mesma planta de novo. |
| `kgPerPlant` | número | — | Peso colhido dividido pela população de plantas do talhão. É razão: não some entre períodos. |
| `harvestLines` | inteiro | — | Quantidade de linhas de colheita agregadas no mês. |

#### Sales — Vendas

As linhas comerciais: cliente, produto, quantidade e faturamento.

OData: `/odata/v1/Sales` · REST: `/api/v1/openagros/sales` · chave: `id` · escopo: `finance.read`

**Cuidado.** quantity só faz sentido somado dentro de uma mesma unit. Para um total que atravessa unidades, use grossAmount.

grossAmount é o faturamento; stockAmount é o valor de custo ou estoque da linha. São medidas distintas. No tenant validado, subaccount vem de Subconta; a coluna SubcontaProd citada no levantamento do PBIX não existe no schema real.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `saleNumber` | número | filtra, ordena | Número da venda. |
| `date` | data | filtra, ordena | Data do registro. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `product` | texto | filtra, ordena | Produto. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `revenueGroup` | texto | filtra, ordena | Grupo da receita (canal ou rateio). Classifica a receita contra o plano de contas financeiro, não o produto vendido. |
| `revenueAccount` | texto | filtra, ordena | Conta da receita (canal ou rateio). |
| `revenueSubaccount` | texto | filtra, ordena | Subconta da receita (canal ou rateio). |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `quantity` | número | — | Quantidade. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `grossAmount` | número | — | Faturamento bruto. |
| `stockAmount` | número | — | Valor de custo ou estoque da linha. |

#### SalesPerformancePeriods — Desempenho de vendas por período

Receita mensal por fazenda e safra, com população deduplicada e receita por planta.

OData: `/odata/v1/SalesPerformancePeriods` · REST: `/api/v1/openagros/sales-performance-periods` · chave: `id` · escopo: `finance.read`

**Exige filtro** em `periodStart` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | — | Identificador da linha. |
| `periodStart` | data | filtra, ordena | Primeiro dia do mês do modelo agregado. Os modelos derivados exigem filtro por este campo. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `grossAmount` | número | — | Faturamento bruto. |
| `stockAmount` | número | — | Valor de custo ou estoque da linha. |
| `saleLines` | inteiro | — | Quantidade de linhas comerciais agregadas no mês. |
| `plantCount` | número | — | Total de plantas do talhão. É atributo: a mesma subárea aparece em várias ordens de produção, então somar entre elas conta a mesma planta de novo. |
| `revenuePerPlant` | número | — | Receita bruta mensal dividida pela população de plantas da fazenda/safra. É razão: não some entre linhas. |

#### WeighingTickets — Pesagens e transporte

Os tickets da balança: pesos, origem, destino, transportador e frete.

OData: `/odata/v1/WeighingTickets` · REST: `/api/v1/openagros/weighing-tickets` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** commercialUnits só soma dentro de uma mesma unit. freightRate é valor unitário e freightAmount é o total do ticket — somar o unitário não significa nada.

O ticket é uma entidade própria da balança e se liga ao resto do modelo pelo território, não pelo apontamento.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `departureDate` | data | filtra, ordena | Data de saída. |
| `deliveryDate` | data | filtra, ordena | Data de entrega. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `product` | texto | filtra, ordena | Produto. |
| `productCode` | número | filtra, ordena | Código do produto. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `origin` | texto | filtra, ordena | Origem. |
| `destination` | texto | filtra, ordena | Destino. |
| `carrier` | texto | filtra, ordena | Transportadora. |
| `plate` | texto | filtra, ordena | Placa do veículo. |
| `lot` | texto | filtra, ordena | Lote. |
| `grossWeightKg` | número | — | Peso bruto, em quilos. |
| `netWeightKg` | número | — | Peso líquido, em quilos. |
| `tareWeightKg` | número | — | Peso de tara, em quilos. |
| `rejectWeightKg` | número | — | Peso de refugo, em quilos. |
| `commercialUnits` | número | — | Quantidade na unidade comercial. |
| `rejectUnits` | número | — | Refugo na unidade comercial. |
| `commercialFactor` | número | — | Quantos quilos cabem em uma unidade comercial. |
| `freightRate` | número | — | Valor unitário do frete. |
| `freightAmount` | número | — | Valor total do frete no ticket. |
| `opNumber` | número | filtra, ordena | Número da ordem de produção. |
| `opControl` | número | filtra, ordena | Controle da ordem de produção. |

#### Payables — Contas a pagar

Os títulos a pagar, com emissão, vencimento e sinais de baixa.

OData: `/odata/v1/Payables` · REST: `/api/v1/openagros/payables` · chave: `id` · escopo: `finance.read`

Sem campo de situação: os sinais de baixa (paid, paymentDate, settlementDate) vêm como informados, para você conciliar com a regra que vale na sua operação. reconciledDate é a conferência manual posterior; bankEntryId liga ao movimento bancário quando existe; cashBook indica o Livro Caixa. amount e finalAmount são medidas distintas — o final é líquido de juros e desconto.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `dueDate` | data | filtra, ordena | Data de vencimento. |
| `paymentDate` | data | — | Data de pagamento informada. |
| `settlementDate` | data | — | Data de liquidação informada. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `document` | texto | — | Documento. |
| `title` | texto | — | Título. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `reconciledDate` | data | filtra, ordena | Data de conferência manual posterior à baixa. Não é sinônimo de paid. |
| `bankEntryId` | número | filtra, ordena | Chave do lançamento bancário correspondente ao título, quando existir. |
| `cashBook` | booleano | filtra, ordena | Se o título participa do Livro Caixa. |
| `amount` | número | — | Valor do título. |
| `finalAmount` | número | — | Valor final, já com juros e desconto. |
| `interest` | número | — | Juros. |
| `discount` | número | — | Desconto. |
| `paid` | booleano | — | Sinal de baixa informado. |
| `reconciledCheckDate` | data | filtra, ordena | Segunda data de conferência do título, distinta de reconciledDate. O sistema grava as duas em campos separados e elas divergem. |
| `note` | texto | — | Observação. |

#### LivestockActivities — Manejos pecuários

O registro de um manejo do rebanho: quando, em que fase e quanto custou.

OData: `/odata/v1/LivestockActivities` · REST: `/api/v1/openagros/livestock-activities` · chave: `id` · escopo: `livestock.read`

**Cuidado.** O custo pertence ao manejo. LivestockActivityCosts abre por animal e não se soma a este total.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `phase` | texto | filtra, ordena | Fase da operação. |
| `operation` | texto | filtra, ordena | Operação executada. |
| `totalCost` | número | — | Custo total. |

#### LivestockActivityCosts — Custo por animal

O custo de cada manejo aberto por animal e por território.

OData: `/odata/v1/LivestockActivityCosts` · REST: `/api/v1/openagros/livestock-activity-costs` · chave: `id` · escopo: `livestock.read`

**Cuidado.** São muitas linhas por manejo. Agregue nesta coleção e relacione por activityId; nunca junte numa tabela só com LivestockActivities.

Sem campo de data própria: o recorte temporal vai por LivestockActivities.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `animalId` | inteiro | filtra, ordena | Aponta para o animal correspondente. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `protocolType` | texto | filtra, ordena | Tipo de protocolo. |
| `totalCost` | número | — | Custo total. |

#### LedgerEntries — Lançamentos

O espelho detalhado dos lançamentos: conta, contraparte, quantidade e valor.

OData: `/odata/v1/LedgerEntries` · REST: `/api/v1/openagros/ledger-entries` · chave: `id` · escopo: `finance.read`

É o detalhe dos lançamentos, não uma peça contábil fechada — a regra contábil varia por operação e não é aplicada aqui. titleId preserva a ligação legada com Payables ou Receivables quando o ERP a informa.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `entryDate` | data | filtra, ordena | Data de entrada. |
| `type` | texto | filtra, ordena | Tipo. |
| `entryType` | texto | filtra, ordena | Tipo de lançamento. |
| `subtype` | texto | filtra, ordena | Subtipo. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `document` | texto | — | Documento. |
| `titleId` | número | filtra, ordena | Chave do título relacionado em Payables ou Receivables, quando existir. |
| `documentId` | número | filtra, ordena | Chave do cabeçalho do lançamento em LedgerDocuments. Várias linhas de detalhe compartilham o mesmo cabeçalho. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `employeeCode` | número | filtra, ordena | Código do funcionário vinculado à linha. |
| `employee` | texto | filtra, ordena | Funcionário vinculado à linha. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `history` | texto | — | Histórico do lançamento. |
| `note` | texto | — | Observação. |
| `quantity` | número | — | Quantidade. |
| `amount` | número | — | Valor do título. |
| `unitPrice` | número | — | Preço unitário. |
| `grossInvoiceAmount` | número | — | Valor bruto da nota. Não está embutido em amount, que é o valor do lançamento. |
| `discount` | número | — | Desconto. |

#### PestScoutings — Monitoramento de pragas

As amostragens de MIP: praga encontrada, resultado e quem monitorou.

OData: `/odata/v1/PestScoutings` · REST: `/api/v1/openagros/pest-scoutings` · chave: `id` · escopo: `agriculture.read`

**Exige filtro** em `date` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

**Cuidado.** Exige janela de data no filtro. É a coleção de maior volume da API, e o recorte obrigatório mantém a consulta rápida para você e leve para a operação.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `pest` | texto | filtra, ordena | Praga monitorada. |
| `result` | texto | filtra, ordena | Resultado da amostragem. |
| `quantity` | número | — | Quantidade. |
| `worker` | texto | — | Pessoa que executou. |

#### WeatherReadings — Leituras de estação

As leituras das estações meteorológicas por fazenda.

OData: `/odata/v1/WeatherReadings` · REST: `/api/v1/openagros/weather-readings` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** rainfallReading é a leitura observada, e a grandeza muda conforme o fabricante da estação — somar leituras não tem significado físico. Para acumular chuva use rainfallDay.

Só chuva: expomos o que as estações efetivamente medem, em vez de colunas que viriam sempre vazias.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `station` | texto | filtra, ordena | Estação meteorológica. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `rainfallReading` | número | — | Leitura de chuva da estação. |
| `rainfallDay` | número | — | Chuva acumulada no dia, informada pela estação. |

#### Receivables — Contas a receber

Os títulos a receber, com emissão, vencimento e sinais de baixa.

OData: `/odata/v1/Receivables` · REST: `/api/v1/openagros/receivables` · chave: `id` · escopo: `finance.read`

Mesmas regras de Payables: sem situação derivada, e amount diferente de finalAmount. Fazenda, conferência manual, vínculo bancário e Livro Caixa vêm como sinais independentes.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `dueDate` | data | filtra, ordena | Data de vencimento. |
| `paymentDate` | data | — | Data de pagamento informada. |
| `settlementDate` | data | — | Data de liquidação informada. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `document` | texto | — | Documento. |
| `title` | texto | — | Título. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `reconciledDate` | data | filtra, ordena | Data de conferência manual posterior à baixa. Não é sinônimo de paid. |
| `bankEntryId` | número | filtra, ordena | Chave do lançamento bancário correspondente ao título, quando existir. |
| `cashBook` | booleano | filtra, ordena | Se o título participa do Livro Caixa. |
| `amount` | número | — | Valor do título. |
| `finalAmount` | número | — | Valor final, já com juros e desconto. |
| `interest` | número | — | Juros. |
| `discount` | número | — | Desconto. |
| `paid` | booleano | — | Sinal de baixa informado. |

#### Budgets — Orçamentos

O planejamento de cada ordem de produção: área, custo orçado e produtividade estimada.

OData: `/odata/v1/Budgets` · REST: `/api/v1/openagros/budgets` · chave: `id` · escopo: `agriculture.read`

Traz o planejado. Para o realizado, use os fatos de apontamento — comparar os dois é o cruzamento que fecha o ciclo da safra.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `number` | número | filtra, ordena | Número da ordem de produção. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `name` | texto | filtra, ordena | Nome da ordem de produção. |
| `crop` | texto | filtra, ordena | Cultura. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `unit` | texto | filtra, ordena | Unidade em que a produtividade foi estimada. |
| `plannedAreaHa` | número | — | Área planejada, em hectares. Não é a área física. |
| `budgetedCost` | número | — | Custo orçado. |
| `budgetedCostPerHa` | número | — | Custo orçado por hectare. |
| `estimatedYield` | número | — | Produção estimada, em quilos. É o previsto que se compara com o grossWeightKg realizado. |
| `estimatedYieldPerHa` | número | — | Produção estimada por hectare, em quilos. É razão: some estimatedYield e divida pela área, não some esta coluna entre talhões. |
| `budgetedRevenue` | número | — | Receita orçada. |

#### BudgetAreas — Orçamento por talhão

O orçamento aberto por talhão. A área aqui é a planejada — a física vive em Subareas.

OData: `/odata/v1/BudgetAreas` · REST: `/api/v1/openagros/budget-areas` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** plannedAreaHa é a área que a ordem de produção planejou para o talhão, NÃO a área física. A mesma subárea aparece em várias ordens, então somar esta coluna conta a mesma terra mais de uma vez. Para área física, use Subareas.areaHa.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `budgetNumber` | número | filtra, ordena | Número do orçamento. |
| `budgetControl` | número | filtra, ordena | Revisão do orçamento. É o que desempata quando o mesmo número de orçamento aparece mais de uma vez para o mesmo talhão — relacionar sem ele multiplica as linhas. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `crop` | texto | filtra, ordena | Cultura. |
| `variety` | texto | filtra, ordena | Variedade. |
| `rootstock` | texto | filtra, ordena | Porta-enxerto. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `plannedAreaHa` | número | — | Área planejada, em hectares. Não é a área física. |
| `budgetedCost` | número | — | Custo orçado. |
| `budgetedAdmin` | número | — | Custo administrativo orçado. |
| `budgetedTotal` | número | — | Custo total orçado. |
| `estimatedYield` | número | — | Produção estimada, em quilos. É o previsto que se compara com o grossWeightKg realizado. |
| `estimatedYieldPerHa` | número | — | Produção estimada por hectare, em quilos. É razão: some estimatedYield e divida pela área, não some esta coluna entre talhões. |
| `plantsPerArea` | número | — | Plantas cadastradas por área. |
| `plantCount` | número | — | Total de plantas do talhão. É atributo: a mesma subárea aparece em várias ordens de produção, então somar entre elas conta a mesma planta de novo. |
| `status` | texto | filtra, ordena | Situação do orçamento para o talhão. |

#### PlantingCharacteristics — Características de plantio

O cadastro agronômico do talhão dentro da ordem de produção: espaçamento, plantas e data de plantio. É a única origem de data de plantio, e é dela que sai a idade da planta.

OData: `/odata/v1/PlantingCharacteristics` · REST: `/api/v1/openagros/planting-characteristics` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `budgetNumber` | número | filtra, ordena | Número do orçamento. |
| `budgetControl` | número | filtra, ordena | Revisão do orçamento. É o que desempata quando o mesmo número de orçamento aparece mais de uma vez para o mesmo talhão — relacionar sem ele multiplica as linhas. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `cropType` | texto | filtra, ordena | Tipo de cultura (perene ou anual). |
| `variety` | texto | filtra, ordena | Variedade. |
| `rootstock` | texto | filtra, ordena | Porta-enxerto. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `unit` | texto | — | Unidade de medida. |
| `plannedAreaHa` | número | — | Área planejada, em hectares. Não é a área física. |
| `spacing` | texto | — | Espaçamento do plantio. |
| `plantsPerHa` | número | — | Plantas por hectare. |
| `totalPlants` | número | — | Total de plantas do talhão. É atributo: a mesma subárea aparece em várias ordens de produção, então somar entre elas conta a mesma planta de novo. |
| `plantingDate` | data | filtra, ordena | Data de plantio do talhão. |
| `harvestDate` | data | filtra, ordena | Data prevista de colheita. |
| `yieldPerHa` | número | — | Produção prevista por hectare, no cadastro agronômico. |
| `grossYield` | número | — | Produção bruta prevista. |
| `netYield` | número | — | Produção líquida prevista. |

#### MaintenanceEntries — Manutenção e oficina

Cada peça ou serviço de manutenção, ligado ao bem físico. É o único lugar em que a despesa de oficina aparece por máquina.

OData: `/odata/v1/MaintenanceEntries` · REST: `/api/v1/openagros/maintenance-entries` · chave: `id` · escopo: `finance.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `titleId` | número | filtra, ordena | Chave do título relacionado em Payables ou Receivables, quando existir. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `entryDate` | data | filtra, ordena | Data de entrada. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `subtype` | texto | filtra, ordena | Subtipo. |
| `item` | texto | filtra, ordena | Item. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `assetId` | número | filtra, ordena | Chave do bem em Assets, quando informada. |
| `asset` | texto | filtra, ordena | Bem, como o sistema registrou em texto. |
| `assetDescription` | texto | — | Descrição do bem. |
| `assetType` | texto | filtra, ordena | Tipo do bem. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `quantity` | número | — | Quantidade. |
| `unitPrice` | número | — | Preço unitário. |
| `discount` | número | — | Desconto. |
| `amount` | número | — | Valor do título. |
| `history` | texto | — | Histórico do lançamento. |
| `note` | texto | — | Observação. |

#### LedgerDocuments — Cabeçalho de lançamento

O documento a que as linhas de LedgerEntries pertencem. O valor daqui é o mesmo dinheiro do detalhe em outro grão: não some os dois.

OData: `/odata/v1/LedgerDocuments` · REST: `/api/v1/openagros/ledger-documents` · chave: `id` · escopo: `finance.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `entryType` | texto | filtra, ordena | Tipo de lançamento. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `entryDate` | data | filtra, ordena | Data de entrada. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `invoiceNumber` | texto | filtra, ordena | Número da nota fiscal. |
| `invoiceSeries` | texto | filtra, ordena | Série da nota fiscal. |
| `group` | texto | filtra, ordena | Grupo. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `history` | texto | — | Histórico do lançamento. |
| `amount` | número | — | Valor do título. |
| `grossExpenseAmount` | número | — | Valor bruto da despesa. |
| `discount` | número | — | Desconto. |
| `productTotal` | número | — | Valor total dos produtos da nota. |

#### ActivityPauses — Pausas

As paradas dentro de um apontamento, com motivo e duração.

OData: `/odata/v1/ActivityPauses` · REST: `/api/v1/openagros/activity-pauses` · chave: `id` · escopo: `agriculture.read`

durationMinutes é a versão numérica de duration, que vem como texto. Some a numérica; a de texto está aí para conferência.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `reason` | texto | filtra, ordena | Motivo. |
| `note` | texto | — | Observação. |
| `duration` | texto | — | Duração, como o sistema registra (texto). |
| `durationMinutes` | número | — | A mesma duração em minutos, para somar. |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | Longitude. |

#### ActivityIssues — Ocorrências

Os problemas reportados durante um apontamento, com prioridade e resolução.

OData: `/odata/v1/ActivityIssues` · REST: `/api/v1/openagros/activity-issues` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `type` | texto | filtra, ordena | Tipo da ocorrência. |
| `priority` | texto | filtra, ordena | Prioridade. |
| `description` | texto | — | Descrição. |
| `reportedBy` | texto | filtra, ordena | Quem reportou. |
| `reportedAt` | data | filtra, ordena | Quando foi reportado. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `resolved` | booleano | — | Se foi resolvida. |
| `resolvedBy` | texto | — | Quem resolveu. |
| `resolvedAt` | data | — | Quando foi resolvida. |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | Longitude. |

#### HarvestPoints — Colheita por ponto

Cada quantidade colhida por uma pessoa, com coordenada — o detalhe fino da mão de obra.

OData: `/odata/v1/HarvestPoints` · REST: `/api/v1/openagros/harvest-points` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** quantity é o colhido por pessoa e por ponto. Não some junto com o peso de Harvest — são leituras da mesma colheita em granularidades diferentes.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `laborId` | número | filtra, ordena | Aponta para a linha de mão de obra correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `worker` | texto | filtra, ordena | Pessoa que executou. |
| `quantity` | número | filtra, ordena | Quantidade. |
| `latitude` | número | filtra, ordena | Latitude. |
| `longitude` | número | filtra, ordena | Longitude. |

#### WorkOrders — Ordens de serviço

O planejamento da aplicação: alvo, calda, bico, velocidade e equipamento previstos.

OData: `/odata/v1/WorkOrders` · REST: `/api/v1/openagros/work-orders` · chave: `id` · escopo: `agriculture.read`

É o planejamento da aplicação: alvo, calda, bico, velocidade. A execução está em Activities e nos seus detalhes.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | número | filtra, ordena | Aponta para o apontamento correspondente. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `variety` | texto | filtra, ordena | Variedade. |
| `status` | texto | filtra, ordena | Situação da ordem de serviço. |
| `areaHa` | número | — | Área física, em hectares. |
| `appliedAreaHa` | número | — | Área efetivamente aplicada, em hectares. |
| `target` | texto | filtra, ordena | Alvo da aplicação. |
| `sprayVolumeLPerHa` | número | — | Volume de calda por hectare, em litros. |
| `nozzle` | texto | — | Bico utilizado. |
| `nozzlePressure` | número | — | Pressão por bico. |
| `speed` | número | — | Velocidade de deslocamento. |
| `gear` | texto | — | Marcha. |
| `rpm` | número | — | Rotação do motor. |
| `machine` | texto | filtra, ordena | Máquina. |
| `implement` | texto | filtra, ordena | Implemento utilizado. |
| `worker` | texto | filtra, ordena | Pessoa que executou. |
| `totalCost` | número | — | Custo total. |

#### WorkOrderHeaders — Cabeçalho da ordem de serviço

Uma linha por O.S., com os prazos, a situação e o alvo. É onde vivem as datas planejadas que a coleção por talhão não carrega.

OData: `/odata/v1/WorkOrderHeaders` · REST: `/api/v1/openagros/work-order-headers` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `phase` | texto | filtra, ordena | Fase da operação. |
| `operation` | texto | filtra, ordena | Operação executada. |
| `status` | texto | filtra, ordena | Situação. |
| `plannedStart` | data | filtra, ordena | Data em que a ordem de serviço deveria começar. |
| `plannedEnd` | data | filtra, ordena | Prazo final da ordem de serviço. |
| `deliveryDate` | data | — | Data de entrega. |
| `closedAt` | data | — | Data de encerramento da ordem de serviço. |
| `budgetName` | texto | filtra, ordena | Nome da ordem de produção associada. |
| `responsible` | texto | filtra, ordena | Responsável técnico pela ordem de serviço. |
| `executor` | texto | filtra, ordena | Quem executou a ordem de serviço. |
| `notes` | texto | — | Observação registrada na ordem de serviço. |
| `target` | texto | filtra, ordena | Alvo da aplicação. |
| `reentryHours` | número | — | Intervalo de reentrada na área após a aplicação, em horas. |
| `preHarvestIntervalDays` | número | — | Período de carência até a colheita, em dias. |
| `areaHa` | número | — | Área física, em hectares. |
| `sprayTotalL` | número | — | Calda total planejada, em litros. |
| `sprayTotalAppointedL` | número | — | Calda total apontada no cabeçalho, em litros. |

#### WorkOrderInputs — Receita da ordem de serviço

O insumo PLANEJADO: dose por bomba e capacidade da bomba. Não confunda com os insumos do apontamento, que são o consumo real.

OData: `/odata/v1/WorkOrderInputs` · REST: `/api/v1/openagros/work-order-inputs` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `workOrderId` | número | filtra, ordena | Aponta para a ordem de serviço correspondente. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `inputCode` | número | filtra, ordena | Código do insumo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `group` | texto | filtra, ordena | Grupo. |
| `location` | texto | filtra, ordena | Local de estoque de onde o insumo sai — o tanque, no combustível. |
| `applicationType` | texto | filtra, ordena | Forma de aplicação do insumo. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `quantity` | número | — | Quantidade. |
| `quantityPerHa` | número | — | Quantidade por hectare. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |
| `dosePerHa` | número | — | Dose planejada por hectare. |
| `quantityPerPumpL` | número | — | Quantidade de produto por bomba, conforme a receita. |
| `pumpCapacityL` | número | — | Capacidade da bomba da ordem de serviço, em litros. É atributo da O.S. repetido em cada linha: agregue com MAX, nunca com SUM. |
| `pumps` | número | — | Quantidade de bombas prevista na receita. |
| `sprayTotalL` | número | — | Calda total planejada, em litros. |
| `activeIngredient` | texto | — | Ingrediente ativo do produto. |
| `chemicalGroup` | texto | — | Grupo químico do produto. |
| `target` | texto | filtra, ordena | Alvo da aplicação. |

#### WorkOrderTargets — Alvos da ordem de serviço

Os alvos declarados na O.S., com tolerância. Coleção separada porque uma O.S. pode ter vários alvos.

OData: `/odata/v1/WorkOrderTargets` · REST: `/api/v1/openagros/work-order-targets` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `workOrderId` | número | filtra, ordena | Aponta para a ordem de serviço correspondente. |
| `target` | texto | filtra, ordena | Alvo da aplicação. |
| `pestId` | número | filtra, ordena | Aponta para a praga correspondente no cadastro. |
| `sprayCount` | número | — | Número de pulverizações previstas para o alvo. |
| `tolerance` | número | — | Nível de tolerância definido para o alvo. |

#### SprayReconciliation — Conciliação da pulverização

Planejado × aplicado por O.S. e subárea, com rateio de custo e equivalência em bombas já resolvidos. Some as colunas à vontade: só as terminadas em razão (por hectare, percentual) devem ser recalculadas.

OData: `/odata/v1/SprayReconciliation` · REST: `/api/v1/openagros/spray-reconciliation` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | — | Identificador da linha. |
| `workOrderId` | inteiro | filtra, ordena | Aponta para a ordem de serviço correspondente. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `variety` | texto | filtra, ordena | Variedade. |
| `status` | texto | filtra, ordena | Situação. |
| `phase` | texto | — | Fase da operação. |
| `operation` | texto | — | Operação executada. |
| `plannedStart` | data | — | Data em que a ordem de serviço deveria começar. |
| `plannedEnd` | data | — | Prazo final da ordem de serviço. |
| `actualStart` | data | — | Primeira data efetivamente apontada. |
| `actualEnd` | data | — | Última data efetivamente apontada. |
| `startVarianceDays` | número | — | Dias entre o início planejado e o real. Vazio quando falta um dos lados — nunca zero, que afirmaria pontualidade. |
| `endVarianceDays` | número | — | Dias entre o prazo final e o fim real. Positivo é atraso. Vazio quando falta um dos lados. |
| `plannedAreaHa` | número | — | Área planejada, em hectares. Não é a área física. |
| `appliedAreaHa` | número | — | Área efetivamente aplicada, em hectares. |
| `plannedSprayL` | número | — | Calda planejada, em litros. |
| `appliedSprayL` | número | — | Calda efetivamente aplicada, em litros. |
| `sprayVarianceL` | número | — | Calda aplicada menos a planejada, em litros. |
| `pumpCapacityL` | número | — | Capacidade da bomba da ordem de serviço, em litros. É atributo da O.S. repetido em cada linha: agregue com MAX, nunca com SUM. |
| `plannedPumps` | número | — | Calda planejada convertida em bombas. Vazio quando a capacidade da bomba é desconhecida — um padrão fixo erraria na maioria das ordens. |
| `appliedPumps` | número | — | Calda aplicada convertida em bombas. Vazio quando a capacidade da bomba é desconhecida. |
| `pumpVariance` | número | — | Bombas aplicadas menos as planejadas. |
| `plannedSprayPerHa` | número | — | Calda planejada por hectare planejado. É intensidade de aplicação: recalcule a partir dos componentes em vez de somar. |
| `appliedSprayPerHa` | número | — | Calda aplicada por hectare apontado. É intensidade de aplicação: recalcule a partir dos componentes em vez de somar. |
| `sprayVariancePercent` | número | — | Desvio da calda por hectare aplicada em relação à planejada. Acima de 5% para mais ou para menos indica desvio de aplicação, não ruído de apontamento. |
| `laborCost` | número | — | Custo de mão de obra rateado pela área apontada da subárea. |
| `machineCost` | número | — | Custo de máquinas e implementos rateado pela área apontada da subárea. |
| `inputCost` | número | — | Custo de insumos rateado pela área apontada da subárea. |
| `totalCost` | número | — | Custo total. |
| `costPerHa` | número | — | Custo total por hectare efetivamente apontado. É razão: recalcule a partir dos componentes em vez de somar. |

#### InventoryMovements — Movimentação de estoque

Entradas e saídas de insumo. É fluxo do período, não posição de estoque.

OData: `/odata/v1/InventoryMovements` · REST: `/api/v1/openagros/inventory-movements` · chave: `id` · escopo: `finance.read`

**Cuidado.** É fluxo do período, não posição de estoque. Some inQuantity e outQuantity; o saldo acumulado não é exposto porque se repete a cada movimento e somá-lo não significa nada. Para posição, agregue o fluxo até a data.

location e type entregam o mesmo dado — o local de estoque do movimento. type é o nome antigo, mantido para não quebrar relatórios já publicados; em modelo novo, use location.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `inputId` | número | filtra, ordena | Identificador do insumo. |
| `type` | texto | filtra, ordena | Local de estoque do movimento. Nome herdado: prefira `location`, que lê o mesmo dado. |
| `location` | texto | filtra, ordena | Local de estoque do movimento — o tanque, no combustível. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `supplier` | texto | filtra, ordena | Fornecedor. |
| `inQuantity` | número | — | Quantidade que entrou. |
| `outQuantity` | número | — | Quantidade que saiu. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |
| `averageCost` | número | — | Custo médio. |

#### InventoryTransfers — Transferência entre locais de estoque

A movimentação de insumo de um local para outro — de um tanque para outro, no caso do combustível. Origem e destino ficam na mesma linha, então para montar saldo por local conte a quantidade como saída na origem e entrada no destino.

OData: `/odata/v1/InventoryTransfers` · REST: `/api/v1/openagros/inventory-transfers` · chave: `id` · escopo: `finance.read`

**Cuidado.** quantity é a única medida somável. O movimento tem origem e destino na mesma linha, então para saldo por local conte-a como saída em fromLocation e entrada em toLocation — e não junte esta coleção com InventoryMovements numa tabela só, porque a transferência apareceria duas vezes.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `inputCode` | número | filtra, ordena | Código do insumo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `fromLocation` | texto | filtra, ordena | Local de estoque de origem. |
| `toLocation` | texto | filtra, ordena | Local de estoque de destino. |
| `quantity` | número | — | Quantidade transferida. É a única medida somável da coleção. |
| `unit` | texto | — | Unidade de medida. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `dispatchedBy` | texto | — | Quem liberou a transferência. |
| `transportedBy` | texto | — | Quem transportou. |
| `receivedBy` | texto | — | Quem recebeu. |

#### Timesheets — Ponto

A jornada por pessoa e dia, com horas normais e extras.

OData: `/odata/v1/Timesheets` · REST: `/api/v1/openagros/timesheets` · chave: `id` · escopo: `agriculture.read`

normalMinutes e overtimeMinutes são as versões numéricas das horas, que vêm como texto. Some as numéricas.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `worker` | texto | filtra, ordena | Pessoa que executou. |
| `role` | texto | filtra, ordena | Função. |
| `department` | texto | filtra, ordena | Departamento. |
| `team` | texto | filtra, ordena | Equipe. |
| `normalHours` | texto | — | Horas normais, como o sistema registra (texto). |
| `overtimeHours` | texto | — | Horas extras, como o sistema registra (texto). |
| `normalMinutes` | número | — | Horas normais em minutos, para somar. |
| `overtimeMinutes` | número | — | Horas extras em minutos, para somar. |
| `hourlyWage` | número | — | Salário por hora. |
| `hourlyCharges` | número | — | Encargos por hora. |
| `absent` | booleano | — | Falta abonada. |
| `vacation` | booleano | — | Em férias. |

#### BankEntries — Movimentação bancária

Os lançamentos de tesouraria: débito, crédito, conta e conciliação.

OData: `/odata/v1/BankEntries` · REST: `/api/v1/openagros/bank-entries` · chave: `id` · escopo: `finance.read`

**Cuidado.** Some debit e credit. balance e confirmedBalance são posições acumuladas para conciliação pontual; não os agregue, porque se repetem a cada movimento.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `paymentDate` | data | filtra, ordena | Data de pagamento informada. |
| `settlementDate` | data | filtra, ordena | Data de liquidação informada. |
| `reconciledDate` | data | filtra, ordena | Data de conferência manual posterior à baixa. Não é sinônimo de paid. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `history` | texto | — | Histórico do lançamento. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `group` | texto | filtra, ordena | Grupo. |
| `subgroup` | texto | filtra, ordena | Subgrupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `amount` | número | — | Valor do título. |
| `debit` | número | — | Débito. |
| `credit` | número | — | Crédito. |
| `balance` | número | — | Saldo acumulado no ERP. Não é medida agregável. |
| `confirmedBalance` | número | — | Saldo confirmado acumulado no ERP. Não é medida agregável. |

#### CashBalancePeriods — Saldos mensais por conta

Saldo de abertura, movimento e saldo final calculados por mês a partir do saldo inicial cadastrado e dos lançamentos bancários.

OData: `/odata/v1/CashBalancePeriods` · REST: `/api/v1/openagros/cash-balance-periods` · chave: `id` · escopo: `finance.read`

**Exige filtro** em `periodStart` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | — | Identificador da linha. |
| `periodStart` | data | filtra, ordena | Primeiro dia do mês do modelo agregado. Os modelos derivados exigem filtro por este campo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `openingBalance` | número | — | Saldo inicial cadastrado da conta. É o ponto de partida do saldo projetado — negativo é saldo legítimo, não erro. |
| `periodCredit` | número | — | Créditos do mês, em valor absoluto. |
| `periodDebit` | número | — | Débitos do mês, em valor absoluto. |
| `netMovement` | número | — | Créditos menos débitos do mês. |
| `closingBalance` | número | — | Saldo ao final do mês. É posição: use o último mês do recorte, não some vários meses. |
| `movementCount` | inteiro | — | Quantidade de lançamentos no mês da conta. |
| `balanceAvailable` | booleano | — | Indica se existe saldo inicial cadastrado para calcular a posição da conta. |

#### CashPlanEntries — Plano de caixa

Os lançamentos planejados, com valor previsto, pago e em aberto.

OData: `/odata/v1/CashPlanEntries` · REST: `/api/v1/openagros/cash-plan-entries` · chave: `id` · escopo: `finance.read`

Valores planejados, com pago e em aberto lado a lado. Sem volume para certificar nos ambientes que medimos — o contrato existe para quem usa o módulo.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `issueDate` | data | filtra, ordena | Data de emissão. |
| `dueDate` | data | filtra, ordena | Data de vencimento. |
| `paymentDate` | data | filtra, ordena | Data de pagamento informada. |
| `document` | texto | filtra, ordena | Documento. |
| `documentNumber` | texto | filtra, ordena | Número do documento. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `description` | texto | — | Descrição. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `type` | texto | filtra, ordena | Tipo. |
| `entryType` | texto | filtra, ordena | Tipo de lançamento. |
| `amount` | número | — | Valor do título. |
| `finalAmount` | número | — | Valor final, já com juros e desconto. |
| `paidAmount` | número | — | Valor já pago. |
| `openAmount` | número | — | Valor em aberto. |

#### MarketQuotes — Cotações

As séries de índices de mercado. Exige escolher a série no filtro.

OData: `/odata/v1/MarketQuotes` · REST: `/api/v1/openagros/market-quotes` · chave: `id` · escopo: `finance.read`

**Exige filtro** em `name` — sem ele a resposta é 400 `FilterRequired`. Só a superfície OData aceita declarar o filtro.

**Cuidado.** Exige escolher a série no filtro (name). São mais de um milhão de linhas distribuídas em poucas séries; sem o recorte, a consulta traria o histórico inteiro de todos os índices.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `name` | texto | filtra, ordena | Série do índice. É o filtro obrigatório desta coleção. |
| `type` | texto | filtra, ordena | Tipo do índice. |
| `source` | texto | filtra, ordena | Fonte da cotação. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `unitFactor` | número | — | Fator de conversão da unidade. |
| `value` | número | — | Valor da cotação. |

#### WaterReadings — Leituras de hidrômetro

O consumo de água medido por canal, em metros cúbicos.

OData: `/odata/v1/WaterReadings` · REST: `/api/v1/openagros/water-readings` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** volumeDeltaM3 é o consumo do intervalo e é o campo que soma. O contador acumulado do aparelho não é exposto — somá-lo entre leituras não tem significado físico, como a chuva.

Sem volume para certificar nos ambientes que medimos.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `date` | data | filtra, ordena | Data do registro. |
| `channelId` | número | filtra, ordena | Canal de medição. |
| `volumeDeltaM3` | número | — | Consumo do intervalo, em metros cúbicos. |
| `flowM3S` | número | — | Vazão, em metros cúbicos por segundo. |
| `durationSeconds` | número | — | Duração da medição, em segundos. |
| `batteryV` | número | — | Tensão da bateria do aparelho. |
| `signalQuality` | número | — | Qualidade do sinal. |

#### TrapReadings — Leituras de armadilha

O que foi capturado em cada armadilha, por praga e data.

OData: `/odata/v1/TrapReadings` · REST: `/api/v1/openagros/trap-readings` · chave: `id` · escopo: `agriculture.read`

Zero capturado é medição legítima, não ausência de dado — diferente de um campo vazio.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `trapId` | número | filtra, ordena | Aponta para a armadilha correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `worker` | texto | filtra, ordena | Pessoa que executou. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `crop` | texto | filtra, ordena | Cultura. |
| `pest` | texto | filtra, ordena | Praga monitorada. |
| `quantity` | número | — | Quantidade. |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | Longitude. |
| `active` | booleano | — | Se está ativa. |

#### FeedIngredients — Ingredientes da ração

O que entrou em cada batida, com quantidade planejada e efetiva — a diferença é o desvio da fórmula.

OData: `/odata/v1/FeedIngredients` · REST: `/api/v1/openagros/feed-ingredients` · chave: `id` · escopo: `livestock.read`

plannedQuantity e actualQuantity vêm em par de propósito: a diferença entre os dois é o desvio da fórmula, que é o número que interessa em nutrição.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `batchId` | número | filtra, ordena | Identificador da batida. |
| `plantId` | número | filtra, ordena | Identificador da fábrica. |
| `date` | data | filtra, ordena | Data do registro. |
| `batchDate` | data | filtra, ordena | Data da batida. |
| `ingredient` | texto | filtra, ordena | Ingrediente. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `plannedQuantity` | número | — | Quantidade planejada pela fórmula. |
| `actualQuantity` | número | — | Quantidade efetivamente batida. |
| `plannedShare` | número | — | Participação planejada, em porcentagem. |
| `actualShare` | número | — | Participação efetiva, em porcentagem. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |

#### FeedProducts — Produtos da ração

O que saiu de cada batida, com quantidade e custo.

OData: `/odata/v1/FeedProducts` · REST: `/api/v1/openagros/feed-products` · chave: `id` · escopo: `livestock.read`

**Cuidado.** O custo do produto e a soma dos ingredientes da mesma batida são leituras diferentes do mesmo processo. Não os some — compare-os.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `batchId` | número | filtra, ordena | Identificador da batida. |
| `plantId` | número | filtra, ordena | Identificador da fábrica. |
| `batchDate` | data | filtra, ordena | Data da batida. |
| `product` | texto | filtra, ordena | Produto. |
| `plant` | texto | filtra, ordena | Nome da fábrica de ração. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `plannedQuantity` | número | — | Quantidade planejada pela fórmula. |
| `actualQuantity` | número | — | Quantidade efetivamente batida. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |

#### BreedingProtocols — Protocolos reprodutivos

Os protocolos por animal: inseminação, prenhez, nascimento e custo.

OData: `/odata/v1/BreedingProtocols` · REST: `/api/v1/openagros/breeding-protocols` · chave: `id` · escopo: `livestock.read`

Uma linha por animal e protocolo. cost e revenue são do protocolo, não do animal inteiro.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `animalId` | número | filtra, ordena | Aponta para o animal correspondente. |
| `protocolId` | número | filtra, ordena | Identificador do protocolo. |
| `protocol` | texto | filtra, ordena | Nome do protocolo. |
| `type` | texto | filtra, ordena | Tipo do protocolo. |
| `animal` | texto | filtra, ordena | Nome do animal. |
| `handlingCode` | texto | filtra, ordena | Código de manejo. |
| `aptitude` | texto | filtra, ordena | Aptidão. |
| `sex` | texto | filtra, ordena | Sexo. |
| `entryDate` | data | filtra, ordena | Data de entrada. |
| `exitDate` | data | filtra, ordena | Data de saída. |
| `bull` | texto | filtra, ordena | Touro. |
| `donor` | texto | — | Doadora. |
| `receiver` | texto | — | Receptora. |
| `semen` | texto | — | Partida de sêmen. |
| `embryo` | texto | — | Embrião. |
| `pregnant` | texto | — | Sinal de prenhez informado. |
| `born` | booleano | — | Houve nascimento. |
| `stillborn` | booleano | — | Natimorto. |
| `abortion` | booleano | — | Houve aborto. |
| `bornCount` | número | — | Quantidade nascida. |
| `cost` | número | — | Custo. |
| `revenue` | número | — | Receita. |

#### AnimalSales — Histórico comercial

Compras e vendas do rebanho, com valores e proprietários.

OData: `/odata/v1/AnimalSales` · REST: `/api/v1/openagros/animal-sales` · chave: `id` · escopo: `livestock.read`

**Cuidado.** saleAmount e purchaseAmount são eventos opostos. Somar os dois numa medida só mistura entrada com saída.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `animalId` | número | filtra, ordena | Aponta para o animal correspondente. |
| `saleId` | número | filtra, ordena | Identificador da venda. |
| `type` | texto | filtra, ordena | Tipo. |
| `entryDate` | data | filtra, ordena | Data de entrada. |
| `exitDate` | data | filtra, ordena | Data de saída. |
| `previousOwner` | texto | filtra, ordena | Proprietário anterior. |
| `newOwner` | texto | filtra, ordena | Novo proprietário. |
| `saleAmount` | número | — | Valor de venda. |
| `purchaseAmount` | número | — | Valor de compra. |
| `costAmount` | número | — | Valor de custo. |
| `initialAmount` | número | — | Valor no início do período. |

#### AnimalValuations — Valores por animal

A posição de valor de cada animal. Inicial e final descrevem o mesmo animal em momentos diferentes.

OData: `/odata/v1/AnimalValuations` · REST: `/api/v1/openagros/animal-valuations` · chave: `id` · escopo: `livestock.read`

**Cuidado.** São POSIÇÕES, não fluxo. initialAmount e finalAmount descrevem o mesmo animal em momentos diferentes — some cada um isoladamente, ou compare-os. Somar os dois não significa nada.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `animalId` | número | filtra, ordena | Aponta para o animal correspondente. |
| `status` | texto | filtra, ordena | Situação do animal no período. |
| `valuationDate` | data | filtra, ordena | Data da apuração. |
| `initialAmount` | número | — | Valor no início do período. |
| `finalAmount` | número | — | Valor final, já com juros e desconto. |
| `purchaseAmount` | número | — | Valor de compra. |
| `birthAmount` | número | — | Valor atribuído a nascimentos. |
| `saleAmount` | número | — | Valor de venda. |
| `deathAmount` | número | — | Valor atribuído a mortes. |
| `costAmount` | número | — | Valor de custo. |
| `laborAmount` | número | — | Parcela de mão de obra. |
| `inputAmount` | número | — | Parcela de insumos. |
| `machineAmount` | número | — | Parcela de máquinas. |
| `initialCount` | número | — | Quantidade no início do período. |
| `finalCount` | número | — | Quantidade no fim do período. |
| `bornCount` | número | — | Quantidade nascida. |
| `soldCount` | número | — | Quantidade vendida. |
| `weightKg` | número | — | Peso, em quilos. |
| `weightArroba` | número | — | Peso, em arrobas. |
| `yieldPercent` | número | — | Rendimento, em porcentagem. |

#### LivestockInputs — Insumos do manejo

O que foi aplicado em cada manejo pecuário.

OData: `/odata/v1/LivestockInputs` · REST: `/api/v1/openagros/livestock-inputs` · chave: `id` · escopo: `livestock.read`

**Cuidado.** O totalCost daqui já está dentro do totalCost de LivestockActivities. Serve para abrir o custo por insumo, nunca para somar ao custo do manejo.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `activityId` | inteiro | filtra, ordena | Aponta para o apontamento correspondente. |
| `date` | data | filtra, ordena | Data do registro. |
| `input` | texto | filtra, ordena | Insumo aplicado. |
| `group` | texto | filtra, ordena | Grupo. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `quantity` | número | — | Quantidade. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |
| `semen` | texto | — | Partida de sêmen. |
| `embryo` | texto | — | Embrião. |
| `batch` | texto | — | Partida ou lote. |

#### ResinRamals — Ramais de resina

Os ramais planejados. As faces são posição, não quantidade — só o total soma.

OData: `/odata/v1/ResinRamals` · REST: `/api/v1/openagros/resin-ramals` · chave: `id` · escopo: `agriculture.read`

**Cuidado.** As faces do ramal são posição, não quantidade — por isso só facesTotal é exposto como medida.

Sem volume para certificar nos ambientes que medimos.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `budgetNumber` | número | filtra, ordena | Número do orçamento. |
| `activityId` | número | filtra, ordena | Aponta para o apontamento correspondente. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `ramalNumber` | número | filtra, ordena | Número do ramal. |
| `variety` | texto | filtra, ordena | Variedade. |
| `facesTotal` | número | — | Total de faces do ramal. |

### Dimensões

Por onde você fatia. Cada linha é uma entidade do cadastro, uma vez só — por isso área em hectares se soma aqui, nunca no fato.

#### Farms — Fazendas

O primeiro nível do território.

OData: `/odata/v1/Farms` · REST: `/api/v1/openagros/farms` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | filtra, ordena | Nome da fazenda, que é também a chave. |
| `name` | texto | filtra, ordena | Nome da fazenda. |
| `city` | texto | filtra, ordena | Município. |
| `state` | texto | filtra, ordena | Unidade federativa. |

#### Areas — Áreas

O nível intermediário: cada fazenda tem várias áreas.

OData: `/odata/v1/Areas` · REST: `/api/v1/openagros/areas` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | — | Caminho fazenda\|área, que é também a chave. |
| `name` | texto | filtra, ordena | Nome da área. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `areaHa` | número | — | Área física, em hectares. |

#### Subareas — Subáreas

O talhão, nível mais fino do território — e onde vive a área física em hectares.

OData: `/odata/v1/Subareas` · REST: `/api/v1/openagros/subareas` · chave: `id` · escopo: `agriculture.read`

É daqui que sai a área para produtividade: SUM(peso) ÷ SUM(areaHa). A área vive na dimensão porque lá cada talhão aparece uma vez só.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | filtra, ordena | Caminho fazenda\|área\|subárea, que é também a chave. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `areaKey` | texto | — | Chave de relacionamento com a área. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `areaHa` | número | — | Área física, em hectares. |

#### AnimalRegistry — Cadastro de animais

Os animais do rebanho, com identificação, aptidão e datas.

OData: `/odata/v1/AnimalRegistry` · REST: `/api/v1/openagros/animal-registry` · chave: `id` · escopo: `livestock.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `handlingCode` | texto | filtra, ordena | Código de manejo. |
| `number` | número | — | Número do animal. |
| `name` | texto | filtra, ordena | Nome. |
| `sisbov` | texto | filtra, ordena | Identificação Sisbov. |
| `aptitude` | texto | filtra, ordena | Aptidão. |
| `sex` | texto | filtra, ordena | Sexo. |
| `birthDate` | data | filtra, ordena | Data de nascimento. |
| `entryDate` | data | — | Data de entrada. |

#### Workers — Funcionários

As pessoas que aparecem nos apontamentos de mão de obra.

OData: `/odata/v1/Workers` · REST: `/api/v1/openagros/workers` · chave: `id` · escopo: `agriculture.read`

Agrupada por nome, que é a granularidade que os apontamentos expressam. Homônimos aparecem como uma linha só. contractor identifica o empreiteiro associado à pessoa para o BI calcular a comissão.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | filtra, ordena | Nome da pessoa, que é também a chave. |
| `name` | texto | filtra, ordena | Nome da pessoa. |
| `role` | texto | filtra, ordena | Função. |
| `contractor` | texto | filtra, ordena | Empreiteiro associado à pessoa. |
| `department` | texto | filtra, ordena | Departamento. |
| `sector` | texto | filtra, ordena | Setor. |
| `section` | texto | filtra, ordena | Seção. |
| `team` | texto | filtra, ordena | Equipe. |
| `costCenter` | texto | filtra, ordena | Centro de custo. |
| `subCostCenter` | texto | filtra, ordena | Subcentro de custo. |
| `company` | texto | filtra, ordena | Empresa. |

#### Teams — Equipes

As equipes cadastradas.

OData: `/odata/v1/Teams` · REST: `/api/v1/openagros/teams` · chave: `id` · escopo: `agriculture.read`

Cadastro de equipes. Não confunda com execução: quem trabalhou está em ActivityLabor.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | filtra, ordena | Nome da equipe, que é também a chave. |
| `name` | texto | filtra, ordena | Nome da equipe. |

#### Crops — Culturas

As culturas que aparecem nos apontamentos.

OData: `/odata/v1/Crops` · REST: `/api/v1/openagros/crops` · chave: `id` · escopo: `agriculture.read`

Vem dos apontamentos, e não de um cadastro à parte — então lista exatamente as culturas que aparecem na sua operação.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | texto | filtra, ordena | Nome da cultura, que é também a chave. |
| `name` | texto | filtra, ordena | Nome da cultura. |

#### Units — Unidades

As unidades de medida cadastradas, com fator de conversão.

OData: `/odata/v1/Units` · REST: `/api/v1/openagros/units` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `name` | texto | filtra, ordena | Nome da unidade de medida. |
| `base` | texto | filtra, ordena | Unidade base. |
| `multiplier` | número | — | Multiplicador de conversão. |
| `abbreviation` | texto | filtra, ordena | Abreviatura. |

#### CostCenters — Centros de custo

Os centros de custo, com as áreas própria e arrendada.

OData: `/odata/v1/CostCenters` · REST: `/api/v1/openagros/cost-centers` · chave: `id` · escopo: `finance.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `item` | texto | filtra, ordena | Item. |
| `type` | texto | filtra, ordena | Tipo. |
| `subtype` | texto | filtra, ordena | Subtipo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `ownAreaHa` | número | — | Área própria, em hectares. |
| `leasedAreaHa` | número | — | Área arrendada, em hectares. |
| `totalAreaHa` | número | — | Área total, em hectares. |

#### ChartAccounts — Plano de contas

O cadastro de contas administrativas e bancárias. Os fatos já trazem grupo, conta e subconta em texto — o que só existe aqui é o saldo inicial da conta, ponto de partida do fluxo de caixa projetado.

OData: `/odata/v1/ChartAccounts` · REST: `/api/v1/openagros/chart-accounts` · chave: `id` · escopo: `finance.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `company` | texto | filtra, ordena | Empresa. |
| `type` | texto | filtra, ordena | Tipo. |
| `subtype` | texto | filtra, ordena | Subtipo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `item` | texto | filtra, ordena | Item. |
| `accountNumber` | texto | filtra, ordena | Número da conta bancária, quando a linha é conta de banco. |
| `accountType` | texto | filtra, ordena | Tipo da conta. |
| `unit` | texto | filtra, ordena | Unidade de medida. |
| `openingBalance` | número | — | Saldo inicial cadastrado da conta. É o ponto de partida do saldo projetado — negativo é saldo legítimo, não erro. |
| `currentBalance` | número | — | Saldo atual da conta no sistema, na data de balanceDate. É posição, não medida do período que você filtrou. |
| `balanceDate` | data | filtra, ordena | Data a que o saldo atual se refere. |
| `status` | texto | filtra, ordena | Situação. |

#### Assets — Frota e bens

O cadastro de máquinas, implementos e veículos. Os valores aqui são cadastrais; o realizado da máquina está em ActivityMachines e em MaintenanceEntries.

OData: `/odata/v1/Assets` · REST: `/api/v1/openagros/assets` · chave: `id` · escopo: `agriculture.read`

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `code` | número | filtra, ordena | Código de identificação. |
| `name` | texto | filtra, ordena | Nome. |
| `assetType` | texto | filtra, ordena | Tipo do bem. |
| `assetSubtype` | texto | filtra, ordena | Subtipo do bem. |
| `manufacturer` | texto | filtra, ordena | Fabricante. |
| `model` | texto | filtra, ordena | Modelo. |
| `plate` | texto | filtra, ordena | Placa do bem, quando é veículo. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | filtra, ordena | Chave de relacionamento com a fazenda. |
| `sector` | texto | filtra, ordena | Setor. |
| `subsector` | texto | filtra, ordena | Subsetor. |
| `acquisitionDate` | data | filtra, ordena | Data de entrada do bem. |
| `acquisitionValue` | número | — | Valor de aquisição. |
| `currentValue` | número | — | Valor atual do bem. |
| `hourlyCost` | número | — | Custo-hora cadastrado do bem. É orçado, não realizado. |
| `usefulLifeYears` | número | — | Vida útil, em anos. |
| `usefulLifeHours` | número | — | Vida útil, em horas. |
| `meterHours` | número | — | Leitura do horímetro. |

#### WeatherStations — Estações meteorológicas

O cadastro das estações. As leituras estão em WeatherReadings.

OData: `/odata/v1/WeatherStations` · REST: `/api/v1/openagros/weather-stations` · chave: `id` · escopo: `agriculture.read`

Cadastro. As leituras estão em WeatherReadings; relacione por farmKey ou pelo nome da estação.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `name` | texto | filtra, ordena | Nome da estação. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | Longitude. |
| `active` | booleano | — | Se está ativa. |

#### Traps — Armadilhas

O cadastro das armadilhas instaladas, com posição e quadrante.

OData: `/odata/v1/Traps` · REST: `/api/v1/openagros/traps` · chave: `id` · escopo: `agriculture.read`

Cadastro. As capturas estão em TrapReadings.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha. |
| `code` | número | filtra, ordena | Código da armadilha no monitoramento. |
| `name` | texto | filtra, ordena | Nome da armadilha. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `area` | texto | filtra, ordena | Nome da área. |
| `subarea` | texto | filtra, ordena | Nome da subárea (talhão). |
| `subareaKey` | texto | — | Chave de relacionamento com a subárea. |
| `quadrant` | texto | filtra, ordena | Quadrante. |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | Longitude. |
| `active` | booleano | — | Se está ativa. |

#### AnimalLineage — Genealogia

Pai e mãe de cada animal. Para subir gerações, relacione de volta ao próprio identificador.

OData: `/odata/v1/AnimalLineage` · REST: `/api/v1/openagros/animal-lineage` · chave: `id` · escopo: `livestock.read`

Genealogia achatada em um nível. Para subir gerações, relacione sireId e damId de volta a animalId quantas vezes precisar.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `id` | inteiro | filtra, ordena | Identificador da linha de genealogia. |
| `animalId` | número | filtra, ordena | Aponta para o animal correspondente. |
| `name` | texto | filtra, ordena | Nome do animal. |
| `handlingCode` | texto | filtra, ordena | Código de manejo. |
| `sex` | texto | filtra, ordena | Sexo. |
| `breed` | texto | filtra, ordena | Raça. |
| `species` | texto | filtra, ordena | Espécie. |
| `aptitude` | texto | filtra, ordena | Aptidão. |
| `birthDate` | data | — | Data de nascimento. |
| `sireId` | número | filtra, ordena | Aponta para o pai. |
| `sire` | texto | filtra, ordena | Nome do pai. |
| `damId` | número | filtra, ordena | Aponta para a mãe. |
| `dam` | texto | filtra, ordena | Nome da mãe. |
| `receiver` | texto | — | Receptora. |

### Legado

Anteriores ao modelo em estrela, com campos em português porque os apps de campo compartilham o mesmo schema. Não filtram nem ordenam.

#### Employees — Funcionários (legado)

Cadastro compartilhado com os aplicativos de campo. Campos em português.

OData: `/odata/v1/Employees` · REST: `/api/v1/agriculture/employees` · chave: `codigo` · escopo: `agriculture.read`

Não aceita `$filter` nem `$orderby`: só paginação. Traga a coleção inteira e recorte do seu lado.

Recurso anterior ao modelo em estrela. Campos em português porque o schema é compartilhado com os aplicativos de campo.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `codigo` | inteiro | — | Identificador da linha. |
| `user` | inteiro | — | Usuário de acesso do aplicativo de campo. |
| `senha` | inteiro | — | Senha numérica do aplicativo de campo. |
| `nomefantasia` | texto | — | Nome usado no dia a dia. |
| `funcao` | texto | — | Função exercida. |

#### Operations — Operações (legado)

Cadastro compartilhado com os aplicativos de campo. Campos em português.

OData: `/odata/v1/Operations` · REST: `/api/v1/agriculture/operations` · chave: `codigo` · escopo: `agriculture.read`

Não aceita `$filter` nem `$orderby`: só paginação. Traga a coleção inteira e recorte do seu lado.

Recurso anterior ao modelo em estrela. Campos em português porque o schema é compartilhado com os aplicativos de campo.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `codigo` | inteiro | — | Identificador da linha. |
| `nome` | texto | — | Nome. |
| `fase` | texto | — | Fase da operação. |
| `estrias` | booleano | — | Marca se a operação é de estriagem (resina). |

#### Animals — Animais (legado)

Cadastro compartilhado com os aplicativos de campo. Para o modelo em estrela, use AnimalRegistry.

OData: `/odata/v1/Animals` · REST: `/api/v1/livestock/animals` · chave: `codigo` · escopo: `livestock.read`

Não aceita `$filter` nem `$orderby`: só paginação. Traga a coleção inteira e recorte do seu lado.

Recurso anterior ao modelo em estrela. Para o cadastro no modelo novo, use AnimalRegistry.

| Campo | Tipo | Consulta | O que é |
| --- | --- | --- | --- |
| `codigo` | inteiro | — | Identificador da linha. |
| `numero` | número | — | Número do animal. |
| `sigla` | texto | — | Sigla da operação. |
| `nome` | texto | — | Nome. |
| `sisbov` | texto | — | Identificação Sisbov. |
| `manejo` | texto | — | Código de manejo. |
| `raca` | texto | — | Raça. |
| `sexo` | texto | — | Sexo. |
| `categoria` | texto | — | Categoria do animal. |
| `lote` | texto | — | Lote. |
| `area` | texto | — | Nome da área. |
| `subarea` | texto | — | Nome da subárea (talhão). |
| `regimeAl` | texto | — | Regime alimentar. |
| `idEletr2` | texto | — | Identificação eletrônica. |
| `peso` | número | — | Peso de entrada, em quilos. |
| `pesoatual` | número | — | Peso atual, em quilos. |
| `situacaoanimal` | texto | — | Situação do animal. |
| `nascimento` | texto | — | Data de nascimento. |