API upCampo

Q: Como faço a autenticação na API da upCampo?

Envie um POST para https://api.upcampo.com.br/autenticar com um JSON contendo client_id, client_secret, audience e grant_type. A upCampo entrega esse arquivo de credenciais pronto ao parceiro. O retorno traz um bearer token válido por 24 horas, que deve ir no cabeçalho Authorization de todas as chamadas seguintes.

Q: Como envio uma exclusão pela API?

Envie o registro com o atributo DELETADO igual a true. Não existe verbo DELETE: a exclusão é lógica e vai no mesmo POST do cadastro.

Q: Como puxar só o que mudou desde a última consulta?

Use o parâmetro datmod_inicial com a data e a hora da consulta anterior. Toda vez que um usuário cria ou altera um registro na upCampo, a data de modificação é atualizada. Guarde a data de cada consulta e use-a na consulta seguinte para receber apenas os registros alterados depois dela.

Q: O que significa cada STATUS do retorno de um POST?

INCLUIDO quer dizer que o registro era novo e foi criado; ALTERADO, que já existia e foi atualizado; ERRO, que ele foi barrado — e aí o motivo vem no campo MENSAGEM. Em documentos com cabeçalho e itens, basta uma linha com ERRO para o documento inteiro não ser gravado.

Q: Qual endpoint devolve os fardos de algodão colhidos?

GET /fardo, com data_inicial e data_final obrigatórios, devolve os fardos com QR Code, module id, peso da fazenda, hectares e talhão de origem. Para buscar um fardo específico na portaria da algodoeira, use GET /fardoEspecifico com qrcode, moduleid, codigo ou id. Quem usa essas rotas para a entrada na algodoeira precisa devolver o peso por POST /fardoPeso.

Q: Existe uma especificação da API legível por máquina?

Sim. A especificação OpenAPI 3.1 está em https://suporte.upcampo.com.br/api/openapi.json e cobre todos os endpoints, parâmetros, corpos e retornos documentados. Ela pode ser importada no Postman, no Insomnia, no Swagger UI ou em geradores de cliente.

Referência de integração — atualizada em 20/08/2026. Escrita por Jonas Rotilli.

A API de serviços da plataforma upCampo fornece um meio de integração com outros sistemas de forma fácil e independente de tecnologia. Ela é baseada em chamadas HTTP/HTTPS do tipo GET e POST, com corpo no formato JSON. Portanto, qualquer sistema com capacidade de realizar uma chamada HTTP/HTTPS convencional pode usar os diversos serviços fornecidos.

Na prática, o ERP do cliente (Siagri, Sankhya e outros) puxa cadastros e movimentos da upCampo, e devolve o identificador dele — o ID_REFERENCIA — para amarrar os dois lados. É esse campo que sustenta toda a integração; vale ler a seção ID_REFERENCIA antes de escrever a primeira linha de código.

Liberação caso a caso

Teoricamente é possível criar endpoint para qualquer tabela da plataforma. A liberação, porém, é feita caso a caso, conforme a análise da necessidade. Procure a equipe da upCampo para solicitar um endpoint que não esteja nesta página.

Como ler esta página

A coluna da esquerda descreve o endpoint, os parâmetros e os campos.
A coluna da direita traz a requisição pronta e um exemplo de retorno real.
Todos os exemplos usam $TOKEN no lugar do token obtido em /autenticar.

Explorar e testar

Esta página explica o que cada endpoint significa. Para ver a lista completa em formato interativo — com os campos, os schemas e um botão que dispara a chamada —, use o explorador:

🧪 Explorar os endpoints →

Especificação legível por máquina

Além desta página, a API tem uma especificação OpenAPI 3.1 com todos os endpoints, parâmetros, corpos e retornos. Importe-a no Postman, no Insomnia, no Swagger UI ou num gerador de cliente:

https://suporte.upcampo.com.br/api/openapi.json

Integração em três passos

# 1. autentica e guarda o token (vale 24 horas)
curl -X POST https://api.upcampo.com.br/autenticar \
  -H 'Content-Type: application/json' \
  -d @credenciais.json

# 2. consome os dados com o token no cabeçalho
curl https://api.upcampo.com.br/produto \
  -H 'Authorization: Bearer $TOKEN'

# 3. devolve o id do seu sistema para a upCampo
curl -X POST 'https://api.upcampo.com.br/produtoReferencia?id_upcampo=F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F&id_referencia=25' \
  -H 'Authorization: Bearer $TOKEN'

URL base

A URL de requisição segue sempre o mesmo padrão, independentemente do serviço:

https://api.upcampo.com.br

Ao longo desta página, URL BASE significa esse endereço. O servidor também responde em http://api.upcampo.com.br, mas use HTTPS: o tráfego leva o seu token.

Parâmetros

Em GET, os parâmetros vão sempre na URL. O nome do parâmetro diferencia maiúsculas de minúsculas e, por convenção, é todo minúsculo.
Havendo mais de um, concatene com &.
Não é preciso colocar aspas em strings.
Valores com espaço ou acento precisam ser codificados na URL (espaço = %20).

Formato das datas

São três formatos, e cada um aparece num lugar. O que se envia é sempre o padrão ISO — ano, mês, dia, nessa ordem, com hífen:

Onde	Formato	Exemplo
Filtro de período na URL — `data_inicial`, `data_final`	AAAA-MM-DD	2024-08-19
Filtro de modificação na URL — `datmod_inicial`	AAAA-MM-DD HH:MM:SS	2024-03-15 07:00:00
Campo de data no corpo de um POST — `DATA`, `DATPLA`, `DATCOL`, `DATVEN`	AAAA-MM-DD	2024-08-19

Nas respostas vêm os dois

Onde o retorno traz uma data, ele costuma trazer o par: DATA no formato AAAA-MM-DD, para o seu sistema processar, e DATASTRING em dd/mm/aaaa, para exibir na tela. O mesmo vale para DATPRE / DATPRESTRING e DATFIN / DATFINSTRING na ordem de serviço. Alguns campos voltam com hora e fuso (2023-12-12T12:55:15.532Z) — trate como data/hora completa, não corte a string.

Não use dd/mm/aaaa no envio

O valor do filtro vai direto para a consulta no banco. Em AAAA-MM-DD não há ambiguidade; em 31/01/2024 a leitura depende da configuração do servidor e a consulta pode falhar ou — pior — devolver o período errado sem avisar.

Sem data_inicial, a rota não devolve nada em vez de acusar erro. Se a resposta vier vazia sem motivo aparente, confira primeiro se o parâmetro de data foi enviado e está escrito exatamente assim — o nome também diferencia maiúsculas de minúsculas.

Um parâmetro

https://api.upcampo.com.br/talhao?setor=BOA VISTA

Mais de um parâmetro

https://api.upcampo.com.br/plantio_safra?id_safra=xyz&id_cultura=zyx

Autenticação POST

URL BASE + /autenticar

A autenticação usa um Client ID e um Client Secret fornecidos ao parceiro pela upCampo, num arquivo de credenciais em formato JSON. Esse par é individual por parceiro × empresa × fazenda — ou seja, cada fazenda exige um Client ID e um Client Secret próprios.

A empresa e a fazenda vêm do token

Na liberação do Client ID e do Secret, o ID da empresa e o ID da fazenda ficam fixados internamente na API. Cada endpoint retorna somente dados daquela empresa e daquela fazenda — não existe parâmetro para trocar isso na chamada.

Com o sucesso da autenticação, a API retorna um token com validade fixada em 24 horas. O corpo da resposta traz apenas access_token e token_type: o prazo fica dentro do próprio token, no campo exp do JWT.

Use o token até ele expirar

Não gere um token novo a cada chamada. São no máximo 10 tentativas de autenticação a cada 15 minutos por client_id; passando disso, a API responde 429 e o cabeçalho Retry-After diz em quantos segundos o acesso volta.

O limite é por client_id, então um parceiro que exagera não afeta os outros. Quem gera um token por dia e o reaproveita nunca esbarra nele — o token vale 24 horas.

A partir da geração do token, toda chamada seguinte precisa incluí-lo no cabeçalho, como bearer token:

Authorization: Bearer <token>

Corpo da requisição

Campo	Tipo	Observação
client_id	String	Fornecido pela upCampo.
client_secret	String	Fornecido pela upCampo.
audience	String	`https://api.upcampo.com.br`
grant_type	String	`client_credentials`

Este JSON é entregue pronto pela upCampo ao parceiro.

Requisição

curl -X POST https://api.upcampo.com.br/autenticar \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "CLIENT ID QUE A UPCAMPO LHE INFORMARÁ",
    "client_secret": "CLIENT SECRET QUE A UPCAMPO LHE INFORMARÁ",
    "audience": "https://api.upcampo.com.br",
    "grant_type": "client_credentials"
  }'

Corpo (body)

{
  "client_id": "CLIENT ID QUE A UPCAMPO LHE INFORMARÁ",
  "client_secret": "CLIENT SECRET QUE A UPCAMPO LHE INFORMARÁ",
  "audience": "https://api.upcampo.com.br",
  "grant_type": "client_credentials"
}

Token gerado200

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type": "Bearer"
}

Não autorizado401

{
  "status": "Invalid token"
}

Tentativas demais429

{
  "status": "Erro",
  "error": "Muitas tentativas de autenticação. Gere o token uma vez e use-o até expirar (24 horas), em vez de gerar um por chamada. Tente de novo em 900 segundos."
}

Testar o token GET

URL BASE + /teste

Faça um GET simples para a rota teste, com o bearer token informado. É a forma leve de conferir o token, sem sobrecarregar nenhuma rota de dados nem o banco.

Retornos possíveis

Situação	HTTP	Conteúdo
Autorizado	200 OK	`status`, `mensagem` e `nome` — o nome do token traz a fazenda e o ambiente (PROD ou HOMOLOGACAO).
Token não reconhecido	401	`"error": "Token não inválido"`
Token não informado	401	`"error": "Token não fornecido"`

Requisição

curl https://api.upcampo.com.br/teste \
  -H 'Authorization: Bearer $TOKEN'

Autorizado200

{
  "status": "Sucesso",
  "mensagem": "Hello world, você está na API da upCampo!",
  "nome": "Nome do token, nome da fazenda + PROD ou HOMOLOCACAO"
}

Token inválido401

{
  "status": "Erro",
  "error": "Token não inválido"
}

Token ausente401

{
  "status": "Erro",
  "error": "Token não fornecido"
}

Códigos de retorno

A API usa o padrão dos códigos HTTP em cada chamada.

Código	Significado
200	Autorizado — deu certo.
400	Erro de requisição: antes de chegar ao servidor, erro primário ou erro do banco de dados (coluna inexistente, por exemplo).
401	O token expirou ou é inválido; é preciso gerar de novo. O motivo detalhado vem no corpo da resposta.
429	Tentativas de autenticação demais para o mesmo `client_id` — limite de 10 a cada 15 minutos. O cabeçalho `Retry-After` traz em quantos segundos o acesso volta.
500	Erro de validação — a requisição chegou ao banco de dados e alguma regra barrou o registro. O corpo devolve o array de resultados com `STATUS: "ERRO"`.

Quando acontece erro de banco de dados, o padrão de retorno é um JSON com status e detalhe, com HTTP 400 — o exemplo ao lado.

Erro de banco400

{
  "status": "Erro",
  "detalhe": {
    "message": "Invalid column name 'teste'.",
    "code": "EREQUEST",
    "number": 207,
    "state": 1,
    "class": 16,
    "serverName": "pragueiroserver",
    "procName": "",
    "lineNumber": 1
  }
}

Regras gerais dos endpoints

Todas as tabelas têm uma coluna chamada ID_REFERENCIA. É nela que fica o identificador do registro no sistema do parceiro.
Em POST, passe todos os atributos do JSON em MAIÚSCULO.
Para excluir, informe o atributo DELETADO com valor true.
O corpo de um POST é sempre um array: dá para enviar vários registros na mesma requisição.

Inserção ou atualização?

Quem decide é o ID_REFERENCIA. Ao receber um POST, a upCampo procura na tabela correspondente um registro com aquele ID_REFERENCIA:

não existe → é uma inserção;
já existe → é uma atualização.

Retorno padrão de escrita

Campo	Significado
TABELA	Tabela em questão, a ser incluída ou alterada.
ID_UPCAMPO	Identificador interno da upCampo. É aqui que o parceiro o obtém, caso precise guardar.
ID_REFERENCIA	Identificador do sistema parceiro. Enviando mais de um registro na mesma requisição, o parceiro percorre o resultado para saber o status de cada id seu.
STATUS	Três opções: `INCLUIDO`, `ALTERADO` ou `ERRO`.
MENSAGEM	Quando o status é `ERRO`, descreve o motivo.

Documentos com cabeçalho e itens

Em movimentação e transferência o retorno traz uma linha CABECALHO e uma linha DETALHE por item. Basta uma linha com STATUS: "ERRO" para o documento inteiro não ser gravado.

Sucesso200

