Cropland API Documentation

🔑 Autenticação

ℹ️ Formato: Bearer {sua_api_key}

POST

Importar Estoque

/api/import/estoque

▼

Importa um arquivo Excel (.xlsx, .xls) ou CSV contendo dados de estoque. O arquivo é processado e armazenado para posterior análise na plataforma Cropland.

📋 Colunas esperadas no arquivo

Coluna	Campo	Obrig.	Para que serve
Loja (ou Filial)	filial	Sim	Filial do registro — formato COD:Nome, ex.: 076:Loja Campos Gerais (define o level3/level4)
Data	data	Sim	Data do registro do estoque (base da limpeza mensal)
Cód. Item	codigoItem	Sim	Código externo do produto (product_external_code)
Item (ou Produto)	item	Sim	Nome do produto
Estoque Disponível	estoqueDisponivel	Sim	Quantidade disponível (unidades)
Custo Ajustado Estimado	custoAjustado	Sim	Preço unitário
Esto. Disponível Kg/Lt	estoqueDisponivelVol	Sim	Volume disponível (KG/L)
Fornecedor	fornecedor	Não	Indústria — não utilizada no processamento
Valor Total	valorTotal	Não	Valor total da linha

Variações de escrita são aceitas (acentos, maiúsculas, espaços e pontuação são ignorados). Os cabeçalhos devem estar na primeira linha da planilha. Sem uma coluna obrigatória, o processamento do arquivo é adiado.

Arquivo (Excel/CSV - Máx. 10MB)

Clique para selecionar ou arraste o arquivo aqui Formatos aceitos: .xlsx, .xls, .csv ✓

Processando arquivo...

POST

Importar Vendas

/api/import/vendas

▼

Importa um arquivo Excel ou CSV contendo dados de vendas. Essencial para análise de performance e gestão de vendas em tempo real na plataforma Cropland.

📋 Colunas esperadas no arquivo

Coluna	Campo	Obrig.	Para que serve
DATA - Ano	ano	Sim	Ano da competência (ex.: 2026)
DATA - Mês	mes	Sim	Mês da competência (nome ou MM/AAAA)
Filial	filial	Sim	Filial — formato COD:Nome, ex.: L12:Loja Monte Carmelo (define o level3/level4)
Documento Cliente	documentoCliente	Sim	Código do cliente (customer_external_code)
Código do Item	codigoItem	Sim	Código externo do produto (product_external_code)
Item - Descrição	item	Sim	Nome do produto
VOL. POG KG/LT	volume	Sim	Volume vendido (KG/L)
VALOR POG UNITARIO	precoUnit	Sim	Preço unitário
VALOR TOTAL POG	valorTotal	Sim	Valor total da venda
Nome Fornecedor	fornecedor	Não	Indústria — não utilizada no processamento

Arquivo (Excel/CSV - Máx. 10MB)

Clique para selecionar ou arraste o arquivo aqui Formatos aceitos: .xlsx, .xls, .csv ✓

Processando arquivo...

POST

Importar SOC

/api/import/soc

▼

Importa um arquivo Excel ou CSV contendo dados de SOC (Sales Order Confirmation). Utilizado para confirmação de pedidos e gestão do canal de vendas.

📋 Colunas esperadas no arquivo

Coluna	Campo	Obrig.	Para que serve
DATA - Ano	ano	Sim	Ano da competência — define a safra do rateio level3
DATA - Mês	mes	Sim	Mês da competência (nome ou MM/AAAA)
Filial	filial	Sim	Filial (level3) — formato COD:Nome. O SOC grava direto no level3 (sem level4/rateio de level4)
Bayer	bayer	Sim	SOC da indústria Bayer (baseline — referência de quanto a Bayer vende sobre o total)
Outros	outros	Sim	SOC das demais indústrias (marcas não identificadas no relatório)
Total Geral	totalGeral	Não	Venda total do canal (todas as marcas). Se vazio, usa Bayer + Outros

