aegro-estoquista
GitHub管理Aegro平台的库存与投入品，涵盖库存项、存储位置、流转日志、农业元素及目录。支持查询库存状态、记录出入库、转移、消耗及手动调整，关联财务分类，适用于农业物资的全生命周期追踪。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill aegro-estoquista -g -y
SKILL.md
Frontmatter
{
"name": "aegro-estoquista",
"version": "0.5.1",
"description": "Dominio de estoque e insumos do Aegro - itens, locais, movimentacoes, catalogos e elementos"
}
Aegro Estoquista
Skill especializada no dominio de estoque e insumos da plataforma Aegro. Cobre itens de estoque (posicoes), locais de armazenamento, movimentacoes (logs), elementos (insumos) e catalogos.
1. Vocabulario
| Termo Aegro | Termo CLI | Descricao |
|---|---|---|
| Item de estoque | stock item |
Posicao de estoque = cruzamento de um elemento em um local. Representa "quanto tem onde". |
| Local de estoque | stock location |
Armazem, deposito, silo ou qualquer local fisico de armazenamento. |
| Movimentacao de estoque | stock log |
Registro de entrada, saida, transferencia ou consumo de um item. |
| Elemento | elements |
Insumo agricola. Categorias: DEFENSIVE, FERTILIZER, SEED, ITEM, SERVICE. |
| Catalogo | catalogs |
Base de dados pre-definida de elementos. Somente leitura. Usado como referencia. |
| Entrada manual | stock entry |
Tipo MANUAL_ENTRY. Registra compra ou recebimento. Possui valor monetario. |
| Remocao manual | stock removal |
Tipo MANUAL_REMOVAL. Registra perda, ajuste ou descarte. Sem valor monetario. |
| Transferencia | stock transfer |
Tipo TRANSFER. Move quantidade entre dois locais. Sem valor monetario. |
| Consumo por atividade | ACTIVITY_CONSUMPTION | Automatico. Gerado quando uma atividade agricola realizada consome insumos. |
| Tipo de defensivo | --type |
HERBICIDE, INSECTICIDE, FUNGICIDE, ADJUVANT, BIOLOGICAL, OTHER. |
| Tipo de semente | --type |
SOYBEAN, CORN, WHEAT, COTTON, RICE, BEAN, COFFEE, SUGARCANE, OTHER. |
| Unidade de medida | --unit |
kg, L, un, t, sc (saca), mL, g, etc. |
| Quantidade | quantity |
Objeto: {"magnitude": X, "unit": "kg"}. Magnitude pode ser negativa (divergencia). |
| Associacao financeira | set-categories |
Vincula elemento a categorias financeiras de receita e/ou despesa. |
2. Modelo de Dados
FARM
+-- STOCK_LOCATION (local de armazenamento)
| +-- STOCK_ITEM (1:N posicoes de estoque por local)
| elementKey -> ELEMENT
| locationKey -> STOCK_LOCATION
+-- ELEMENT (insumo cadastrado na fazenda)
| categoria: DEFENSIVE | FERTILIZER | SEED | ITEM | SERVICE
| +-- STOCK_ITEM (1:N posicoes em diferentes locais)
| +-- set-categories -> FINANCIAL_CATEGORY (ponte com dominio financeiro)
+-- STOCK_LOG (historico de movimentacoes)
| elementKey -> ELEMENT
| sourceLocationKey -> STOCK_LOCATION (origem, para removal e transfer)
| destinationLocationKey -> STOCK_LOCATION (destino, para entry e transfer)
+-- CATALOG (base pre-definida, somente leitura)
+-- CATALOG_ELEMENT (referencia para criar elementos)
Relacionamentos-chave:
- STOCK_ITEM = intersecao ELEMENT x STOCK_LOCATION (posicao de estoque).
- STOCK_LOG registra toda movimentacao (entrada, saida, transferencia, consumo).
- ACTIVITY_REALIZATION gera STOCK_LOG de consumo automaticamente (dominio atividades).
- CATALOG e somente leitura; serve para buscar elementos padrao do mercado.
elements set-categoriesconecta estoque ao dominio financeiro.
3. Regras de Negocio
-
Quantidade pode ser negativa: Se remocoes + consumos superam entradas, a posicao fica negativa. Isso indica divergencia de estoque, nao erro. O sistema permite.
-
Formato de quantidade: Sempre
{"magnitude": X, "unit": "kg"}. O campo emagnitude, naoamountouquantity. -
Entry tem valor monetario, Removal e Transfer nao:
stock entry: requer--amounte--currency. Body:{"amount": {"amount": X, "currencyCode": "BRL"}}.stock removal: NAO possui campo de valor. ApenaselementKey,quantity,occurrenceDate,sourceLocationKey.stock transfer: NAO possui campo de valor. PossuisourceLocationKeyEdestinationLocationKey.
-
Endpoints de criacao de movimentacao:
- Entry:
POST /pub/v1/stock-logs/manual-entries - Removal:
POST /pub/v1/stock-logs/manual-removals - Transfer:
POST /pub/v1/stock-logs(endpoint generico)
- Entry:
-
Elementos por categoria tem endpoints especificos:
- Defensivos:
POST /pub/v1/elements/defensives(requer--type) - Fertilizantes:
POST /pub/v1/elements/fertilizers(sem--type) - Sementes:
POST /pub/v1/elements/seeds(requer--type) - Itens:
POST /pub/v1/elements/items(requer--type) - Servicos:
POST /pub/v1/elements/services(sem--type, sem--manufacturer)
- Defensivos:
-
set-categories e ponte entre dominios: Vincula elemento a categorias financeiras. Formato do body:
{"associations": {"revenueFinancialCategory": {"key": "financialCategory::abc"}, "expenseFinancialCategory": {"key": "financialCategory::def"}}} -
Catalogos sao somente leitura: Nao e possivel criar, editar ou excluir elementos de catalogo. Use-os como referencia para criar seus proprios elementos.
-
Paginacao padrao: Todos os filtros usam
requiredPageNumberemaximumItemsPerPageCount: 50.
4. Referencia de Comandos
4.1 stock (itens, locais e movimentacoes)
| Comando | Tipo | Parametros obrigatorios | Parametros opcionais |
|---|---|---|---|
item <key> |
GET | key (argumento) |
--output |
location <key> |
GET | key (argumento) |
--output |
items |
POST | (nenhum) | --location-key, --element-key, --crop-key, --page |
locations |
POST | (nenhum) | --page |
logs |
POST | (nenhum) | --element-key, --start-date, --end-date, --source-key, --dest-key, --page |
log <key> |
GET | key (argumento) |
--output |
entry |
POST | --element-key, --quantity, --unit, --date, --amount, --dest-key |
--currency (default BRL), --observations |
removal |
POST | --element-key, --quantity, --unit, --date, --source-key |
--observations |
transfer |
POST | --element-key, --quantity, --unit, --date, --source-key, --dest-key |
--observations |
Exemplos reais:
# Listar todos os itens de estoque de um elemento
aegro stock items --element-key element::abc123
# Listar itens em um local especifico
aegro stock items --location-key stockLocation::def456
# Listar locais de estoque
aegro stock locations --output table
# Consultar historico de movimentacoes de um elemento no periodo da safra
aegro stock logs --element-key element::abc123 \
--start-date 2025-09-01 --end-date 2026-03-13
# Filtrar movimentacoes por local de origem
aegro stock logs --source-key stockLocation::def456
# Registrar entrada de estoque (compra de 50kg a R$ 500)
aegro stock entry --element-key element::abc123 \
--quantity 50 --unit kg --date 2026-03-13 \
--amount 500 --currency BRL --dest-key stockLocation::def456
# Registrar remocao de estoque (perda/ajuste de 5kg)
aegro stock removal --element-key element::abc123 \
--quantity 5 --unit kg --date 2026-03-13 \
--source-key stockLocation::def456 --observations "Perda por validade"
# Transferir 10kg entre locais
aegro stock transfer --element-key element::abc123 \
--quantity 10 --unit kg --date 2026-03-13 \
--source-key stockLocation::s1 --dest-key stockLocation::s2
4.2 elements (insumos)
| Comando | Tipo | Parametros obrigatorios | Parametros opcionais |
|---|---|---|---|
get <key> |
GET | key (argumento) |
--output |
list |
POST | (nenhum) | --category (repetivel), --type (repetivel), --page |
create-defensive |
POST | --name, --type, --unit |
--manufacturer, --observations |
create-fertilizer |
POST | --name, --unit |
--manufacturer, --observations |
create-seed |
POST | --name, --type, --unit |
--manufacturer, --observations |
create-item |
POST | --name, --type, --unit |
--manufacturer, --observations |
create-service |
POST | --name, --unit |
(nenhum) |
set-categories <key> |
POST | element_key (argumento) |
--revenue-category-key, --expense-category-key |
Exemplos reais:
# Listar todos os defensivos
aegro elements list --category DEFENSIVE
# Listar herbicidas especificamente
aegro elements list --category DEFENSIVE --type HERBICIDE
# Listar fertilizantes e sementes
aegro elements list --category FERTILIZER --category SEED
# Criar defensivo herbicida
aegro elements create-defensive --name "Roundup Original" \
--type HERBICIDE --unit L --manufacturer "Bayer"
# Criar fertilizante
aegro elements create-fertilizer --name "Ureia 46%" --unit kg \
--manufacturer "Mosaic"
# Criar semente de soja
aegro elements create-seed --name "TMG 2381 IPRO" --type SOYBEAN --unit kg
# Criar servico
aegro elements create-service --name "Pulverizacao Aerea" --unit HA
# Criar item generico
aegro elements create-item --name "Sacaria 60kg" --type GENERAL --unit UN
# Vincular elemento a categorias financeiras
aegro elements set-categories element::abc123 \
--revenue-category-key financialCategory::rev1 \
--expense-category-key financialCategory::exp1
4.3 catalogs (catalogos de referencia)
| Comando | Tipo | Parametros obrigatorios | Parametros opcionais |
|---|---|---|---|
list |
GET | (nenhum) | --output |
element-keys <key> |
GET | catalog_key (argumento) |
--output |
elements <key> |
POST | catalog_key (argumento) |
--category (repetivel), --search-text, --page |
Exemplos reais:
# Listar catalogos disponiveis
aegro catalogs list
# Listar chaves de elementos de um catalogo
aegro catalogs element-keys catalog::abc123
# Buscar elemento no catalogo por nome
aegro catalogs elements catalog::abc123 --search-text "Roundup" --category DEFENSIVE
# Listar sementes disponiveis no catalogo
aegro catalogs elements catalog::abc123 --category SEED --page 1
5. Gotchas
CRITICO: Formato de valor monetario em entry
O campo amount da entrada de estoque usa currencyCode (nao currency):
{"amount": {"amount": 500.00, "currencyCode": "BRL"}}
Isso e DIFERENTE do formato da parcela financeira ({"amount": X, "currency": "BRL"}).
create-seed retorna HTTP 500 (Bug #5)
A criacao de sementes via API retorna erro 500 intermitentemente. Este e um bug conhecido da API Aegro. Workaround: criar a semente pela interface web do Aegro e depois consultar via CLI com aegro elements list --category SEED.
set-categories usa formato aninhado
O body de set-categories nao e uma lista simples de keys. E um objeto aninhado:
{
"associations": {
"revenueFinancialCategory": {"key": "financialCategory::abc"},
"expenseFinancialCategory": {"key": "financialCategory::def"}
}
}
Ambos os campos sao opcionais, mas pelo menos um deve ser fornecido.
Transfer usa endpoint generico
Enquanto entry usa /stock-logs/manual-entries e removal usa /stock-logs/manual-removals, transfer usa o endpoint raiz /stock-logs. Nao confunda os endpoints.
Filtros de logs sem --element-key podem retornar volumes enormes
O endpoint stock logs sem filtro de elemento retorna TODAS as movimentacoes da fazenda. Sempre filtre por --element-key ou por periodo (--start-date / --end-date) para evitar respostas enormes.
Campo "occurrenceDate" no body (nao "date")
O CLI aceita --date, mas no body JSON o campo se chama occurrenceDate. Isso e tratado pelo CLI, mas e importante saber ao debugar.
Fertilizante e servico NAO tem --type
Diferente de defensivo, semente e item, os endpoints de criacao de fertilizante e servico nao aceitam --type. Enviar --type gera erro.
6. Padroes e Exemplos
Verificar estoque total de um elemento em todos os locais
# 1. Listar todas as posicoes do elemento
aegro stock items --element-key element::abc123 --output table
# Cada item retorna a quantidade atual no local. Some as magnitudes para o total.
Historico de movimentacoes no periodo de safra
# Movimentacoes de semente de soja na safra 2025/2026
aegro stock logs --element-key element::abc123 \
--start-date 2025-09-01 --end-date 2026-03-31
# Para filtrar por local especifico
aegro stock logs --element-key element::abc123 \
--source-key stockLocation::def456 --start-date 2025-09-01
Formula de reconciliacao de estoque
Posicao atual = Saldo inicial
+ SUM(entradas manuais)
- SUM(remocoes manuais)
- SUM(consumos por atividade)
+/- SUM(transferencias)
Para verificar:
1. aegro stock items --element-key element::xxx (posicao atual)
2. aegro stock logs --element-key element::xxx --start-date YYYY-MM-DD (historico)
3. Comparar soma dos logs com posicao atual
Fluxo completo: cadastrar insumo e dar entrada
# 1. Consultar catalogo para referencia
aegro catalogs elements catalog::abc --search-text "Glifosato" --category DEFENSIVE
# 2. Criar o elemento na fazenda
aegro elements create-defensive --name "Glifosato 480 SL" \
--type HERBICIDE --unit L --manufacturer "Nortox"
# 3. Anotar a key retornada (element::xyz789)
# 4. Verificar locais de estoque disponiveis
aegro stock locations --output table
# 5. Registrar entrada de compra
aegro stock entry --element-key element::xyz789 \
--quantity 200 --unit L --date 2026-03-13 \
--amount 3600 --currency BRL \
--dest-key stockLocation::armazem1 \
--observations "NF 12345 - Nortox"
# 6. Vincular a categoria financeira de despesa
aegro elements set-categories element::xyz789 \
--expense-category-key financialCategory::defensivos
Transferir estoque entre depositos
# 1. Verificar posicao no deposito de origem
aegro stock items --element-key element::abc123 --location-key stockLocation::origem
# 2. Executar transferencia
aegro stock transfer --element-key element::abc123 \
--quantity 50 --unit L --date 2026-03-13 \
--source-key stockLocation::origem --dest-key stockLocation::destino
# 3. Verificar posicoes atualizadas
aegro stock items --element-key element::abc123 --output table
Buscar elemento no catalogo e criar na fazenda
# 1. Listar catalogos
aegro catalogs list
# 2. Buscar no catalogo
aegro catalogs elements catalog::padrao --search-text "Ureia" --category FERTILIZER
# 3. Criar na fazenda baseado nos dados do catalogo
aegro elements create-fertilizer --name "Ureia 46%" --unit kg --manufacturer "Petrobras"
7. Anti-padroes
-
Nao faca removal maior que o disponivel sem avisar. O sistema permite e cria posicao negativa. Sempre verifique a posicao atual com
aegro stock items --element-key <key>antes de executar removal. -
Nao confunda items (posicao) com logs (historico).
stock itemsmostra quanto tem agora.stock logsmostra o que aconteceu ao longo do tempo. Para saber o saldo, useitems. Para auditoria, uselogs. -
Sempre especifique --element-key em logs. Sem filtro,
stock logsretorna todas as movimentacoes da fazenda inteira, potencialmente milhares de registros. Filtre sempre. -
Nao tente modificar catalogos. Catalogos sao somente leitura. Para personalizar um elemento do catalogo, crie um novo elemento na fazenda usando os dados do catalogo como referencia.
-
Nao envie --type ao criar fertilizante ou servico. Esses endpoints nao aceitam tipo. Defensivo, semente e item aceitam e exigem
--type. -
Nao ignore o Bug #5 (create-seed). Se
create-seedfalhar com 500, nao tente repetir varias vezes. Use a interface web do Aegro para criar a semente. -
Nao confunda endpoints de movimentacao. Entry usa
/manual-entries, removal usa/manual-removals, transfer usa o endpoint raiz/stock-logs. Usar o endpoint errado causa erro ou comportamento inesperado. -
Nao esqueca set-categories apos criar elemento. Sem a associacao financeira, lancamentos de compra desse insumo nao serao classificados corretamente no financeiro.
Version History
- e0220ca Current 2026-07-05 23:34