[
  {
    "TABELA": "PRODUTO",
    "ID_UPCAMPO": "7B6E1387-E3BC-4DE9-B8F2-63703B4F9495",
    "ID_REFERENCIA": "30",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Documento finalizado500

[
  {
    "TABELA": "CABECALHO",
    "ID_UPCAMPO": "B674DF03-052C-427D-9CCD-FFA553F88D18",
    "ID_REFERENCIA": "21",
    "STATUS": "ERRO",
    "MENSAGEM": "Documento finalizado não pode ser alterado"
  }
]

Produto não encontrado no item500

[
  {
    "TABELA": "CABECALHO",
    "ID_UPCAMPO": "31ACB79E-0FF8-453D-9AD2-0608C935D960",
    "ID_REFERENCIA": "22",
    "STATUS": "ERRO",
    "MENSAGEM": "Problema em algum item do documento"
  },
  {
    "TABELA": "DETALHE",
    "ID_UPCAMPO": "DBB01E35-53E5-453B-A7E2-03552B125992",
    "ID_REFERENCIA": "22_A",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  },
  {
    "TABELA": "DETALHE",
    "ID_UPCAMPO": null,
    "ID_REFERENCIA": "22_B",
    "STATUS": "ERRO",
    "MENSAGEM": "Produto não encontrado"
  }
]

Saldo negativo500

[
  {
    "TABELA": "CABECALHO",
    "ID_UPCAMPO": "BE2F2CEC-0142-41A0-A3A6-DAC557A78696",
    "ID_REFERENCIA": "22",
    "STATUS": "ERRO",
    "MENSAGEM": "Problema em algum item do documento"
  },
  {
    "TABELA": "DETALHE",
    "ID_UPCAMPO": null,
    "ID_REFERENCIA": null,
    "STATUS": "ERRO",
    "MENSAGEM": "Validacao: (MILHO EM GRAOS) - O saldo ficará negativo (origem) (-5.000000). 9 - Impossível continuar."
  }
]

ID_REFERENCIA

Esta coluna está presente em todas as tabelas e facilita bastante a vida do parceiro: ela aparece em todos os GET e é considerada em todos os POST.

O registro na upCampo tem o identificador próprio dele; na coluna ID_REFERENCIA o parceiro coloca o identificador do seu sistema. Há três caminhos para gravar essa referência:
- pelo sistema — todas as telas do portal têm um campo para isso;
- por um POST do objeto inteiro;
- pela rota de referência, que altera só esse campo — veja Atualizar só a referência.
Em qualquer GET de tabela que contenha, por exemplo, produto, virá um atributo ID_REFERENCIA.
Em um POST — de movimentação, digamos —, basta pôr no JSON o atributo com o ID_REFERENCIA que a upCampo localiza o registro correspondente na tabela dela.

Convenção dos nomes

Nos retornos, o mesmo dado aparece em três formas: <ENTIDADE>_DESCRICAO (o nome na upCampo), ID_<ENTIDADE>_UPCAMPO (o identificador interno) e ID_<ENTIDADE>_REFERENCIA (o identificador no seu ERP). Nos envios, use sempre a forma _REFERENCIA.

Gravar a referência de um produto

curl -X POST 'https://api.upcampo.com.br/produtoReferencia?id_upcampo=F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F&id_referencia=25' \
  -H 'Authorization: Bearer $TOKEN'

Como o dado volta em um GET

{
  "PRODUTO_DESCRICAO": "BRAVONIL 720",
  "ID_PRODUTO_UPCAMPO": "BC8DC697-9673-4636-B78D-370926042403",
  "ID_PRODUTO_REFERENCIA": "330"
}

Fluxo de sincronização

O cenário ideal de uso é este:

Toda vez que um usuário cria ou altera um registro na upCampo, a data de modificação é atualizada.
O parceiro faz um GET usando a data de modificação como parâmetro: datmod_inicial=2024-3-15 07:00. Grave a data de cada consulta para usá-la na consulta seguinte e recuperar apenas o que mudou desde então.
O parceiro processa os resultados no sistema dele: se já tiver id_referencia, é atualização; se não tiver, é inserção.
O parceiro faz um POST na rota de referência daquele grupo (por exemplo abastecimentoReferencia) com o identificador gerado do lado dele.

Janela de sete dias

Nas rotas de movimento — movimentação, transferência, ordem de serviço, levantamento, coleta climática — o período entre data_inicial e data_final é de no máximo 7 dias. Para carga histórica, faça várias chamadas em janelas seguidas.

Consulta incremental

# só o que mudou desde a última consulta
curl -G https://api.upcampo.com.br/abastecimento \
  -H 'Authorization: Bearer $TOKEN' \
  --data-urlencode 'datmod_inicial=2024-03-15 07:00'

Atualizar só a referência POST

Em alguns casos é necessário alterar somente a referência — ou seja, apenas gravar o identificador do sistema do parceiro na base da upCampo, para facilitar o uso futuro. Para não ter de preencher o objeto inteiro, existe uma forma simples: basta acrescentar os parâmetros id_upcampo (o identificador dentro da base da upCampo) e id_referencia (o identificador no sistema do parceiro).

URL BASE + /<entidade>Referencia?id_upcampo=…&id_referencia=…

Endpoints disponíveis

Rota	Entidade
/safraReferencia	Safra
/plantio_safraReferencia	Plantio da safra
/tipo_atividadeReferencia	Tipo de atividade
/equipeReferencia	Equipe
/funcionarioReferencia	Funcionário
/local_estoqueReferencia	Local de estoque
/culturaReferencia	Cultura
/variedadeReferencia	Variedade
/classeReferencia	Classe de produto
/produtoReferencia	Produto
/equipamentoReferencia	Equipamento / frota / bem feitoria
/movimentacaoReferencia	Movimentação (NF)
/transferenciaReferencia	Transferência entre locais de estoque
/fardoReferencia	Fardo
/abastecimentoReferencia	Abastecimento
/ordem_agricola_insumoReferencia	Ordem de serviço agrícola — insumos
/ordem_agricola_execucaoReferencia	Ordem de serviço agrícola — execuções
/ordem_agricola_completaReferencia	Ordem de serviço agrícola — completa. Aceita ainda o parâmetro opcional `codSai`, para quando o código gerado no sistema do parceiro é diferente do código da ordem na upCampo.

Requisição

curl -X POST 'https://api.upcampo.com.br/culturaReferencia?id_upcampo=135CFB89-1DAC-4A04-B7CA-4D2A0ADDAB29&id_referencia=1234' \
  -H 'Authorization: Bearer $TOKEN'

Ordem completa, com codSai

curl -X POST 'https://api.upcampo.com.br/ordem_agricola_completaReferencia?id_upcampo=…&id_referencia=…&codSai=…' \
  -H 'Authorization: Bearer $TOKEN'

Índice de endpoints

Os principais endpoints GET e seus parâmetros. A liberação de cada um é feita caso a caso — procure a upCampo para solicitar.

Título	Rota	Parâmetros	Área / módulo
Variedade	/variedade	Nenhum	Lavoura
Cultura	/cultura	Nenhum	Lavoura
Talhão	/talhao	`setor` (opcional)	Lavoura
Safra	/safra	Nenhum	Lavoura
Plantio Safra	/plantio_safra	`id_safra` (opcional) `id_cultura` (opcional)	Lavoura
Classe de Produto	/classe_produto	Nenhum	Estoque
Produto	/produto	`id_classe` (opcional)	Estoque
Local de estoque	/local_estoque	`setor` (opcional)	Estoque
Transferência entre locais de estoque	/transferencia	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias) `id_local_origem` e `id_local_destino` (opcionais)	Estoque
Movimentação (NF)	/movimentacao	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias)	Estoque
Ordem de serviço agrícola — INSUMOS	/ordem_agricola_insumo	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias)	Lavoura e Estoque
Ordem de serviço agrícola — EXECUÇÃO	/ordem_agricola_execucao	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias)	Lavoura e Estoque
Classificação de Equipamento	/classificacao_equipamento	Nenhum	Frota
Equipamento / Frota / Bem feitoria	/equipamento	`id_classificacao` (opcional)	Frota
Abastecimento	/abastecimento	`data_inicial` e `data_final` (obrigatórios) `id_local` e `id_local_referencia` (opcionais) `id_equipamento` e `id_equipamento_referencia` (opcionais) `numero`, `id_referencia`, `id_abastecimento_upcampo` (opcionais)	Frota
Pragas	/praga	Nenhum	Lavoura
Levantamentos	/levantamento	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias) `id_safra` (obrigatório) `id_plantio_safra` (opcional)	Lavoura
Coleta de informações climáticas	/coleta_climatica	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias)	Lavoura

Também documentados nesta página

Tipo de atividade/tipo_atividade Identificação resumida/identificacao_resumida Ordem de serviço completa/ordem_agricola_completa Devoluções da ordem/ordem_agricola_devolucao Inventário/inventario Saldo de estoque/estoque Fardos/fardo Peso do fardo/fardoPeso Fardo específico/fardoEspecifico Romaneio de colheita/romcol Classificação do romaneio/romcolClassificacao

Cultura GETPOST

URL BASE + /cultura

A cultura é o que se planta — soja, milho, algodão. Ela é o topo da hierarquia da lavoura: a variedade pertence a uma cultura, e o plantio da safra amarra cultura, variedade e talhão.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não encontrar, é um registro novo.
DESCRICAO	String	Sim	Nome.
CODIGO	String	—
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Requisição

curl -X POST https://api.upcampo.com.br/cultura \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d @cultura.json

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "Cultura- TESTE INTEGRACAO 2",
    "ATIVO": true,
    "DELETADO": false
  }
]

Retorno200

[
  {
    "TABELA": "CULTURA",
    "ID_UPCAMPO": "1D64C046-B166-4E66-8A2F-02E1E75102CA",
    "ID_REFERENCIA": "1",
    "STATUS": "ALTERADO",
    "MENSAGEM": ""
  }
]

Variedade GETPOST

URL BASE + /variedade

A variedade (ou cultivar) é o material genético plantado dentro de uma cultura. Toda variedade pertence a uma cultura — por isso o ID_CULTURA_REFERENCIA é obrigatório no envio.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não encontrar, é um registro novo.
DESCRICAO	String	Sim	Nome.
CODIGO	String	—
DIACIC	Integer	—	Dias do ciclo.
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.
ID_CULTURA_REFERENCIA	String	Sim	Identificador da cultura no ERP terceiro. Este código precisa estar mapeado no cadastro da upCampo para que o identificador dela seja localizado.

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "Variedade integracao",
    "ATIVO": true,
    "DELETADO": false,
    "ID_CULTURA_REFERENCIA": "1"
  }
]

Retorno do POST200

