# OpenAGROs — referência completa

Gerado de https://docs.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.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 oito
tarefas de ponta a ponta — produtividade, custo por talhão, abrir o custo,
colheita por unidade, produção por pessoa, estriagem, contas a pagar e carga
incremental —, 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 54 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. O limite é por token, por minuto (até 240; 60 é o padrão da superfície
aberta) — quem estoura normalmente está paginando o que poderia ter filtrado.

**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 54 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.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` — oito 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 54 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.agrosti.com.br` — a documentação completa, com a referência
  navegável e os guias.
- `https://docs.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)

---

### 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, o rateio é uma decisão sua
(por área? por igual?) e deve ser explícito no relatório. A API não rateia de
propósito: a regra varia por operação, e um número rateado em silêncio tem cara
de autoridade que ele não tem.

**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`.

## 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.

54 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`. 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), ActivityLabor (mão de obra), ActivityInputs (insumos), ActivityMachines (máquinas e implementos), Harvest (colheita), Sales (vendas), 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), 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), Timesheets (ponto), BankEntries (movimentação bancária), 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), 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`

**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.

| 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. |
| `totalCost` | número | — | 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`

**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. |
| `grossWeightKg` | número | — | Peso bruto, em quilos. |
| `harvestUnit` | texto | — | Unidade em que a fazenda conta a colheita. |
| `harvestFactor` | número | — | Quantos quilos cabem em uma unidade da fazenda. |

#### 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.

| 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. |
| `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`

**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.

| 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. |
| `quantity` | número | — | Quantidade. |
| `quantityPerHa` | número | — | Quantidade por hectare. |
| `unitPrice` | número | — | Preço unitário. |
| `totalCost` | número | — | Custo total. |

#### 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. |

#### 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`

**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 | — | 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. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `grossWeightKg` | número | — | Peso bruto, em quilos. |
| `quantityHarvestUnit` | número | — | 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. |

#### 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.

| 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. |
| `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. |

#### 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. 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). |
| `document` | texto | — | Documento. |
| `title` | texto | — | Título. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `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. |

#### 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.

| 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. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `counterparty` | texto | filtra, ordena | Contraparte (cliente ou fornecedor). |
| `document` | texto | — | Documento. |
| `farm` | texto | filtra, ordena | Nome da fazenda. |
| `farmKey` | texto | — | Chave de relacionamento com a fazenda. |
| `quantity` | número | — | Quantidade. |
| `amount` | número | — | Valor do título. |
| `unitPrice` | número | — | Preço unitário. |

#### 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.

| 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). |
| `document` | texto | — | Documento. |
| `title` | texto | — | Título. |
| `group` | texto | filtra, ordena | Grupo. |
| `account` | texto | filtra, ordena | Conta. |
| `subaccount` | texto | filtra, ordena | Subconta. |
| `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 | — | Produtividade estimada. |
| `estimatedYieldPerHa` | número | — | Produtividade estimada por hectare. |
| `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. |
| `season` | texto | filtra, ordena | Ano-safra. |
| `crop` | texto | filtra, ordena | Cultura. |
| `variety` | texto | filtra, ordena | Variedade. |
| `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. |
| `status` | texto | filtra, ordena | Situação do orçamento para o talhão. |

#### 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 | — | Quantidade. |
| `latitude` | número | — | Latitude. |
| `longitude` | número | — | 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. |
| `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.

| 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 | Tipo do movimento: entrada, saída ou ajuste. |
| `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. |

#### 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. O saldo acumulado não é exposto, pela mesma razão do estoque.

| 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 conciliação. |
| `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. |

#### 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. |

#### 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 | — | 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ó.

| 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. |

#### 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. |

#### 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. |