Os valores de Bayer/Outros/Total Geral alimentam a baseline do SOC (industry_soc_year1), distribuídos pelo rateio level3 (crop fixo "Soja" por enquanto). Variações de escrita são aceitas; cabeçalhos na primeira linha da planilha.

Arquivo (Excel/CSV - Máx. 10MB)

Clique para selecionar ou arraste o arquivo aqui Formatos aceitos: .xlsx, .xls, .csv ✓

Processando arquivo...

POST

Importar Pedido

/api/import/pedido

▼

Importa um arquivo Excel ou CSV contendo dados de pedidos. Fundamental para o planejamento colaborativo e gestão de indicadores de vendas na Cropland.

📋 Colunas esperadas no arquivo

Coluna	Campo	Obrig.	Para que serve
DATA - Ano	ano	Sim	Ano da competência — define a safra do rateio level3
DATA - Mês	mes	Sim	Mês da competência (nome ou MM/AAAA)
Filial	filial	Sim	Filial — formato COD:Nome (define o level3/level4 via rateio)
Item - Descrição	item	Sim	Nome do produto
VOLUME AV KG/LT	volume	Sim	Volume do pedido (KG/L)
VALOR UNITARIO ACORDO DE VENDAS	precoUnit	Sim	Preço unitário
VALOR TOTAL ACORDO	valorTotal	Sim	Valor total do pedido
Código do Item	codigoItem	Não	Código externo do produto — sem ele, a busca do produto cai para o nome
Documento Cliente	documentoCliente	Não	Código do cliente — mapeado, mas o pedido não grava customer_id
Nome Fornecedor	fornecedor	Não	Indústria — não utilizada no processamento

Arquivo (Excel/CSV - Máx. 10MB)

Clique para selecionar ou arraste o arquivo aqui Formatos aceitos: .xlsx, .xls, .csv ✓

Processando arquivo...

🔄 Extração diária — o que precisamos

Para carregar a plataforma automaticamente, precisamos que o sistema do cliente disponibilize dois endpoints GET (estoque e vendas) que o Cropland consome uma vez ao dia, recebendo como parâmetro a data da consulta e devolvendo os dados em JSON.

Extração	Método	Parâmetro de data	Período consultado pelo Cropland
Estoque	GET	Data de referência	Dia corrente (execução diária)
Vendas	GET	Data inicial e data final	Ano corrente (01/01 a 31/12)

Datas no formato YYYY-MM-DD. Se houver mais de uma filial, o Cropland faz uma chamada por filial (via header tenantId ou parâmetro equivalente — alinhamos com o formato disponível).

🧪 Exemplo de requisição

# Estoque — data de referência
GET http://<servidor>:<porta>/<recurso-estoque>/2026-09-18

# Vendas — intervalo de datas
GET http://<servidor>:<porta>/<recurso-vendas>/2026-01-01/2026-12-31

Headers:
  Authorization: Basic <credenciais>
  Accept: application/json

Credenciais de acesso (usuário/senha) devem ser fornecidas à Cropland por canal seguro. O layout da URL pode se adaptar ao padrão já disponível no sistema — o essencial é receber a data e responder em JSON.

📦 Formato da resposta

A resposta pode ser um array JSON direto de registros ou um objeto com a propriedade items contendo o array. Período sem dados deve retornar array vazio ([]) com HTTP 200 — é situação normal.

[
  { "campo": "valor", ... },
  { "campo": "valor", ... }
]

// também aceito:
{ "items": [ { ... }, { ... } ] }

📋 JSON necessário — Estoque

Campos esperados em cada registro. Sufixos: _pro produto. Campos marcados como essenciais são os usados nas análises; os demais são complementares e enriquecem o resultado.