[
  {
    "TABELA": "VARIEDADE",
    "ID_UPCAMPO": "58637420-AF58-4BF5-9E6C-28E79078D263",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Retorno do GET200

[
  {
    "ID": "EBB2540D-15CA-4A4F-9989-8CF8C820E983",
    "CODIGO": "001",
    "DESCRICAO": "TMG 31 B3RF",
    "ATIVO": true,
    "DIACIC": 150,
    "ID_EMPRESA": "B28C5012-D7E8-4987-A9F1-188287F72FE9",
    "ID_CULTURA": "5795CCB1-44FC-44B8-AAB9-0DBDD4182E68",
    "ID_REFERENCIA": null
  }
]

Talhão GET

URL BASE + /talhao

O talhão é a área de plantio. Aceita o parâmetro opcional setor — na maioria das fazendas, o setor é o nome da unidade dentro do grupo. Use esta rota para descobrir a descrição exata e os identificadores do talhão antes de filtrar outras rotas por ele.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro.
DESCRICAO	String	Sim	Nome do talhão.
CODIGO	String	—
AREA	Número	Sim	Em hectares.
SETOR	String	—
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Envio de talhão

Para gravar o identificador do seu sistema num talhão já cadastrado, use a rota de referência. Para criar ou alterar talhão pela API, procure a equipe da upCampo: a liberação é feita caso a caso.

Requisição

curl -G https://api.upcampo.com.br/talhao \
  -H 'Authorization: Bearer $TOKEN' \
  --data-urlencode 'setor=BOA VISTA'

Estrutura do talhão

[
  {
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "TH 01",
    "AREA": 250.6,
    "SETOR": "BOA VISTA",
    "ATIVO": true,
    "DELETADO": false
  }
]

Retorno de escrita200

[
  {
    "TABELA": "TALHAO",
    "ID_UPCAMPO": "58637420-AF58-4BF5-9E6C-28E79078D263",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Safra GET

URL BASE + /safra

A safra é o ciclo produtivo — é ela que separa o que foi plantado, aplicado e colhido em um ano do que foi no ano seguinte. Praticamente toda rota de movimento carrega o identificador da safra.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro.
DESCRICAO	String	Sim	Nome da safra.
CODIGO	String	—
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Para amarrar a safra do seu ERP

Use /safraReferencia.

Requisição

curl https://api.upcampo.com.br/safra \
  -H 'Authorization: Bearer $TOKEN'

Estrutura da safra

[
  {
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "Safra 2025/2026",
    "ATIVO": true,
    "DELETADO": false
  }
]

Retorno de escrita200

[
  {
    "TABELA": "SAFRA",
    "ID_UPCAMPO": "58637420-AF58-4BF5-9E6C-28E79078D263",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Plantio da safra GET

URL BASE + /plantio_safra

O plantio da safra é o registro que amarra safra + talhão + cultura + variedade + área. É a chave de quase toda consulta de lavoura: o fardo, o romaneio e a ordem de serviço apontam para ele pelo ID_PLANTIO_SAFRA_UPCAMPO ou pelo ID_PLANTIO_SAFRA_REFERENCIA.

Parâmetros

Parâmetro	Obrigatório
id_safra	Opcional
id_cultura	Opcional

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro.
ID_SAFRA_REFERENCIA	String	Sim	Identificador da safra no ERP terceiro, mapeado no cadastro da upCampo.
ID_CULTURA_REFERENCIA	String	Sim	Identificador da cultura no ERP terceiro, mapeado no cadastro da upCampo.
ID_TALHAO_REFERENCIA	String	Sim	Identificador do talhão no ERP terceiro, mapeado no cadastro da upCampo.
ID_VARIEDADE_REFERENCIA	String	Sim	Identificador da variedade no ERP terceiro, mapeado no cadastro da upCampo.
DATPLA	String	—	Data de plantio, no formato `AAAA-MM-DD`.
DATCOL	String	—	Data de colheita, no formato `AAAA-MM-DD`.
AREA	Número	Sim	Em hectares.

Requisição

curl 'https://api.upcampo.com.br/plantio_safra?id_safra=xyz&id_cultura=zyx' \
  -H 'Authorization: Bearer $TOKEN'

Retorno200

[
  {
    "ID": "AD6DDC4D-981B-4755-8AE2-1F001D7E8B03",
    "ID_SAFRA": "8B1BA1A7-B454-47F0-A2A3-8DD9980F8514",
    "ID_QUADRA": "038F7B2C-C337-4401-8E18-9DE202D92112",
    "ID_CULTURA": "5795CCB1-44FC-44B8-AAB9-0DBDD4182E68",
    "ID_VARIEDADE": "EBB2540D-15CA-4A4F-9989-8CF8C820E983",
    "AREA": 81,
    "DATPLA": "2022-01-20T00:00:00.000Z",
    "DATCOL": null,
    "ID_DETALHE": null,
    "ATIVO": true,
    "ID_EMPRESA": "B28C5012-D7E8-4987-A9F1-188287F72FE9",
    "ID_FILIAL": "DE319CA8-601F-4E68-978D-D0FB0DC27457"
  }
]

Estrutura de envio

[
  {
    "ID_REFERENCIA": "1",
    "ID_SAFRA_REFERENCIA": "1",
    "ID_CULTURA_REFERENCIA": "1",
    "ID_TALHAO_REFERENCIA": "1",
    "ID_VARIEDADE_REFERENCIA": "1",
    "DATPLA": "2023-3-27",
    "DATCOL": "2024-3-01",
    "AREA": 200.50
  }
]

Classe de produto GETPOST

URL BASE + /classe_produto

A classe agrupa produtos por natureza — insumo, combustível, peça, lubrificante, serviço. É ela que decide o comportamento do produto no estoque e no custo, então cadastre a classe antes do produto.

Parâmetros do GET

Parâmetro	Observação
id_upcampo	Identificador interno da upCampo.
codigo
id_referencia	Identificador no sistema do parceiro.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não, é registro novo.
DESCRICAO	String	Sim	Nome da classe.
CODIGO	String	—
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Requisição

curl -X POST https://api.upcampo.com.br/classe_produto \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d @classe.json

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "Classe integracao",
    "ATIVO": true,
    "DELETADO": false
  }
]

Retorno200

[
  {
    "TABELA": "CLASSE",
    "ID_UPCAMPO": "58637420-AF58-4BF5-9E6C-28E79078D263",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Produto GETPOST

URL BASE + /produto

O produto é o item que entra e sai do estoque: insumo, combustível, peça — e também serviço. É o cadastro mais consultado da integração, porque a movimentação, a ordem de serviço e o abastecimento apontam todos para ele.

Parâmetros do GET

Parâmetro	Observação
id_upcampo	Identificador interno da upCampo.
codigo
id_referencia	Identificador no sistema do parceiro.
id_classe	Filtra por classe de produto.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não, é registro novo.
DESCRICAO	String	Sim	Nome do produto.
CODIGO	String	—
MARCA	String	—
CODUNI	String	—	Abreviação da unidade. Exemplo: `KG`.
ATIVO	Boolean	—	`true` ou `false`.
NCM	String	—
COMBUSTIVEL	Boolean	—	`true` ou `false`.
SEMENTE	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.
CLASSE_DESCRICAO	String	—	Descrição da classe na upCampo.
ID_CLASSE_UPCAMPO	String	—	Identificador da classe na upCampo.
ID_CLASSE_REFERENCIA	String	—	Identificador da classe no ERP terceiro. Precisa estar mapeado no cadastro da upCampo para que o identificador dela seja localizado.

Requisição

curl -X POST https://api.upcampo.com.br/produto \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d @produto.json

Corpo (body)

[
  {
    "ID_REFERENCIA": "30",
    "CODIGO": "0001",
    "DESCRICAO": "TV 40 POLEGADA - TESTE INTEGRACAO 1",
    "MARCA": "LG",
    "CODUNI": "UN",
    "ATIVO": true,
    "DELETADO": false,
    "ID_CLASSE_REFERENCIA": "25"
  }
]

Retorno200

[
  {
    "TABELA": "PRODUTO",
    "ID_UPCAMPO": "7E28F9F0-62BF-4C89-8D7F-84345CA5B183",
    "ID_REFERENCIA": "30",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Local de estoque GET

URL BASE + /local_estoque

O local de estoque é onde o produto fica guardado — barracão de insumos, tanque de diesel, armazém. Na upCampo o saldo e o custo médio são por produto e por local, e não por produto apenas; por isso quase toda rota de movimento exige o local.

Esta rota é somente leitura. Para gravar o identificador do seu sistema, use /local_estoqueReferencia. Aceita o parâmetro opcional setor.

Campos

Campo	Tipo	Observação
ID_UPCAMPO	String	Identificador na upCampo.
ID_REFERENCIA	String	Identificador no ERP terceiro.
DESCRICAO	String	Nome do local.
CODIGO	String
ATIVO	Boolean	`true` ou `false`.
DELETADO	Boolean	`true` ou `false`.

Requisição

curl https://api.upcampo.com.br/local_estoque \
  -H 'Authorization: Bearer $TOKEN'

Estrutura

[
  {
    "ID_UPCAMPO": "58637420-AF58-4BF5-9E6C-28E79078D263",
    "ID_REFERENCIA": "1",
    "CODIGO": "0001",
    "DESCRICAO": "Barracao de Insumos",
    "ATIVO": true,
    "DELETADO": false
  }
]

Equipamento / Frota / Bem feitoria GETPOST

URL BASE + /equipamento

Uma tela só para três coisas: frota (o que tem motor e roda — trator, colhedora, caminhão), equipamento (o implemento puxado) e bem feitoria (o que é imobilizado da fazenda). O campo TIPO é o que separa os três.

Aceita no GET o parâmetro opcional id_classificacao.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não, é registro novo.
TIPO	String	Sim	`Frota`, `Equipamento` ou `Bem Feitoria`.
DESCRICAO	String	Sim	Nome.
CODIGO	String	—	Código.
PLACA	String	—	Placa.
CHASSI	String	—	Chassi.
MODELO	String	—	Modelo.
MARCA	String	—	Marca.
ATIVO	Boolean	—	`true` ou `false`.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "TIPO": "Frota",
    "CODIGO": "0001",
    "DESCRICAO": "Trator 001",
    "PLACA": "JHD-1234",
    "CHASSI": "12345687",
    "MODELO": "T20",
    "MARCA": "JONH DEERE",
    "ATIVO": true,
    "DELETADO": false
  }
]

Retorno200

[
  {
    "TABELA": "EQUIPAMENTO",
    "ID_UPCAMPO": "659EAF57-7C02-4CEE-B063-17F05AB54624",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Tipo de atividade GET

URL BASE + /tipo_atividade

O tipo de atividade é o que a ordem de serviço faz: aplicação de defensivo, adubação, plantio, colheita. É por ele que se filtram as ordens (id_tipati ou id_tipati_referencia).

Campos

Campo	Tipo	Observação
ID	String	Identificador na upCampo.
ID_REFERENCIA	String	Identificador no ERP terceiro.
DESCRICAO	String	Nome do tipo de atividade.
CODIGO	String
ATIVO	Boolean	`true` ou `false`.
CLASSIFICACAO	String	Uma classificação padrão para o tipo de atividade.

Para gravar o identificador do seu ERP, use /tipo_atividadeReferencia.

Retorno200

[
  {
    "ID_REFERENCIA": "1",
    "ID": "1asd-1023-s344-1233-1233",
    "CODIGO": "0001",
    "DESCRICAO": "Aplicação de Defensivo Terreste",
    "ATIVO": true,
    "CLASSIFICACAO": "Aplicação de Defensivo"
  }
]

Identificação resumida GET

URL BASE + /identificacao_resumida

Ide. Res. é como o portal abrevia Identificação Resumida — também chamada de IDERES. É uma espécie de subgrupo do tipo de atividade: dentro de "Aplicação de defensivo", por exemplo, distingue "1 FUNGICIDA" de "INSETICIDA".

Campos

Campo	Tipo	Observação
ID	String	Identificador na upCampo.
ID_REFERENCIA	String	Identificador no ERP terceiro.
DESCRICAO	String	Nome da identificação resumida.
CODIGO	String
ATIVO	Boolean	`true` ou `false`.

Retorno200

[
  {
    "ID_REFERENCIA": "1",
    "ID": "1asd-1023-s344-1233-1233",
    "CODIGO": "0001",
    "DESCRICAO": "1 FUNGICIDA",
    "ATIVO": true
  }
]

Movimentação (NF) GETPOST

URL BASE + /movimentacao

A movimentação é a entrada de nota fiscal no estoque da fazenda — e não só de produto: nota de serviço (frete, manutenção feita fora, aplicação de terceiro) também entra por aqui. É ela que forma o custo médio de cada produto em cada local de estoque.

Parâmetros do GET

Três opções, excludentes:

Opção	Parâmetro	Observação
1	datmod_inicial	Data de modificação inicial. Formato `AAAA-MM-DD HH:MM:SS` — ex.: `2024-03-15 07:00:00`. A hora é opcional; sem ela, vale a partir da meia-noite. Combinável com `data_inicial` + `data_final` — a data do documento, em `AAAA-MM-DD`, janela máxima de 7 dias — e com `status` (`Finalizado` ou `Pendente`).
2	numero	Número da nota.
3	id_referencia	Identificador no sistema do parceiro.

Campos

Campo	Tipo	Obrigatório	Observação
Cabeçalho
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não, é registro novo.
NUMERO	String	Sim	Número da NF.
DATA	String	Sim	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
CNPJCPF	String	Sim	CNPJ ou CPF do emitente. Se a upCampo não encontrar, o emitente é adicionado automaticamente na base dela.
RAZSOC	String	Sim	Razão social do emitente.
NOMFAN	String	—	Nome fantasia do emitente.
CODFOR	String	—	Código do cadastro do emitente no sistema do parceiro.
CHANFE	String	—	Chave da NF-e.
VALTOT	Número	Sim	Valor total da NF.
VALDES	Número	—	Valor total de descontos.
VALFRE	Número	—	Valor total de frete.
VALLIQ	Número	Sim	Valor líquido final, já com os descontos.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.
ITENS	Array	Sim	Os itens da nota.
Itens
ID_REFERENCIA	String	Sim	Identificador do item no ERP terceiro.
ID_PRODUTO_REFERENCIA	String	Sim	Identificador do produto no ERP terceiro, mapeado no cadastro da upCampo.
ID_LOTE_REFERENCIA	String	—	Identificador do lote no ERP terceiro, mapeado no cadastro da upCampo.
DATVEN	String	—	Data de vencimento do lote (se houver lote), formato `AAAA-MM-DD`.
NUMLOT	String	—	Número ou código do lote (se houver lote).
ID_LOCEST_REFERENCIA	String	Um ou outro	Identificador do local de estoque no ERP terceiro, mapeado no cadastro da upCampo.
ID_EQUIPAMENTO_REFERENCIA	String	Um ou outro	Identificador do equipamento ou frota no ERP terceiro — use quando o custo for lançado direto para uma frota, em vez de entrar no estoque.
CODUNI	String	—	Abreviação da unidade. Exemplo: `KG`.
QUANTIDADE	Número	Sim	Quantidade do produto.
VALUNI	Número	Sim	Valor unitário do produto.
VALTOT	Número	Sim	Valor total do produto.
VALDES	Número	—	Valor do desconto do produto.
VALFRE	Número	—	Valor do frete do produto.
VALLIQ	Número	Sim	Valor líquido final, já com os descontos.
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Requisição

curl -G https://api.upcampo.com.br/movimentacao \
  -H 'Authorization: Bearer $TOKEN' \
  --data-urlencode 'datmod_inicial=2023-06-01 09:00:00' \
  --data-urlencode 'status=Finalizado'

Corpo (body)

[
  {
    "ID_REFERENCIA": "2",
    "NUMERO": "0002",
    "DATA": "2024-4-27",
    "DATEMI": "2024-4-01",
    "CNPJCPF": "0123",
    "RAZSOC": "NOVO INTEGRACAO",
    "NOMFAN": "NOVO IN",
    "CHANFE": "5555.44444.5555.6666.9999.99999",
    "VALTOT": 200.50,
    "VALDES": 0,
    "VALFRE": 0,
    "VALLIQ": 200.50,
    "DELETADO": false,
    "ITENS": [
      {
        "ID_REFERENCIA": "A",
        "ID_PRODUTO_REFERENCIA": "1",
        "ID_LOCEST_REFERENCIA": "1010101",
        "QUANTIDADE": 40,
        "VALUNI": 2,
        "VALTOT": 40,
        "VALLIQ": 40
      }
    ]
  }
]

Retorno200

[
  {
    "TABELA": "CABECALHO",
    "ID_UPCAMPO": "86F44591-D8D7-465D-BB86-5EA461B63E7D",
    "ID_REFERENCIA": "2",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  },
  {
    "TABELA": "DETALHE",
    "ID_UPCAMPO": "E9A93574-C4BF-4DA7-8F23-E3D3E0FF816A",
    "ID_REFERENCIA": "A",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Transferência entre locais de estoque GETPOST

URL BASE + /transferencia

A transferência move saldo de um local de estoque para outro, sem nota fiscal — do barracão central para o barracão da unidade, por exemplo. O documento tem cabeçalho e itens.

Parâmetros do GET

Parâmetro	Obrigatório	Observação
data_inicial	Sim	Formato `AAAA-MM-DD` — ex.: `2024-08-19`. Janela máxima de 7 dias entre as duas.
data_final	Sim
status	—	`Finalizado` ou `Pendente`.
codigo	—
id_referencia	—
id_upcampo	—
id_local_origem	—
id_local_destino	—

Campos

Campo	Tipo	Obrigatório	Observação
Cabeçalho
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro.
DATA	String	Sim	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
ID_LOCESTORI_REFERENCIA	String	Sim	Local de estoque de origem, no ERP terceiro, mapeado na upCampo.
ID_LOCESTDES_REFERENCIA	String	Sim	Local de estoque de destino, no ERP terceiro, mapeado na upCampo.
NUMEXT	String	—	Código ou número do documento no ERP terceiro.
QUEMRECEBEU	String	—	Nome de quem recebeu.
QUEMENTREGOU	String	—	Nome de quem entregou.
NUMNF	String	—	Número da NF.
OBSERVACAO	String	—
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.
ITENS	Array	Sim	Os itens da transferência.
Itens
ID_REFERENCIA	String	—	Identificador do item no ERP terceiro.
ID_PRODUTO_REFERENCIA	String	Sim	Identificador do produto no ERP terceiro, mapeado na upCampo.
ID_LOTE_REFERENCIA	String	—	Identificador do lote no ERP terceiro, mapeado na upCampo.
QUANTIDADE	Número	Sim
VALUNI	Número	Sim
VALLIQ	Número	Sim
DELETADO	Boolean	—	Use `true` para enviar uma exclusão.

Documento finalizado não muda

Transferência já finalizada não pode ser alterada — o retorno vem com "MENSAGEM": "Documento finalizado não pode ser alterado". E a upCampo barra a operação que deixaria o saldo da origem negativo.

Corpo (body)

[
  {
    "ID_REFERENCIA": "21",
    "DATA": "2023-3-27",
    "ID_LOCESTORI_REFERENCIA": "1010101",
    "ID_LOCESTDES_REFERENCIA": "2010101",
    "NUMEXT": "0021",
    "QUEMENTREGOU": "José",
    "QUEMRECEBEU": "João",
    "NUMNF": "00158",
    "ITENS": [
      {
        "ID_REFERENCIA": "21_A",
        "ID_PRODUTO_REFERENCIA": "1",
        "QUANTIDADE": 5,
        "VALUNI": 2,
        "VALLIQ": 10
      }
    ]
  }
]

Retorno do POST200

[
  {
    "TABELA": "CABECALHO",
    "ID_UPCAMPO": "B674DF03-052C-427D-9CCD-FFA553F88D18",
    "ID_REFERENCIA": "21",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  },
  {
    "TABELA": "DETALHE",
    "ID_UPCAMPO": "F1692266-457D-4B86-A33C-3381F0F5FF56",
    "ID_REFERENCIA": "21_A",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Retorno do GET200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_TRANSFERENCIA_UPCAMPO": "1AA818E8-0B7C-44D2-81F0-7155AB00127C",
    "ID_REFERENCIA": "12345",
    "EXCLUIDO": false,
    "CODIGO": "0011",
    "NUMEXT": null,
    "DATA_MODIFICACAO": "2024-04-30T15:47:01.697",
    "DATASTRING": "30/04/2024",
    "DATA": "2024-04-30",
    "STATUS": "Finalizado",
    "USUARIO_NOME": "Admin",
    "ID_USUARIO_UPCAMPO": "0dab044a-1e1e-4333-a39b-879e891fa086",
    "OBSERVACAO": "OBSERVACAO",
    "NUMNF": "001",
    "ENTREGADOR": "CARLOS",
    "RECEBEDOR": "MARCOS",
    "LOCESTORI_DESCRICAO": "Algodoeira",
    "ID_LOCESTORI_UPCAMPO": "C02A3653-849B-4C3D-894E-FBFE4FFCF479",
    "ID_LOCESTORI_REFERENCIA": "1010101",
    "LOCESTDES_DESCRICAO": "Algodoeira",
    "ID_LOCESTDES_UPCAMPO": "C02A3653-849B-4C3D-894E-FBFE4FFCF479",
    "ID_LOCESTDES_REFERENCIA": "1010101",
    "itens": [
      {
        "ID_TRANSFERENCIA_DETALHE_UPCAMPO": "F090E396-1E96-4D49-80FE-655CAE2AB309",
        "ID_REFERENCIA_DETALHE": null,
        "EXCLUIDO_DETALHE": false,
        "PRODUTO_DESCRICAO": "Algodao em Pluma 01",
        "ID_PRODUTO_UPCAMPO": "D236201E-BACA-4D14-9D10-F4374B46D17A",
        "ID_PRODUTO_REFERENCIA": "1",
        "ID_LOTE_UPCAMPO": null,
        "ID_LOTE_REFERENCIA": null,
        "PRODUTO_UNIDADE": "KG - Quilograma",
        "PRODUTO_CODUNI": "KG",
        "QUANTIDADE": 6.000000
      }
    ]
  }
]

Inventário POST

URL BASE + /inventario

O inventário acerta o saldo de um produto num local de estoque: em vez de lançar entrada ou saída, informa-se qual é o saldo correto naquela data. Use na virada de safra e na conferência física do almoxarifado.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no ERP terceiro. Se a upCampo encontrar, é atualização; se não, é registro novo.
ID_PRODUTO_REFERENCIA	String	Sim*	Identificador do produto no ERP terceiro, mapeado na upCampo.
ID_PRODUTO_UPCAMPO	String	Sim*	Identificador do produto na upCampo — use quando `ID_PRODUTO_REFERENCIA` estiver nulo.
ID_LOTE_REFERENCIA	String	—	Identificador do lote no ERP terceiro, mapeado na upCampo.
ID_LOTE_UPCAMPO	String	—	Identificador do lote na upCampo, quando não houver a referência.
ID_LOCEST_REFERENCIA	String	Sim*	Identificador do local de estoque no ERP terceiro, mapeado na upCampo.
ID_LOCEST_UPCAMPO	String	Sim*	Identificador do local na upCampo — use quando `ID_LOCEST_REFERENCIA` estiver nulo.
DATA	String	—	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
SALDO	Número	Sim	Saldo do produto.
VALUNI	Número	—	Valor unitário do produto.
VALTOT	Número	—	Valor total do produto.

* Informe a referência ou o identificador da upCampo — um dos dois.

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "ID_PRODUTO_REFERENCIA": "1",
    "ID_LOCEST_REFERENCIA": "1010101",
    "DATA": "2023-02-01",
    "SALDO": 20.00,
    "VALUNI": "30.00",
    "VALTOT": "600.00"
  }
]

Retorno200

[
  {
    "TABELA": "INVENTARIO",
    "ID_UPCAMPO": "7E28F9F0-62BF-4C89-8D7F-84345CA5B183",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Saldo de estoque GET

URL BASE + /estoque

Devolve o saldo atual por produto e local de estoque — é assim que a upCampo controla estoque, e é por isso que o mesmo produto pode ter saldos diferentes em barracões diferentes.

Parâmetros

Parâmetro	Observação
id_locest_referencia	Filtra por local de estoque.
id_produto_referencia	Filtra por produto.

Campos

Campo	Tipo	Observação
ID_ESTOQUE_UPCAMPO	String	Identificador da linha de estoque na upCampo.
LOCEST_DESCRICAO	String	Descrição do local de estoque na upCampo.
ID_LOCEST_UPCAMPO	String	Identificador do local na upCampo.
ID_LOCEST_REFERENCIA	String	Identificador do local no ERP terceiro.
PRODUTO_DESCRICAO	String	Descrição do produto na upCampo.
ID_PRODUTO_UPCAMPO	String	Identificador do produto na upCampo.
ID_PRODUTO_REFERENCIA	String	Identificador do produto no ERP terceiro.
SALDO	Número	Saldo atual.

Requisição

curl 'https://api.upcampo.com.br/estoque?id_locest_referencia=38' \
  -H 'Authorization: Bearer $TOKEN'

Retorno200

[
  {
    "ID_ESTOQUE_UPCAMPO": "0F5D3D06-7BB1-4A2E-9A05-5D6E5F0C61A3",
    "LOCEST_DESCRICAO": "FUM - DIESEL",
    "ID_LOCEST_UPCAMPO": "23C7A375-B67B-42BC-ABD9-6577F075A26A",
    "ID_LOCEST_REFERENCIA": "38",
    "PRODUTO_DESCRICAO": "DIESEL S10",
    "ID_PRODUTO_UPCAMPO": "F44E08B3-4A0F-4A35-99AD-1E66418611D9",
    "ID_PRODUTO_REFERENCIA": "1201",
    "SALDO": 12450.000000
  }
]

Ordem de serviço agrícola — completa GET

URL BASE + /ordem_agricola_completa

A ordem de serviço é o documento que registra o que foi aplicado, em quais talhões e por quem. Esta rota devolve tudo em um objeto só: cabeçalho + produtos + talhões + execuções. É a escolha certa quando o ERP quer a ordem inteira em uma leitura.

O custo é rateado por área

A quantidade de cada produto é lançada para a ordem inteira (QUANTIDADE_TOTAL_PRODUTO) e distribuída entre os talhões conforme a área de cada um. Por isso a ordem traz a área total (ARETOT) e a área de cada talhão (AREA).

Parâmetros

Opção	Parâmetro	Observação
1	data_inicial + data_final	Formato `AAAA-MM-DD` — ex.: `2024-08-19`. Combinável com `id_tipati`, `id_tipati_referencia` e `status` (`Finalizado` ou `Pendente`).
2	codigo	Código da ordem na upCampo.
3	id_referencia	Identificador no sistema do parceiro.

Exemplo: ?data_inicial=2023-06-01&data_final=2023-06-30&status=Finalizado

Gravar a referência da ordem

Use POST /ordem_agricola_completaReferencia com id_upcampo, id_referencia e, opcionalmente, codSai — este último para quando o código gerado no sistema do parceiro é diferente do código da ordem na upCampo.

Campos

Campo	Tipo	Observação
Cabeçalho da ordem
ID_ORDSER_UPCAMPO	String	Identificador da ordem de serviço na upCampo.
ID_REFERENCIA	String	Identificador no ERP terceiro, mapeado no cadastro da upCampo.
CODIGO	String	Código ou número da ordem na upCampo.
SEQUENCIAL	Integer	Funciona como um identificador numérico, para parceiros que não conseguem trabalhar com identificador em texto.
DELETADO	Boolean
DATPRESTRING	String	Data prevista, no formato `dd/mm/aaaa`.
DATPRE	String	Data prevista, no formato `AAAA-MM-DD`.
DATFINSTRING	String	Data de finalização, no formato `dd/mm/aaaa`.
DATFIN	String	Data de finalização, no formato `AAAA-MM-DD`.
ARETOT	Número	Área total da ordem, em hectares.
AREEXE	Número	Área total executada, em hectares.
STATUS	String	`Pendente` ou `Finalizado`.
TIPAPL	String	Tipo de aplicação de defensivo: `Terrestre` ou `Aérea`.
USUARIO_NOME ID_USUARIO_UPCAMPO ID_USUARIO_REFERENCIA	String	Quem incluiu — nome, identificador na upCampo e identificador no ERP terceiro.
USUARIO_FINALIZOU_NOME ID_USUARIO_FINALIZOU_UPCAMPO ID_USUARIO_FINALIZOU_REFERENCIA	String	Quem finalizou — nome, identificador na upCampo e identificador no ERP terceiro.
TIPATI_DESCRICAO ID_TIPATI_UPCAMPO ID_TIPATI_REFERENCIA	String	Tipo da atividade.
IDERES_DESCRICAO ID_IDERES_UPCAMPO ID_IDERES_REFERENCIA	String	Identificação resumida, uma espécie de subgrupo do tipo de atividade.
EQUIPE_DESCRICAO ID_EQUIPE_UPCAMPO ID_EQUIPE_REFERENCIA	String	Equipe que executou.
SAFRA_DESCRICAO SAFRA_ID_UPCAMPO ID_SAFRA_REFERENCIA	String	Safra da ordem.
ID_CICLO_REFERENCIA	String	Identificador do ciclo no ERP terceiro.
Agrupamento — produtos
LOCEST_DESCRICAO ID_LOCEST_UPCAMPO ID_LOCEST_REFERENCIA	String	Local de estoque de onde o produto saiu.
PRODUTO_DESCRICAO ID_PRODUTO_UPCAMPO ID_PRODUTO_REFERENCIA	String	Produto aplicado.
LOTE_DESCRICAO ID_LOTE_UPCAMPO ID_LOTE_REFERENCIA	String	Lote, quando o produto for controlado por lote.
PRODUTO_UNIDADE	String	Unidade completa (código + descrição).
PRODUTO_CODUNI	String	Abreviação da unidade.
QUANTIDADE_TOTAL_PRODUTO	Número	Quantidade do item, bruta, sem divisão.
DOSE_INDIVIDUAL	Número	Dose do item, bruta, sem divisão.
Agrupamento — talhões
TALHAO_DESCRICAO ID_TALHAO_UPCAMPO ID_TALHAO_REFERENCIA	String	Talhão incluído na ordem.
TALHAO_SETOR	String
ID_SETOR_REFERENCIA	String	Identificador no ERP terceiro. Dica: se o ERP usa várias filiais e a upCampo não, faça o de/para aqui.
AREA	Número	Área em hectares daquele talhão na ordem.
VARIEDADE_DESCRICAO ID_VARIEDADE_UPCAMPO ID_VARIEDADE_REFERENCIA	String	Variedade plantada.
CULTURA_DESCRICAO ID_CULTURA_UPCAMPO ID_CULTURA_REFERENCIA	String	Cultura.
SAFRA_DESCRICAO ID_SAFRA_REFERENCIA	String	Safra do talhão.
ID_PLANTIO_SAFRA_UPCAMPO ID_PLANTIO_SAFRA_REFERENCIA	String	Plantio da safra correspondente.
Agrupamento — execuções
ID_EXECUCAO_UPCAMPO	String	Identificador interno da execução na upCampo.
DATASTRING	String	Data da execução, no formato `dd/mm/aaaa`.
DATA	String	Data da execução, no formato `AAAA-MM-DD`.
HORA_INICIO / MINUTO_INICIO	String	Início da execução.
HORA_FIM / MINUTO_FIM	String	Fim da execução.
AREA	Número	Área em hectares da execução.
EQUIPAMENTO_DESCRICAO ID_EQUIPAMENTO_UPCAMPO ID_EQUIPAMENTO_REFERENCIA	String	Equipamento usado.
LEIINI	Número	Leitura inicial (horímetro ou km).
LEIFIN	Número	Leitura final (horímetro ou km).
QUAHOR	Número	Quantidade de horas.
FUNCIONARIO_NOME ID_FUNCIONARIO_UPCAMPO ID_FUNCIONARIO_REFERENCIA	String	Funcionário que executou.
ID_FUNCIONARIOS_AGRUPADOS	String	Identificadores agrupados, quando mais de um funcionário participa da mesma execução — separados por ponto e vírgula.

Requisição

curl 'https://api.upcampo.com.br/ordem_agricola_completa?data_inicial=2023-06-01&data_final=2023-06-30&status=Finalizado' \
  -H 'Authorization: Bearer $TOKEN'

Retorno200

[
  {
    "ID_FILIAL": "DE319CA8-601F-4E68-978D-D0FB0DC27457",
    "ID_ORDSER_UPCAMPO": "io0wrnIjESTkkvAGkrlY",
    "CODIGO": "0570",
    "DATPRESTRING": "24/05/2023",
    "DATPRE": "2023-05-24",
    "DATFINSTRING": "24/05/2023",
    "DATFIN": "2023-05-24T00:00:00.000Z",
    "ARETOT": 142,
    "AREEXE": 142,
    "STATUS": "Finalizado",

    "ID_SAIDA_UPCAMPO": "0B94079D-8D3A-4FE2-B1F5-B0D36F3579BC",
    "ID_SAIDA_REFERENCIA": "11556",

    "LOCEST_DESCRICAO": "FUM - DEFENSIVOS",
    "ID_LOCEST_UPCAMPO": "B203B099-9AB2-4379-89FD-52D788E73F9C",
    "ID_LOCEST_REFERENCIA": "12",

    "PRODUTO_DESCRICAO": "BRAVONIL 720",
    "ID_PRODUTO_UPCAMPO": "BC8DC697-9673-4636-B78D-370926042403",
    "ID_PRODUTO_REFERENCIA": "330",
    "ID_LOTE_UPCAMPO": null,
    "ID_LOTE_REFERENCIA": null,
    "QUANTIDADE_PROPORCIONAL": 93.8,
    "QUANTIDADE_TOTAL_PRODUTO": 198.8,
    "DOSE_INDIVIDUAL": 1.4,

    "TALHAO_DESCRICAO": "16 - UNIAO",
    "ID_TALHAO_UPCAMPO": "CA7742B0-AA38-4A37-A77C-10F214AED03D",
    "ID_TALHAO_REFERENCIA": "1",
    "AREA": 67,

    "VARIEDADE_DESCRICAO": "FM 985 GLTP",
    "ID_VARIEDADE_UPCAMPO": "9D6D9741-AFEB-4405-BACD-4C7341EC8006",
    "ID_VARIEDADE_REFERENCIA": "1",

    "CULTURA_DESCRICAO": "ALGODAO",
    "ID_CULTURA_UPCAMPO": "5795CCB1-44FC-44B8-AAB9-0DBDD4182E68",
    "ID_CULTURA_REFERENCIA": "1",

    "SAFRA_DESCRICAO": "ALGODAO E MILHO 2023",
    "ID_SAFRA_REFERENCIA": "1",
    "ID_PLANTIO_SAFRA_UPCAMPO": "592D56A2-2A71-4DD0-953B-F3020A142B5B",
    "ID_PLANTIO_SAFRA_REFERENCIA": "1",

    "TIPATI_DESCRICAO": "Aplicação de defensivo",
    "ID_TIPATI_UPCAMPO": "8650A085-15E2-4877-A7DA-92A52D112463",
    "ID_TIPATI_REFERENCIA": "1",
    "IDERES": "FUNGICIDA + INSET",

    "EQUIPE_DESCRICAO": "UNIAO - APL TERRESTRE",
    "ID_EQUIPE_UPCAMPO": "938C2A4C-035E-478A-866C-B200B42300D9",
    "ID_EQUIPE_REFERENCIA": "1"
  }
]

Ordem de serviço — insumos / produto GET

URL BASE + /ordem_agricola_insumo

Devolve a ordem de serviço com o cabeçalho e três listas aninhadas: produtos, talhoes e execucoes. É a rota usada para levar a baixa de insumo da lavoura para o estoque do ERP.

Parâmetros

Opção	Parâmetro	Observação
1	datmod_inicial	Data de modificação inicial. Formato `AAAA-MM-DD HH:MM:SS` — ex.: `2024-03-15 07:00:00`. A hora é opcional; sem ela, vale a partir da meia-noite. Combinável com `data_inicial` + `data_final` — a data do documento, em `AAAA-MM-DD` —, `id_tipati`, `id_tipati_referencia` e `status`.
2	codigo	Código da ordem na upCampo.
3	id_referencia	Identificador no sistema do parceiro.

Exemplo: ?datmod_inicial=2023-06-01 09:00:00&status=Finalizado

Campos específicos desta rota

O cabeçalho é o mesmo da ordem completa. Acrescentam-se:

Campo	Tipo	Observação
EXCLUIDO	Boolean
CODIGO_SAIDA_UPCAMPO	String	Código da ordem de serviço mais a sequência única de talhão × produto.
ID_SAIDA_UPCAMPO	String	Identificador interno da saída na upCampo.
ID_SAIDA_REFERENCIA	String	Identificador da saída no ERP terceiro, mapeado na upCampo. Grave-o com `/ordem_agricola_insumoReferencia`.
QUANTIDADE_PROPORCIONAL	Número	Quantidade do item já dividida proporcionalmente pela área do talhão em relação à área total da ordem.
QUANTIDADE_TOTAL_PRODUTO	Número	Quantidade do item, bruta, sem divisão.
DOSE_INDIVIDUAL	Número	Dose do item, bruta, sem divisão.

Proporcional ou total?

QUANTIDADE_TOTAL_PRODUTO é o que saiu do estoque na ordem inteira. QUANTIDADE_PROPORCIONAL é a fatia daquele talhão. Some as proporcionais e você chega à total — não lance as duas.

Retorno200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_ORDSER_UPCAMPO": "11F66754-1A1A-469B-BC39-1F96C8EBA897",
    "CODIGO": "0632",
    "DATA_MODIFICACAO": "2023-06-29T17:14:30.363",
    "DATPRESTRING": "19/06/2023",
    "DATPRE": "2023-06-19",
    "DATFINSTRING": "19/06/2023",
    "DATFIN": "2023-06-19",
    "ARETOT": 652.000000,
    "AREEXE": 652.000000,
    "STATUS": "Finalizado",
    "TIPAPL": "Terrestre",
    "TIPATI_DESCRICAO": "Aplicação de defensivo",
    "ID_TIPATI_UPCAMPO": "FC35C6B4-6512-4F58-BEA2-CCAA6BFED487",
    "ID_TIPATI_REFERENCIA": "3",
    "IDERES_DESCRICAO": "INSETICIDA ",
    "ID_IDERES_UPCAMPO": "7FE2669B-2820-45E8-83E2-40B74851A7D3",
    "ID_IDERES_REFERENCIA": "55",
    "EQUIPE_DESCRICAO": "UNIAO - APL TERRESTRE",
    "ID_EQUIPE_UPCAMPO": "D0C6C6C4-B15B-49C3-817D-EE88ACFDF2B1",
    "ID_EQUIPE_REFERENCIA": "10",
    "produtos": [
      {
        "LOCEST_DESCRICAO": "FCO - DEFENSIVOS",
        "ID_LOCEST_UPCAMPO": "92F51139-05BA-4C62-99A7-7597587CCFD2",
        "ID_LOCEST_REFERENCIA": "103",
        "PRODUTO_DESCRICAO": "DISPERSE ULTRA",
        "ID_PRODUTO_UPCAMPO": "2FDA9A05-7002-4B27-A190-8E511531976D",
        "ID_PRODUTO_REFERENCIA": "609",
        "ID_LOTE_UPCAMPO": "null",
        "ID_LOTE_REFERENCIA": "null",
        "ARETOT": 652.0000,
        "QUANTIDADE_TOTAL_PRODUTO": 13.0400,
        "DOSE_INDIVIDUAL": 0.0200
      },
      {
        "LOCEST_DESCRICAO": "FCO - DEFENSIVOS",
        "ID_LOCEST_UPCAMPO": "92F51139-05BA-4C62-99A7-7597587CCFD2",
        "ID_LOCEST_REFERENCIA": "103",
        "PRODUTO_DESCRICAO": "MARSHAL",
        "ID_PRODUTO_UPCAMPO": "BDA4D865-784E-4B71-94E8-7BA69F53F433",
        "ID_PRODUTO_REFERENCIA": "666",
        "ID_LOTE_UPCAMPO": "null",
        "ID_LOTE_REFERENCIA": "null",
        "ARETOT": 652.0000,
        "QUANTIDADE_TOTAL_PRODUTO": 260.0000,
        "DOSE_INDIVIDUAL": 0.3988
      }
    ],
    "talhoes": [
      {
        "TALHAO_DESCRICAO": "18",
        "SETOR": "UNIAO",
        "ID_SETOR_REFERENCIA": "10",
        "ID_TALHAO_UPCAMPO": "D7DC95FD-ABB2-4FBF-9076-2A598809DE35",
        "ID_TALHAO_REFERENCIA": "130",
        "AREA": 101.000000,
        "VARIEDADE_DESCRICAO": "FM 985 GLTP",
        "ID_VARIEDADE_UPCAMPO": "CEF765F5-476D-45EA-AA19-1B4811492395",
        "ID_VARIEDADE_REFERENCIA": "18",
        "CULTURA_DESCRICAO": "ALGODAO",
        "ID_CULTURA_UPCAMPO": "E4B14FA0-807D-4A82-B9E3-A116BB72CA87",
        "ID_CULTURA_REFERENCIA": "1",
        "SAFRA_DESCRICAO": "Safra 01",
        "ID_SAFRA_UPCAMPO": "E95AD81A-E30A-4AF4-99D1-F21FE86997FD",
        "ID_SAFRA_REFERENCIA": "2",
        "ID_PLANTIO_SAFRA_UPCAMPO": "591E5517-848C-4135-B018-9C5E3C1F5831",
        "ID_PLANTIO_SAFRA_REFERENCIA": "null"
      }
    ],
    "execucoes": [
      {
        "ID_EXECUCAO_UPCAMPO": "9693EB90-CB9F-4E1B-ABC9-ACDFDA75D9F8_DEF63419-DD18-4D7E-81C5-9578ACD5787A",
        "DATASTRING": "19/06/2023",
        "DATA": "2023-06-19",
        "AREA": 67.0000000,
        "LEIINI": 0.0,
        "LEIFIN": 0.0,
        "QUAHOR": 0.0000,
        "EQUIPAMENTO_DESCRICAO": "0235 - 0235 - PULVERIZADOR M4030 - JOHN DEER - 035",
        "ID_EQUIPAMENTO_UPCAMPO": "C0E6E02A-06A2-47EF-A9ED-EC15352053D0",
        "ID_EQUIPAMENTO_REFERENCIA": "9",
        "FUNCIONARIO_NOME": "OPERADOR 01",
        "ID_FUNCIONARIO_UPCAMPO": "297ACD8A-4241-4A70-A02B-2DED72A0E47E",
        "ID_FUNCIONARIO_REFERENCIA": "null",
        "USUARIO_NOME": "null",
        "ID_USUARIO_UPCAMPO": "null",
        "ID_USUARIO_REFERENCIA": "null"
      }
    ]
  }
]

Ordem de serviço — devoluções GET

URL BASE + /ordem_agricola_devolucao

Quando a ordem é finalizada, a quantidade realmente usada pode ser diferente da programada. Esta rota devolve essa diferença, para o ERP acertar o estoque dele: o que sobrou volta, o que faltou sai.

Os parâmetros são os mesmos da rota de insumos. O cabeçalho também.

Campos específicos

Campo	Tipo	Observação
QUANTIDADE_DIFERENCA	Número	Quantidade da diferença (quantidade original − quantidade alterada).
TIPO_DIFERENCA	String	`ENTRADA` — é uma devolução: precisa entrar no estoque. `SAÍDA` — é uma retirada a mais: precisa sair do estoque.
CODIGO_SAIDA_UPCAMPO	String	Código da ordem mais a sequência única de talhão × produto.
ID_SAIDA_UPCAMPO ID_SAIDA_REFERENCIA	String	Identificador da saída na upCampo e no ERP terceiro.

Leia o sinal, não só o número

QUANTIDADE_DIFERENCA vem sempre positiva; quem diz a direção é TIPO_DIFERENCA. Lançar tudo como entrada dobra o saldo.

Retorno200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_ORDSER_UPCAMPO": "FDDB3C4F-7C62-4A6B-8B7A-4845244AB9AF",
    "CODIGO": "00653",
    "DATA_MODIFICACAO": "2023-12-19T17:24:40.910Z",
    "DATPRESTRING": "19/12/2023",
    "DATPRE": "2023-12-19T00:00:00.000Z",
    "DATFINSTRING": "19/12/2023",
    "DATFIN": "2023-12-19T00:00:00.000Z",
    "ARETOT": 108,
    "AREEXE": 108,
    "STATUS": "Finalizado",
    "TIPAPL": "Terrestre",
    "USUARIO_NOME": "Admin",
    "ID_USUARIO_UPCAMPO": "0dab044a-1e1e-4333-a39b-879e891fa086",
    "ID_USUARIO_REFERENCIA": null,
    "USUARIO_FINALIZOU_NOME": "Admin",
    "ID_USUARIO_FINALIZOU_UPCAMPO": "0dab044a-1e1e-4333-a39b-879e891fa086",
    "ID_USUARIO_FINALIZOU_REFERENCIA": null,
    "TIPATI_DESCRICAO": "Aplicação de defensivo",
    "ID_TIPATI_UPCAMPO": "FC35C6B4-6512-4F58-BEA2-CCAA6BFED487",
    "ID_TIPATI_REFERENCIA": "3",
    "IDERES_DESCRICAO": "INSETICIDA ",
    "ID_IDERES_UPCAMPO": "7FE2669B-2820-45E8-83E2-40B74851A7D3",
    "ID_IDERES_REFERENCIA": "55",
    "EQUIPE_DESCRICAO": null,
    "ID_EQUIPE_UPCAMPO": null,
    "ID_EQUIPE_REFERENCIA": null,
    "CODIGO_SAIDA_UPCAMPO": "00653_1",
    "EXCLUIDO": false,
    "ID_SAIDA_UPCAMPO": "A7306BB0-AACA-4FB6-8455-D6E5DE9902F1",
    "ID_SAIDA_REFERENCIA": null,
    "LOCEST_DESCRICAO": "FUM - DEFENSIVOS",
    "ID_LOCEST_UPCAMPO": "E1E9D54F-535C-4715-83D3-D472A1E6ED5E",
    "ID_LOCEST_REFERENCIA": "40",
    "PRODUTO_DESCRICAO": "APRESA 1X20",
    "ID_PRODUTO_UPCAMPO": "8DA739BC-28F3-4021-8A3A-311C92E06EC7",
    "ID_PRODUTO_REFERENCIA": "9365",
    "ID_LOTE_UPCAMPO": null,
    "ID_LOTE_REFERENCIA": null,
    "QUANTIDADE_DIFERENCA": 10,
    "TIPO_DIFERENCA": "ENTRADA",
    "TALHAO_DESCRICAO": "A01",
    "SETOR": "CENTRO OESTE",
    "ID_SETOR_REFERENCIA": "1",
    "ID_TALHAO_UPCAMPO": "6CF450A4-00E7-47E0-BEE5-F83E713AEAEA",
    "ID_TALHAO_REFERENCIA": "198",
    "AREA": 108,
    "VARIEDADE_DESCRICAO": "TMG 44 B2RF",
    "ID_VARIEDADE_UPCAMPO": "D0FF4EA3-350D-440E-9264-4565CBCE0C57",
    "ID_VARIEDADE_REFERENCIA": "26",
    "CULTURA_DESCRICAO": "ALGODAO",
    "ID_CULTURA_UPCAMPO": "E4B14FA0-807D-4A82-B9E3-A116BB72CA87",
    "ID_CULTURA_REFERENCIA": "1",
    "SAFRA_DESCRICAO": "Safra 01",
    "ID_SAFRA_UPCAMPO": "E95AD81A-E30A-4AF4-99D1-F21FE86997FD",
    "ID_SAFRA_REFERENCIA": "2",
    "ID_PLANTIO_SAFRA_UPCAMPO": "551CBF6A-ADD7-4ACE-B9C8-C532FE3D2F71",
    "ID_PLANTIO_SAFRA_REFERENCIA": null
  }
]

Ordem de serviço — execuções GET

URL BASE + /ordem_agricola_execucao

Uma linha por execução: quem operou, com qual máquina, em qual talhão, quantas horas. É o apontamento de mão de obra e hora-máquina da ordem — a rota de insumos cuida do produto; esta, do trabalho.

Aceita datmod_inicial, além dos mesmos parâmetros das outras rotas de ordem.

Campos específicos

Campo	Tipo	Observação
ID_EXECUCAO_UPCAMPO	String	Identificador interno da execução na upCampo.
DATASTRING / DATA	String	Data da execução em `dd/mm/aaaa` e em `AAAA-MM-DD`.
HORA_INICIO / MINUTO_INICIO HORA_FIM / MINUTO_FIM	String	Início e fim da execução.
AREA	Número	Área em hectares da execução.
EQUIPAMENTO_DESCRICAO ID_EQUIPAMENTO_UPCAMPO ID_EQUIPAMENTO_REFERENCIA	String	Máquina usada.
IMPLEMENTO_DESCRICAO ID_IMPLEMENTO_UPCAMPO ID_IMPLEMENTO_REFERENCIA	String	Implemento acoplado.
LEIINI / LEIFIN	Número	Leitura inicial e final (horímetro ou km).
QUAHOR	Número	Quantidade de horas.
FUNCIONARIO_NOME ID_FUNCIONARIO_UPCAMPO ID_FUNCIONARIO_REFERENCIA	String	Funcionário que executou.
ID_FUNCIONARIOS_AGRUPADOS	String	Identificadores de mais de um funcionário na mesma execução, separados por ponto e vírgula.

O cabeçalho da ordem, o talhão, a variedade, a cultura, a safra e o plantio da safra vêm nos mesmos campos descritos na ordem completa.

Requisição

curl -G https://api.upcampo.com.br/ordem_agricola_execucao \
  -H 'Authorization: Bearer $TOKEN' \
  --data-urlencode 'datmod_inicial=2023-06-01 09:00:00'

Retorno200

[
  {
    "ID_FILIAL": "DE319CA8-601F-4E68-978D-D0FB0DC27457",
    "ID_ORDSER_UPCAMPO": "io0wrnIjESTkkvAGkrlY",
    "CODIGO": "0570",
    "DATPRESTRING": "24/05/2023",
    "DATPRE": "2023-05-24",
    "DATFINSTRING": "24/05/2023",
    "DATFIN": "2023-05-24T00:00:00.000Z",
    "ARETOT": 142,
    "AREEXE": 142,
    "STATUS": "Finalizado",

    "ID_EXECUCAO_UPCAMPO": "0B94079D-8D3A-4FE2-B1F5-B0D36F3579BC",
    "DATASTRING": "24/05/2023",
    "DATA": "2023-05-24",
    "HORA_INICIO": 7,
    "MINUTO": 30,
    "HORA_FIM": 8,
    "MINUTO_FIM": 30,

    "TALHAO_DESCRICAO": "16 - UNIAO",
    "ID_TALHAO_UPCAMPO": "CA7742B0-AA38-4A37-A77C-10F214AED03D",
    "ID_TALHAO_REFERENCIA": "1",

    "VARIEDADE_DESCRICAO": "FM 985 GLTP",
    "ID_VARIEDADE_UPCAMPO": "9D6D9741-AFEB-4405-BACD-4C7341EC8006",
    "ID_VARIEDADE_REFERENCIA": "1",

    "CULTURA_DESCRICAO": "ALGODAO",
    "ID_CULTURA_UPCAMPO": "5795CCB1-44FC-44B8-AAB9-0DBDD4182E68",
    "ID_CULTURA_REFERENCIA": "1",

    "SAFRA_DESCRICAO": "ALGODAO E MILHO 2023",
    "ID_SAFRA_REFERENCIA": "1",
    "ID_PLANTIO_SAFRA_UPCAMPO": "592D56A2-2A71-4DD0-953B-F3020A142B5B",
    "ID_PLANTIO_SAFRA_REFERENCIA": "1",

    "TIPATI_DESCRICAO": "Aplicação de defensivo",
    "ID_TIPATI_UPCAMPO": "8650A085-15E2-4877-A7DA-92A52D112463",
    "ID_TIPATI_REFERENCIA": "1",
    "IDERES": "FUNGICIDA + INSET",

    "EQUIPAMENTO_DESCRICAO": "UNIPORTE AGRIJACTO - 0008",
    "ID_EQUIPAMENTO_UPCAMPO": "ASD5889C-035E-478A-866C-B200B42300D9",
    "ID_EQUIPAMENTO_REFERENCIA": "1",
    "LEIINI": 10569,
    "LEIFIN": 10570,
    "QUAHOR": 1,

    "EQUIPE_DESCRICAO": "UNIAO - APL TERRESTRE",
    "ID_EQUIPE_UPCAMPO": "938C2A4C-035E-478A-866C-B200B42300D9",
    "ID_EQUIPE_REFERENCIA": "1",

    "FUNCIONARIO_NOME": "JOAO ALBERTO",
    "ID_FUNCIONARIO_UPCAMPO": "938C2A4C-035E-8897A-866C-B200B42300D9",
    "ID_FUNCIONARIO_REFERENCIA": "1",
    "ID_FUNCIONARIOS_AGRUPADOS": "938C2A4C-035E-8897A-866C-B200B42300D9;938C2A4C-035E-8897A-866C-B200B42300D9;"
  }
]

Abastecimento GET

URL BASE + /abastecimento

Cada linha é um abastecimento: quantos litros saíram de qual tanque para qual máquina, com a leitura do horímetro ou do hodômetro. É o que sustenta o controle de consumo da frota.

Parâmetros

Opção	Parâmetro	Observação
1	datmod_inicial	Data de modificação inicial. Formato `AAAA-MM-DD HH:MM:SS` — ex.: `2024-03-15 07:00:00`. A hora é opcional; sem ela, vale a partir da meia-noite. Combinável com: `data_inicial` + `data_final` — a data do documento, em `AAAA-MM-DD`; `status` (`Finalizado` ou `Pendente`); `id_locest` (upCampo) ou `id_locest_referencia`; `id_equipamento` (upCampo) ou `id_equipamento_referencia`.
2	numero	Número do abastecimento na upCampo.
3	id_referencia	Identificador no sistema do parceiro.

Exemplo: ?datmod_inicial=2023-06-01 09:00:00&id_equipamento_referencia=23

Campos

Campo	Tipo	Observação
ID_ABASTECIMENTO_UPCAMPO	String	Identificador do abastecimento na upCampo.
ID_REFERENCIA	String	Identificador no sistema do parceiro, gravado pela rota `/abastecimentoReferencia`.
NUMERO	String	Número na upCampo.
TICKET	String	Número adicional, para os casos em que há formulário impresso com numeração própria.
DATASTRING	String	Data no formato `dd/mm/aaaa`.
DATA	String	Data no formato `AAAA-MM-DD`.
LITROS	Número	Litros do abastecimento (quantidade).
LEIINI	Número	Leitura inicial da bomba (contador).
LEIFIN	Número	Leitura final da bomba (contador).
USUARIO_NOME ID_USUARIO_UPCAMPO ID_USUARIO_REFERENCIA	String	Quem incluiu o registro.
EQUIPAMENTO_DESCRICAO ID_EQUIPAMENTO_UPCAMPO ID_EQUIPAMENTO_REFERENCIA	String	Máquina abastecida.
FUNCIONARIO_NOME ID_FUNCIONARIO_UPCAMPO ID_FUNCIONARIO_REFERENCIA	String	Funcionário.
LOCEST_DESCRICAO ID_LOCEST_UPCAMPO ID_LOCEST_REFERENCIA	String	Local de estoque de onde saiu o combustível.
PRODUTO_DESCRICAO ID_PRODUTO_UPCAMPO ID_PRODUTO_REFERENCIA	String	Combustível abastecido.

Requisição

curl -G https://api.upcampo.com.br/abastecimento \
  -H 'Authorization: Bearer $TOKEN' \
  --data-urlencode 'datmod_inicial=2023-06-01 09:00:00' \
  --data-urlencode 'id_equipamento_referencia=23'

Retorno200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_ORDSER_UPCAMPO": "3D73BCF4-97E4-48D8-A349-35672F46AB4B",
    "NUMERO": "0001",
    "TICKET": "Ticket 20",
    "DATA_MODIFICACAO": "2023-10-26T14:00:22.793Z",
    "DATASTRING": "26/10/2023",
    "DATA": "2023-10-26T00:00:00.000Z",
    "LITROS": 50,
    "LEIINI": 0,
    "LEIFIN": 50,
    "USUARIO_NOME": "Admin",
    "ID_USUARIO_UPCAMPO": "0dab044a-1e1e-4333-a39b-879e891fa086",
    "ID_USUARIO_REFERENCIA": null,
    "EQUIPAMENTO_DESCRICAO": "0046 - 0046 - HERCULES 6.0 STARA - 0044",
    "ID_EQUIPAMENTO_UPCAMPO": "02CB7041-64DC-4E3F-99AB-C3ACC1E20016",
    "ID_EQUIPAMENTO_REFERENCIA": "54",
    "HORIMETRO": 4506,
    "FUNCIONARIO_NOME": null,
    "ID_FUNCIONARIO_UPCAMPO": null,
    "ID_FUNCIONARIO_REFERENCIA": null,
    "LOCEST_DESCRICAO": "FUM - DIESEL",
    "ID_LOCEST_UPCAMPO": "23C7A375-B67B-42BC-ABD9-6577F075A26A",
    "ID_LOCEST_REFERENCIA": "38",
    "PRODUTO_DESCRICAO": "DIESEL S10",
    "ID_PRODUTO_UPCAMPO": "F44E08B3-4A0F-4A35-99AD-1E66418611D9",
    "ID_PRODUTO_REFERENCIA": ""
  }
]

Fardos GET

URL BASE + /fardo?data_inicial=…&data_final=…

Cada fardo de algodão colhido no campo vira uma linha aqui, com o QR Code, o module id da colhedora, o peso da fazenda e o talhão de origem. É o que liga a colheita à algodoeira.

Se for para entrada na algodoeira, devolva o peso

Ao usar esta rota para a entrada na algodoeira, a condição é atualizar o peso pela rota /fardoPeso. Identificado o uso para algodoeira sem o retorno do peso, o acesso será bloqueado.

Filtros

Parâmetro	Campo filtrado	Observação
data_inicial data_final	DATA	Obrigatórios. Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
id_talhao_upcampo	ID_TALHAO_UPCAMPO	Identificador do talhão na upCampo.
id_talhao_referencia	ID_TALHAO_REFERENCIA	Identificador do talhão no sistema do cliente.
id_plantio_safra_referencia	ID_PLANTIO_SAFRA_REFERENCIA	Identificador do plantio de safra no sistema do cliente.
talhao_descricao	TALHAO_DESCRICAO	Comparação exata.
setor	SETOR	Comparação exata.
talhao_descricao_setor	TALHAO_DESCRICAO_SETOR	Descrição e setor concatenados; comparação exata.
talhao_finalizado	TALHAO_FINALIZADO	Aceita `true`/`false` ou `1`/`0`.

A comparação é exata, sem busca parcial: o valor precisa ser idêntico ao retornado pela rota.
Valores com espaço ou acento devem ser codificados na URL (espaço = %20).
Um valor inválido em talhao_finalizado é ignorado, e a consulta retorna sem esse filtro.
Para descobrir os identificadores e a descrição exata do talhão, use a rota /talhao, que aceita o parâmetro setor.

Campos

Campo	Tipo	Observação
ID_FARDO_UPCAMPO	String	Identificador na upCampo.
CODIGO	String	Código ou número na upCampo.
DATASTRING / DATA	String	`dd/mm/aaaa` e `AAAA-MM-DD`.
HORA / MINUTO	Número
QRCODE	String	QR Code do fardo.
MODULEID	String	Número único que a colhedora grava no fardo.
STATUS	String	`No campo` ou `Recolhido`.
PESFAZ	Número	Peso na fazenda — o da máquina, em kg.
PESALG	Número	Peso da algodoeira, depois de recolhido.
HECTARE	Número	Hectares que geraram este fardo.
LATITUDE / LONGITUDE	String	Onde o fardo foi gerado.
OBSERVACAO	String	Observação adicional do fardo.
ID_REFERENCIA	String	Identificador no sistema do parceiro.
TALHAO_DESCRICAO TALHAO_DESCRICAO_SETOR ID_TALHAO_UPCAMPO ID_TALHAO_REFERENCIA	String	Talhão de origem. `TALHAO_DESCRICAO_SETOR` é descrição + setor.
SETOR	String	Na maioria dos casos, é o nome da fazenda dentro do grupo.
ID_SETOR_REFERENCIA	String	Identificador no ERP terceiro. Dica: se o ERP usa várias filiais e a upCampo não, faça o de/para aqui.
VARIEDADE_DESCRICAO ID_VARIEDADE_UPCAMPO ID_VARIEDADE_REFERENCIA	String	Variedade colhida.
CULTURA_DESCRICAO ID_CULTURA_UPCAMPO ID_CULTURA_REFERENCIA	String	Cultura.
SAFRA_DESCRICAO ID_SAFRA_UPCAMPO ID_SAFRA_REFERENCIA	String	Safra.
ID_PLANTIO_SAFRA_UPCAMPO ID_PLANTIO_SAFRA_REFERENCIA	String	Plantio da safra correspondente.
TALHAO_FINALIZADO	Boolean	Se o talhão já foi finalizado.
EQUIPAMENTO_DESCRICAO ID_EQUIPAMENTO_UPCAMPO ID_EQUIPAMENTO_REFERENCIA	String	Colhedora.

Exemplos de chamada

/fardo?data_inicial=2024-08-19&data_final=2024-08-25&talhao_descricao=07&setor=CAMPINAS

/fardo?data_inicial=2024-08-19&data_final=2024-08-25&talhao_descricao_setor=07%20-%20CAMPINAS

/fardo?data_inicial=2024-08-19&data_final=2024-08-25&id_talhao_referencia=ABC123

/fardo?data_inicial=2024-08-19&data_final=2024-08-25&id_plantio_safra_referencia=XYZ789

/fardo?data_inicial=2024-08-19&data_final=2024-08-25&talhao_descricao_setor=07%20-%20CAMPINAS&talhao_finalizado=false

Retorno200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_FARDO_UPCAMPO": "D83E100A-DFDB-451A-B4BB-56ED09EA851C",
    "CODIGO": "1",
    "DATA": "2023-06-20",
    "DATASTRING": "20/06/2023",
    "HORA": 15,
    "MINUTO": 16,
    "QRCODE": "1234",
    "MODULEID": "456",
    "STATUS": "No campo",
    "PESFAZ": 800,
    "PESALG": null,
    "HECTARE": 0.5,
    "LATITUDE": 0,
    "LONGITUDE": 0,
    "OBSERVACAO": null,
    "ID_REFERENCIA": null,
    "TALHAO_DESCRICAO": "TH Teste 01",
    "TALHAO_SETOR": null,
    "ID_TALHAO_UPCAMPO": "7AB7EDAF-6560-4ABF-834D-7D53D2C4C8F2",
    "ID_TALHAO_REFERENCIA": "2",
    "VARIEDADE_DESCRICAO": null,
    "ID_VARIEDADE_UPCAMPO": null,
    "ID_VARIEDADE_REFERENCIA": null,
    "CULTURA_DESCRICAO": "Soja",
    "ID_CULTURA_UPCAMPO": "EC8A50F5-0B77-45FC-9242-70002C8D10E5",
    "ID_CULTURA_REFERENCIA": "1",
    "SAFRA_DESCRICAO": "Safra 01",
    "ID_SAFRA_REFERENCIA": "6",
    "ID_PLANTIO_SAFRA_UPCAMPO": "EBA7428C-9ECA-415D-9335-6B3B40AEF482",
    "ID_PLANTIO_SAFRA_REFERENCIA": null,
    "EQUIPAMENTO_DESCRICAO": null,
    "ID_EQUIPAMENTO_UPCAMPO": null,
    "ID_EQUIPAMENTO_REFERENCIA": null,
    "createdat": "2023-06-20T19:16:32.001Z"
  }
]

Incluir fardo POST

URL BASE + /fardo

Para incluir um fardo com o cadastro completo. Para atualizar somente a referência ou apenas o peso, use as rotas específicas: /fardoReferencia e /fardoPeso.

Campos

Campo	Tipo	Obrigatório	Observação
DATA	String	Sim	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
QRCODE	String	—	QR Code do fardo.
MODULEID	String	—	Número único que a colhedora grava no fardo.
STATUS	String	Sim	`No campo` ou `Recolhido`.
PESFAZ	Número	—	Peso na fazenda — o da máquina, em kg.
PESALG	Número	—	Peso da algodoeira, depois de recolhido.
HECTARE	Número	—	Hectares que geraram este fardo.
LATITUDE / LONGITUDE	String	—	Onde o fardo foi gerado.
OBSERVACAO	String	—	Observação adicional do fardo.
ID_REFERENCIA	String	Sim	Identificador no sistema do parceiro.
CONTEC	Boolean	Sim	Conferido pelo técnico.
ID_PLANTIO_SAFRA_REFERENCIA	String	Sim	Identificador no ERP terceiro. Este campo ou a combinação `ID_TALHAO_REFERENCIA` + `ID_VARIEDADE_REFERENCIA` + `ID_CULTURA_REFERENCIA` + `ID_SAFRA_REFERENCIA` é obrigatória.
ID_TALHAO_REFERENCIA	String	—	Identificador no ERP terceiro, mapeado na upCampo.
ID_VARIEDADE_REFERENCIA	String	—	Identificador no ERP terceiro, mapeado na upCampo.
ID_CULTURA_REFERENCIA	String	—	Identificador no ERP terceiro, mapeado na upCampo.
ID_SAFRA_REFERENCIA	String	—	Identificador no ERP terceiro, mapeado na upCampo.
ID_EQUIPAMENTO_REFERENCIA	String	—	Identificador no ERP terceiro, mapeado na upCampo.

Corpo (body)

[
  {
    "ID_PLANTIO_SAFRA_REFERENCIA": "12",
    "MODULEID": "MODULEID",
    "QRCODE": "QRCODE",
    "ID_REFERENCIA": "111",
    "LATITUDE": "1",
    "LONGITUDE": "2",
    "PESFAZ": 1100,
    "PESALG": 1500.6,
    "HECTARES": 0.5,
    "STATUS": "No campo",
    "DATA": "2023-7-03",
    "ID_EQUIPAMENTO_REFERENCIA": "1"
  }
]

Peso do fardo POST

URL BASE + /fardoPeso

É a rota que fecha o ciclo do algodão: a algodoeira pesa o fardo recolhido e devolve o PESALG para a upCampo. Sem isso, o campo fica só com o peso estimado da colhedora.

Devolver o peso é condição de acesso

Quem consome /fardo, /fardoEspecifico ou /romcol para entrada na algodoeira precisa atualizar o peso por aqui. Identificado o uso sem o retorno do peso, o acesso será bloqueado.

Campos

Campo	Tipo	Obrigatório	Observaç��o
ID_FARDO_UPCAMPO	String	Sim	Identificador do fardo na upCampo.
ID_REFERENCIA	String	Não	Identificador no sistema do parceiro.
PESALG	Número	Sim	Peso da algodoeira, depois de recolhido.
STATUS	String	Sim	`No campo` ou `Recolhido`.
DATA	String	Sim	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
ID_EQUIPAMENTO_REFERENCIA	String	Não	Identificador no ERP terceiro, mapeado na upCampo.
ID_LOCEST_REFERENCIA	String	Não	Identificador no ERP terceiro, mapeado na upCampo.
NUMCOL	String	Não	Número da coleta no ERP terceiro.

O corpo é um array — pode levar mais de um fardo por chamada.

Corpo (body)

[
  {
    "ID_FARDO_UPCAMPO": "D83E100A-DFDB-451A-B4BB-56ED09EA851C",
    "ID_REFERENCIA": "1",
    "PESALG": 1500.6,
    "STATUS": "Recolhido",
    "DATA": "2023-6-21",
    "ID_EQUIPAMENTO_REFERENCIA": "1",
    "PLACA": "JHW-5047",
    "ID_LOCEST_REFERENCIA": "1010101",
    "NUMCOL": "0059"
  }
]

Retorno200

[
  {
    "TABELA": "FARDO",
    "ID_UPCAMPO": "D83E100A-DFDB-451A-B4BB-56ED09EA851C",
    "ID_REFERENCIA": "1",
    "STATUS": "ALTERADO",
    "MENSAGEM": ""
  }
]

Fardo específico GET

URL BASE + /fardoEspecifico?qrcode=… | moduleid=… | codigo=… | id=…

Busca um fardo pela identificação lida na portaria da algodoeira. É a rota usada no momento em que o caminhão chega e alguém bipa o QR Code.

Um filtro por vez

O filtro é um destes: qrcode, moduleid, codigo ou id. Preenchendo mais de um, vale o último dessa lista; não preenchendo nenhum, nada é retornado.

Se for para entrada na algodoeira, devolva o peso

A condição é atualizar o peso por /fardoPeso. Sem isso, o acesso será bloqueado.

Os campos retornados são os mesmos da rota Fardos.

Requisição

curl 'https://api.upcampo.com.br/fardoEspecifico?qrcode=1234' \
  -H 'Authorization: Bearer $TOKEN'

Retorno200

[
  {
    "ID_FILIAL": "F8E34B7E-2054-4A97-9EE4-9D8BFC8C917F",
    "ID_FARDO_UPCAMPO": "D83E100A-DFDB-451A-B4BB-56ED09EA851C",
    "CODIGO": "1",
    "DATA": "2023-06-20",
    "DATASTRING": "20/06/2023",
    "HORA": 15,
    "MINUTO": 16,
    "QRCODE": "1234",
    "MODULEID": "456",
    "STATUS": "No campo",
    "PESFAZ": 800,
    "PESALG": null,
    "HECTARE": 0.5,
    "LATITUDE": 0,
    "LONGITUDE": 0,
    "OBSERVACAO": null,
    "ID_REFERENCIA": null,
    "TALHAO_DESCRICAO": "TH Teste 01",
    "TALHAO_SETOR": null,
    "ID_TALHAO_UPCAMPO": "7AB7EDAF-6560-4ABF-834D-7D53D2C4C8F2",
    "ID_TALHAO_REFERENCIA": "2",
    "CULTURA_DESCRICAO": "Soja",
    "ID_CULTURA_UPCAMPO": "EC8A50F5-0B77-45FC-9242-70002C8D10E5",
    "ID_CULTURA_REFERENCIA": "1",
    "SAFRA_DESCRICAO": "Safra 01",
    "ID_SAFRA_REFERENCIA": "6",
    "ID_PLANTIO_SAFRA_UPCAMPO": "EBA7428C-9ECA-415D-9335-6B3B40AEF482",
    "ID_PLANTIO_SAFRA_REFERENCIA": null,
    "createdat": "2023-06-20T19:16:32.001Z"
  }
]

Romaneio de colheita GET

URL BASE + /romcol?data_inicial=…&data_final=…

O romaneio de colheita é o documento que registra a pesagem e a classificação de cada carga que chega do talhão. Ele traz os três pesos da balança — bruto, tara e líquido —, os percentuais de classificação e o total líquido final, que é o saldo que entra no estoque e forma a produtividade do talhão.

Se for para entrada na algodoeira, devolva o peso

Ao usar esta rota para a entrada na algodoeira, a condição é atualizar o peso pela rota /fardoPeso. Identificado o uso sem o retorno do peso, o acesso será bloqueado.

Pesos e classificação

Campo	Tipo	Observação
PESBRU	Número	Peso bruto — primeiro peso, caminhão cheio, em kg. Obrigatório.
PESTAR	Número	Peso tara — segundo peso, caminhão vazio, em kg. Obrigatório.
PESLIQ	Número	Peso líquido inicial, sem classificação. Obrigatório.
Descontos — o mesmo trio para cada tipo
UMIPER / UMIDES / UMIDESKG	Número	Umidade: percentual medido, percentual de desconto aplicado (tabela de classificação) e desconto em kg já aplicado sobre o `PESLIQ`.
IMPPER / IMPDES / IMPDESKG	Número	Impureza.
AVAPER / AVADES / AVADESKG	Número	Avariado.
QUEPER / QUEDES / QUEDESKG	Número	Quebrado.
ARDPER / ARDDES / ARDDESKG	Número	Ardido.
ARMPER / ARMDES / ARMDESKG	Número	Armazenagem.
TOTDES	Número	Total de desconto, em kg.
TOTLIQ	Número	Total líquido final — o líquido após a classificação, já descontado. Obrigatório.

A classificação é medida na balança

Umidade, impureza, avariado, ardido e quebrado são medidos pelo classificador da fazenda, na própria balança. Cada fazenda habilita só os tipos que usa — tipo não habilitado não aparece no romaneio. Os percentuais de desconto saem das tabelas configuradas na safra, não do romaneio.

Demais campos

Campo	Tipo	Observação
ID_ROMCOL_UPCAMPO	String	Identificador na upCampo.
NUMERO	String	Código ou número na upCampo. Obrigatório.
NUMAUT	String	Número da autorização (opcional).
DATASTRING / DATA	String	`dd/mm/aaaa` e `AAAA-MM-DD`.
HORA / MINUTO	Número
OBSERVACAO	String	Observação adicional.
CULTURA_DESCRICAO ID_CULTURA_UPCAMPO ID_CULTURA_REFERENCIA	String	Cultura colhida.
SAFRA_DESCRICAO ID_SAFRA_UPCAMPO ID_SAFRA_REFERENCIA	String	Safra.
ID_PLANTIO_SAFRA_UPCAMPO ID_PLANTIO_SAFRA_REFERENCIA	String	Plantio da safra de origem da carga.
EQUIPAMENTO_DESCRICAO ID_EQUIPAMENTO_UPCAMPO ID_EQUIPAMENTO_REFERENCIA	String	Caminhão.
PLACA	String	Placa do caminhão.
MOTORISTA	String	Motorista do caminhão.
LOCEST_DESCRICAO ID_LOCEST_UPCAMPO ID_LOCEST_REFERENCIA	String	Local de estoque (armazém) de destino.
PRODUTO_DESCRICAO ID_PRODUTO_UPCAMPO ID_PRODUTO_REFERENCIA	String	Produto que entra no estoque — por exemplo `SOJA EM GRÃOS`.

Requisição

curl 'https://api.upcampo.com.br/romcol?data_inicial=2023-12-11&data_final=2023-12-17' \
  -H 'Authorization: Bearer $TOKEN'

Retorno200

[
  {
    "ID_FILIAL": "F23FBAF7-AB27-4D28-8B32-74240FB0833D",
    "ID_ROMCOL_UPCAMPO": "9ryejRKRhClBLcKTXwvx",
    "NUMERO": "4819",
    "DATA": "2023-12-12",
    "DATASTRING": "12/12/2023",
    "HORA": 8,
    "MINUTO": 42,
    "NUMAUT": "701",
    "PESBRU": 85700,
    "PESTAR": 27560,
    "PESLIQ": 58140,
    "UMIPER": 13.2,
    "UMIDES": 0,
    "UMIDESKG": 0,
    "IMPPER": 1.6,
    "IMPDES": 0,
    "IMPDESKG": 349,
    "AVAPER": 2,
    "AVADES": 0,
    "AVADESKG": 0,
    "QUEPER": 10,
    "QUEDES": 0,
    "QUEDESKG": 1163,
    "ARDPER": null,
    "ARDDES": null,
    "ARDDESKG": null,
    "ARMPER": null,
    "ARMDES": null,
    "ARMDESKG": null,
    "TOTDES": 1512,
    "TOTLIQ": 56628,
    "OBSERVACAO": null,
    "ID_REFERENCIA": null,
    "TALHAO_DESCRICAO": "22",
    "SETOR": "SANTA CLARA",
    "ID_SETOR_REFERENCIA": "8",
    "ID_TALHAO_UPCAMPO": "6B93B381-5D0A-4552-903C-AF1D2051D248",
    "ID_TALHAO_REFERENCIA": "74",
    "VARIEDADE_DESCRICAO": "TMG 2379 IPRO",
    "ID_VARIEDADE_UPCAMPO": "23537C7D-5720-4D2E-84D7-84FFA488703D",
    "ID_VARIEDADE_REFERENCIA": null,
    "CULTURA_DESCRICAO": "SOJA",
    "ID_CULTURA_UPCAMPO": "4A47936F-60EC-4724-BAC8-16ABD48C9C92",
    "ID_CULTURA_REFERENCIA": null,
    "SAFRA_DESCRICAO": "SOJA E BRAQUIARIA 2023-2024",
    "ID_SAFRA_REFERENCIA": null,
    "ID_PLANTIO_SAFRA_UPCAMPO": "07DF860F-83BF-4069-9598-A11FC3E4DD6B",
    "ID_PLANTIO_SAFRA_REFERENCIA": null,
    "EQUIPAMENTO_DESCRICAO": "ABC-1D23 - CAMINHAO SCANIA R540 - 0091",
    "ID_EQUIPAMENTO_UPCAMPO": "4E0B4070-50C2-4592-AC7B-ADA806842311",
    "ID_EQUIPAMENTO_REFERENCIA": null,
    "PLACA": null,
    "MOTORISTA": "JOSE CARLOS PEREIRA",
    "LOCEST_DESCRICAO": "ARMAZEM CENTRAL LTDA",
    "ID_LOCEST_UPCAMPO": "460E0265-66BB-4892-A1C1-9E392B1DE9A0",
    "ID_LOCEST_REFERENCIA": null,
    "PRODUTO_DESCRICAO": "SOJA EM GRÃOS",
    "ID_PRODUTO_UPCAMPO": "2E0F8AAA-E005-4410-9C37-7492866448CB",
    "ID_PRODUTO_REFERENCIA": null,
    "createdat": "2023-12-12T12:55:15.532Z"
  }
]

Incluir romaneio de colheita POST

URL BASE + /romcol

Para incluir o romaneio de colheita com o cadastro completo. Para atualizar apenas a classificação, use /romcolClassificacao.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no sistema do parceiro.
NUMERO	String	Sim	Código ou número na upCampo.
NUMAUT	String	—	Número da autorização.
DATA	String	—	Formato `AAAA-MM-DD` — ex.: `2024-08-19`.
HORA / MINUTO	Número	—
PESBRU	Número	Sim	Peso bruto — primeiro peso, caminhão cheio, em kg.
PESTAR	Número	Sim	Peso tara — segundo peso, caminhão vazio, em kg.
PESLIQ	Número	Sim	Peso líquido inicial, sem classificação.
OBSERVACAO	String	—	Observação adicional.
ID_PLANTIO_SAFRA_REFERENCIA	String	Sim	Identificador no ERP terceiro. Este campo ou a combinação `ID_TALHAO_REFERENCIA` + `ID_VARIEDADE_REFERENCIA` + `ID_CULTURA_REFERENCIA` + `ID_SAFRA_REFERENCIA` é obrigatória.
ID_TALHAO_REFERENCIA ID_VARIEDADE_REFERENCIA ID_CULTURA_REFERENCIA ID_SAFRA_REFERENCIA	String	—	Identificadores no ERP terceiro, mapeados na upCampo. Use quando não houver o plantio da safra.
ID_EQUIPAMENTO_REFERENCIA	String	Se não houver placa	Identificador do caminhão no ERP terceiro, mapeado na upCampo.
PLACA	String	Se não houver equipamento	Placa do caminhão.
MOTORISTA	String	—
ID_LOCEST_REFERENCIA	String	Sim	Identificador no ERP terceiro do local de estoque (armazém).
ID_PRODUTO_REFERENCIA	String	Sim	Identificador no ERP terceiro do produto que entra no estoque (soja, milho).
UMIPER … ARMDESKG	Número	—	Percentuais e descontos da classificação — mesmos campos descritos em Romaneio de colheita.
TOTLIQ	Número	No fim	Total líquido final. Obrigatório ao fim da operação: todo romaneio precisa ter classificação e algum valor em `TOTLIQ` — é esse saldo final que entra no estoque e nas médias de produtividade.

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "NUMERO": "4826",
    "DATA": "2023-12-13",
    "HORA": 8,
    "MINUTO": 42,
    "PESBRU": 85700,
    "PESTAR": 27560,
    "PESLIQ": 58140,
    "UMIPER": 13.2,
    "UMIDES": 0,
    "UMIDESKG": 0,
    "IMPPER": 1.6,
    "IMPDES": 0,
    "IMPDESKG": 349,
    "AVAPER": 2,
    "AVADES": 0,
    "AVADESKG": 0,
    "QUEPER": 10,
    "QUEDES": 0,
    "QUEDESKG": 1163,
    "ARDPER": null,
    "ARDDES": null,
    "ARDDESKG": null,
    "ARMPER": null,
    "ARMDES": null,
    "ARMDESKG": null,
    "TOTDES": 1512,
    "TOTLIQ": 56628,
    "OBSERVACAO": null,
    "SETOR": "SANTA CLARA",
    "ID_SETOR_REFERENCIA": "8",
    "ID_TALHAO_REFERENCIA": "74",
    "ID_VARIEDADE_REFERENCIA": "1",
    "ID_CULTURA_REFERENCIA": "1",
    "ID_SAFRA_REFERENCIA": "1",
    "ID_PLANTIO_SAFRA_REFERENCIA": "1",
    "ID_EQUIPAMENTO_REFERENCIA": "1",
    "ID_LOCEST_REFERENCIA": "1",
    "ID_PRODUTO_REFERENCIA": "1",
    "PLACA": null,
    "MOTORISTA": "JOSE CARLOS PEREIRA"
  }
]

Retorno200

[
  {
    "TABELA": "ROMCOL",
    "ID_UPCAMPO": "9ryejRKRhClBLcKTXwvx",
    "ID_REFERENCIA": "1",
    "STATUS": "INCLUIDO",
    "MENSAGEM": ""
  }
]

Classificação do romaneio POST

URL BASE + /romcolClassificacao

Para incluir ou atualizar só a classificação de um romaneio já existente — o caso típico de quando a carga é pesada primeiro e classificada depois.

Campos

Campo	Tipo	Obrigatório	Observação
ID_REFERENCIA	String	Sim	Identificador no sistema do parceiro.
ID_ROMCOL_UPCAMPO	String	—	Identificador do romaneio na upCampo.
UMIPER / UMIDES / UMIDESKG	Número	—	Umidade: percentual medido, percentual de desconto e desconto em kg.
IMPPER / IMPDES / IMPDESKG	Número	—	Impureza.
AVAPER / AVADES / AVADESKG	Número	—	Avariado.
QUEPER / QUEDES / QUEDESKG	Número	—	Quebrado.
ARDPER / ARDDES / ARDDESKG	Número	—	Ardido.
ARMPER / ARMDES / ARMDESKG	Número	—	Armazenagem.
TOTDES / TOTLIQ	Número	—	Total de desconto e total líquido final.