Campo	Tipo	Descrição
codi_pro	string	Código do produto — essencial
desc_pro	string	Descrição do produto — essencial
qtde_pro	number	Quantidade total em estoque — essencial
qtdi_pro	number	Quantidade disponível para entrega
qtbl_pro	number	Quantidade bloqueada
qttr_pro	number	Quantidade em trânsito
cmed_pro	number	Custo médio
unid_pro	string	Unidade de medida
lote_pro	string	Lote
date_pro	date	Data do registro (YYYY-MM-DD)
dven_pro	date	Data de vencimento do lote
barr_pro	string	Código de barras (EAN)
codi_fab / codi_rev / cind_pro / ncmp_pro / fsem_pro / trat_pro	string	Fabricante, revisão, código industrial, NCM, semana e tratamento — complementares

Exemplo de registro

{
  "codi_pro": "000123",
  "desc_pro": "HERBICIDA X 5L",
  "qtde_pro": 120.5,
  "qtdi_pro": 118,
  "qtbl_pro": 0,
  "qttr_pro": 0,
  "cmed_pro": 187.45,
  "unid_pro": "UN",
  "lote_pro": "L2609A",
  "date_pro": "2026-09-18",
  "dven_pro": "2027-06-30",
  "barr_pro": "7891234500019"
}

📋 JSON necessário — Vendas

Campos esperados em cada registro (uma linha por venda/produto). Sufixos: _ven venda, _cli cliente, _pro produto, _ivn item da nota, _cul cultura.

Campo	Tipo	Descrição
data_ven	date	Data de emissão da venda — essencial
codi_cli / nome_cli	string	Código e nome do cliente — essencial
codi_pro / desc_pro	string	Código e descrição do produto — essencial
codi_cul / desc_cul	string	Cultura (código/descrição) — essencial
qtde_ivn	number	Quantidade vendida — essencial
pliq_ivn	number	Valor total da venda — essencial
pbru_ivn	number	Valor bruto
codi_ven	string	Código único da venda (evita duplicidade entre cargas)
nume_ven / seri_ven	string	Número e série da nota fiscal
codi_ved / nome_ved	string	Vendedor
muni_cli / cnpj_cli	string	Município e CNPJ do cliente
tipo_con	string	Tipo de negócio / condição
unid_pro / lote	string	Unidade e lote do item
cfop_ven / oper_ven / stat_ven	string	CFOP, operação e status — complementares

Exemplo de registro

{
  "data_ven": "2026-09-10",
  "codi_cli": "000456",
  "nome_cli": "AGROPECUARIA EXEMPLO LTDA",
  "cnpj_cli": "12.345.678/0001-90",
  "muni_cli": "UBERLANDIA",
  "codi_pro": "000123",
  "desc_pro": "HERBICIDA X 5L",
  "codi_cul": "SOJA",
  "desc_cul": "SOJA",
  "qtde_ivn": 50,
  "pliq_ivn": 11875.00,
  "pbru_ivn": 12500.00,
  "codi_ven": "000123456",
  "nume_ven": "001234",
  "seri_ven": "1",
  "codi_ved": "0007",
  "nome_ved": "JOAO VENDEDOR",
  "tipo_con": "PRZ",
  "unid_pro": "UN"
}

⚠️ Informações importantes

Autenticação — Basic Auth (Authorization); credenciais fornecidas pela cooperativa/cliente à Cropland por canal seguro.
Campos numéricos — como número ou string numérica (ex.: 120.5 ou "120.5"); datas em YYYY-MM-DD; campos vazios são aceitos (tratamos como nulos).
Uma chamada por filial — falha ou ausência de dados em uma filial não interrompe as demais.
Janela de consumo — execução diária automática; o endpoint deve responder dentro de um timeout de leitura de até 300s por chamada.
Disponibilidade — o serviço precisa estar acessível no horário da execução (madrinhada/manhã).
Mudanças de estrutura — qualquer alteração de campos ou formato deve ser comunicada à Cropland antes da atualização.