Corpo (body)

[
  {
    "ID_REFERENCIA": "1",
    "ID_ROMCOL_UPCAMPO": "9ryejRKRhClBLcKTXwvx",
    "NUMERO": "4826",
    "DATA": "2023-12-13",
    "HORA": 8,
    "MINUTO": 42,
    "UMIPER": 13.2,
    "UMIDES": 0,
    "UMIDESKG": 0,
    "IMPPER": 1.6,
    "IMPDES": 0,
    "IMPDESKG": 349,
    "AVAPER": 2,
    "AVADES": 0,
    "AVADESKG": 0,
    "QUEPER": 10,
    "QUEDES": 0,
    "QUEDESKG": 1163,
    "ARDPER": null,
    "ARDDES": null,
    "ARDDESKG": null,
    "ARMPER": null,
    "ARMDES": null,
    "ARMDESKG": null,
    "TOTDES": 1512,
    "TOTLIQ": 56628
  }
]

Retorno200

[
  {
    "TABELA": "ROMCOL",
    "ID_UPCAMPO": "9ryejRKRhClBLcKTXwvx",
    "ID_REFERENCIA": "1",
    "STATUS": "ALTERADO",
    "MENSAGEM": ""
  }
]

Endpoints sob liberação

Estes endpoints constam do catálogo de integração, mas não estão liberados por padrão e não têm exemplo de retorno publicado. Procure a equipe da upCampo para solicitar o acesso e receber o contrato de campos.

Título	Rota	Parâmetros	Área
Pragas	/praga	Nenhum	Lavoura
Levantamentos	/levantamento	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias) `id_safra` (obrigatório) `id_plantio_safra` (opcional)	Lavoura
Coleta de informações climáticas	/coleta_climatica	`data_inicial` e `data_final` (obrigatórios, janela de 7 dias)	Lavoura
Classificação de equipamento	/classificacao_equipamento	Nenhum	Frota

Precisa de um endpoint que não está aqui?

Teoricamente é possível criar endpoint para qualquer tabela da plataforma. Fale com a equipe da upCampo dizendo qual dado você precisa ler ou gravar e para quê — a liberação é analisada caso a caso.

❓ Perguntas frequentes

Como faço a autenticação na API da upCampo?

Envie um POST para https://api.upcampo.com.br/autenticar com um JSON contendo client_id, client_secret, audience e grant_type. A upCampo entrega esse arquivo de credenciais pronto ao parceiro. O retorno traz um bearer token válido por 24 horas, que deve ir no cabeçalho Authorization de todas as chamadas seguintes.

Preciso gerar um token novo a cada chamada?

Não. Use o mesmo token até ele expirar. Gerar um token por requisição sobrecarrega a geração de token e o acesso é bloqueado temporariamente. O prazo atual é de 24 horas, gravado dentro do próprio token (no campo exp do JWT) — o corpo da resposta traz só access_token e token_type.

E o limite é aplicado de verdade: são no máximo 10 tentativas de autenticação a cada 15 minutos por client_id; passando disso, a API responde 429 com o cabeçalho Retry-After indicando em quantos segundos o acesso volta.

Como a API sabe de qual empresa e de qual fazenda são os dados?

O identificador da empresa e o da fazenda ficam fixados internamente na API quando o Client ID e o Client Secret são liberados. Cada endpoint retorna somente dados daquela empresa e daquela fazenda — não existe parâmetro para trocar isso na chamada. Por isso cada fazenda exige um par de credenciais próprio.

Para que serve o campo ID_REFERENCIA?

É a coluna onde fica o identificador do registro no sistema do parceiro, presente em todas as tabelas da upCampo. Ao receber um POST, a upCampo procura um registro com aquele ID_REFERENCIA: se não achar, é inserção; se achar, é atualização. E todo GET devolve esse campo, o que permite ao ERP reconhecer os próprios registros.

Como envio uma exclusão pela API?

Envie o registro com o atributo DELETADO igual a true. Não existe verbo DELETE: a exclusão é lógica e vai no mesmo POST do cadastro.

Como puxar só o que mudou desde a última consulta?

Use o parâmetro datmod_inicial com a data e a hora da consulta anterior. Toda vez que um usuário cria ou altera um registro na upCampo, a data de modificação é atualizada. Guarde a data de cada consulta e use-a na consulta seguinte para receber apenas os registros alterados depois dela.

Por que a consulta por período só aceita sete dias?

Nas rotas de movimento — movimentação, transferência, ordem de serviço, levantamento e coleta climática — a janela entre data_inicial e data_final é de no máximo sete dias, para manter o tempo de resposta. Para carga histórica, faça várias chamadas em janelas seguidas.

O que significa cada STATUS do retorno de um POST?

INCLUIDO quer dizer que o registro era novo e foi criado; ALTERADO, que já existia e foi atualizado; ERRO, que ele foi barrado — e aí o motivo vem no campo MENSAGEM. Em documentos com cabeçalho e itens, basta uma linha com ERRO para o documento inteiro não ser gravado.

Qual endpoint devolve os fardos de algodão colhidos?

GET /fardo, com data_inicial e data_final obrigatórios, devolve os fardos com QR Code, module id, peso da fazenda, hectares e talhão de origem. Para buscar um fardo específico na portaria da algodoeira, use GET /fardoEspecifico com qrcode, moduleid, codigo ou id. Quem usa essas rotas para a entrada na algodoeira precisa devolver o peso por POST /fardoPeso.

Existe uma especificação da API legível por máquina?

Sim. A especificação OpenAPI 3.1 está em suporte.upcampo.com.br/api/openapi.json e cobre todos os endpoints, parâmetros, corpos e retornos documentados. Ela pode ser importada no Postman, no Insomnia, no Swagger UI ou em geradores de cliente.

Finalização

Entendemos que integração é essencial para que nosso público-alvo — os clientes — tenha melhor aproveitamento de qualquer tecnologia; afinal, ele é o dono dos dados e a razão de todo o nosso trabalho.

Por isso estamos sempre à disposição para analisar e efetuar mudanças na integração que beneficiem nossos clientes e parceiros. Para dúvidas, procure a equipe da upCampo.

Abraços da equipe upCampo.