MEU RADAR AGRO

API de preços

Guia de integração · atualizado em 19 de setembro de 2026

Este documento é para o desenvolvedor que vai ligar um sistema à nossa base de preços. Ele cobre autenticação, os endpoints, o formato das respostas e — a parte que mais economiza tempo — o que cada campo significa e como não tirar a conclusão errada dele.

Em cinco minutos

Você recebeu uma chave parecida com rd_KdXFGuPHco7f…. Ela vai no cabeçalho Authorization:

curl -H "Authorization: Bearer SUA_CHAVE" \
  "https://www.meuradaragro.com/api/v1"

Essa primeira chamada devolve o que a sua chave comprou, a cota do dia e a documentação viva dos parâmetros. É o melhor lugar para começar e para voltar quando algo der 403.

A chave é secreta e identifica você. Chame sempre a partir do seu servidor, nunca do navegador ou do app do celular: uma chave dentro de bundle JavaScript ou de APK é uma chave pública, e o consumo passa a ser seu. Se ela vazar, avise que revogamos na hora — revogação é imediata e não depende de publicação de versão nova.

Autenticação e limites

Item	Como funciona
Cabeçalho	`Authorization: Bearer <chave>`. Sem ele, `401`.
Camadas	Cada chave compra camadas específicas (hoje: `combustivel`). Pedir rota de camada não contratada devolve `403` com a lista do que a sua chave inclui.
Cota	Por dia, definida em contrato. Ao estourar, `429` com `libera_em` dizendo quando reabre. A cota vira à meia-noite UTC.
Expiração	A chave pode ter prazo. Depois dele, `401` com `expirou_em`.

Camada Combustível

Responde de quem comprar mais barato numa praça, por produto e por tipo de fornecedor. Não é média de mercado: é uma lista ordenada de fornecedores concretos, com CNPJ.

GET /api/v1/combustivel/ranking

Parâmetro	Obrigatório	Valores
`produto`	sim	`diesel_s10`, `diesel_s10_aditivado`, `diesel_s500`, `gasolina_comum`, `gasolina_aditivada`, `etanol`, `arla`
`cidade`	sim	Nome da praça. Aceita com ou sem acento — normalizamos do nosso lado.
`uf`	não	Padrão `MT`.
`recorte`	não	`fazenda`, `posto`, `trr`, `todos` (padrão). Ver abaixo — é o parâmetro que mais muda a resposta.
`janela`	não	Dias de apuração. Padrão 7, máximo 30.

O recorte não é um filtro cosmético

Combustível se compra por dois canais diferentes, e o mesmo produto tem preço diferente em cada um:

recorte	Quem é	Para quem serve
`fazenda`	TRR e distribuidoras	Quem tem tanque na sede e recebe o combustível entregue.
`posto`	Revenda varejista (bomba)	Quem abastece o veículo na rota.
`trr`	Só TRR, sem distribuidora	Quem compra só de transportador revendedor retalhista.

Escolher o recorte errado dá um número plausível e inútil. Um produtor rural não abastece na bomba, e um caminhoneiro não consegue comprar de uma distribuidora. Se você mostrar a lista errada, ela vai parecer correta — os preços são todos reais — e vai apontar para um fornecedor que o seu usuário não pode usar.

Exemplo

GET /api/v1/combustivel/ranking
      ?produto=diesel_s10
      &cidade=Alta Floresta
      &uf=MT
      &recorte=fazenda

{
  "ok": true,
  "cobertura": {
    "cidade": "Alta Floresta", "uf": "MT",
    "produto": "diesel_s10", "produto_rotulo": "Diesel S10",
    "unidade": "l", "janela_dias": 7,
    "recorte": "fazenda", "recorte_rotulo": "Entrega na fazenda",
    "postos": 5,
    "fora_do_recorte": 40,
    "fornecedores_por_tipo": { "posto": 40, "trr": 3, "distribuidora": 2 },
    "notas": 166,
    "preco_min": 5.965, "preco_max": 6.52, "spread_pct": 9.3,
    "apurado_ate": "2026-08-19"
  },
  "fornecedores": [
    {
      "posicao": 1,
      "fornecedor": "TRR EXEMPLO LTDA",
      "razao_social": "TRR EXEMPLO COMERCIO DE COMBUSTIVEIS LTDA",
      "cnpj": "00000000000191",
      "tipo": "trr",
      "tipo_rotulo": "TRR — entrega no tanque do cliente",
      "endereco": "RODOVIA BR-163, KM 112, ZONA RURAL",
      "cep": "78580000",
      "lat": -9.876, "lng": -56.086,
      "precisao_local": "cep",
      "preco_mediana": 6.29,
      "preco_ultima_nota": 6.35,
      "ultima_venda_em": "2026-08-19",
      "notas": 7,
      "preco_min": 6.20, "preco_max": 6.39
    }
  ],
  "natureza": "nota fiscal de venda efetivamente emitida, preço por litro praticado"
}

Os campos que exigem cuidado

Estes quatro respondem perguntas diferentes. Lidos isoladamente, cada um pode levar a uma conclusão errada.

preco_mediana × preco_ultima_nota

Mandamos os dois de propósito, em vez de escolher por você:

preco_mediana — mediana das notas daquele fornecedor na janela. Resiste à venda atípica (o granel, o cliente com desconto), mas atrasa quando o fornecedor acabou de reajustar.
preco_ultima_nota — a venda mais recente vista. É o número mais próximo do preço de hoje, e é exatamente o que uma única venda estranha desloca.

Se o seu produto é "quanto custa agora", use a última nota e mostre a data. Se é "quem é consistentemente mais barato", use a mediana.

notas

Quantas notas fiscais sustentam aquela mediana. Um fornecedor com 1 nota e um com 40 aparecem iguais na lista e não são iguais. Recomendamos exibir esse número, ou ao menos marcar visualmente as posições com poucas notas — sem isso, o seu usuário trata uma observação isolada como preço apurado.

tipo

posto, trr, distribuidora, refino, outro — ou null.

null significa "ainda não classificamos este CNPJ", e não "não é nenhum desses". Esses fornecedores continuam aparecendo na lista, de propósito: sumir com um fornecedor legítimo é um erro invisível, e preferimos o erro que você consegue ver. Trate null como "desconhecido", nunca como "irrelevante".

natureza

De onde vem o preço daquele fornecedor:

Valor	O que é
`nota_fiscal`	Venda faturada — houve comprador, volume e o desconto de quem negocia.
`pesquisa`	Preço afixado na bomba, observado em levantamento oficial de campo. É o preço em vigor, mas ninguém abasteceu naquele registro.

Nunca misturamos as duas numa média. Cada fornecedor da lista traz uma natureza só, e a nota fiscal ganha quando existe para ele. Duas linhas vizinhas podem ter naturezas diferentes — por isso o campo vai em cada linha, e fornecedores_por_natureza resume a praça inteira.

Isso importa na prática: o canal de entrega na fazenda (TRR) só existe em nota fiscal — o levantamento de campo cobre revenda de bomba, não quem entrega no tanque. Uma praça que aparece só com pesquisa responde onde abastecer na estrada, não de quem comprar para a sede.

precisao_local

Valor	O que a coordenada promete
`endereco`	Casou rua e número — precisão de porta.
`cep`	Caiu para o CEP — precisão de bairro.
`null`	Não geocodificado. `lat`/`lng` vêm nulos.

Não trace rota até uma coordenada de cep. Ela leva o motorista a alguns quarteirões do fornecedor. Posto e TRR de beira de estrada quase sempre caem nesse caso, justamente por não terem número de rua mapeado. Para navegação, use o endereço em texto; a coordenada serve para desenhar no mapa e ordenar por distância aproximada.

fora_do_recorte

Quantos fornecedores da praça o seu recorte deixou de fora. É o que distingue "esta praça só tem 2 TRR" de "eu filtrei 40 postos". Sem ele, uma lista curta parece escassez de mercado quando é só o seu próprio filtro.

GET /api/v1/combustivel/mais-barato-por-cidade

É a outra pergunta. O ranking responde “de quem eu compro nesta cidade” — é do gestor de frota que já sabe onde abastece. Esta responde “qual cidade está mais barata”, uma linha por município com o fornecedor campeão de cada um: é de quem escolhe a rota, ou opera em várias praças e precisa decidir para onde mandar o caminhão.

GET /api/v1/combustivel/mais-barato-por-cidade
      ?produto=gasolina_comum
      &uf=MT
      &recorte=posto
      &janela=30

Parâmetro	Obrigatório	O que faz
`produto`	sim	um dos produtos rankeáveis
`uf`	não	padrão `MT`
`cidades`	não	lista separada por vírgula, no máximo 40. Sem ela, todas as praças da UF
`recorte`	não	`fazenda`, `posto`, `trr` ou `todos`
`janela`	não	dias, padrão 7, máximo 30

folga — o número que decide

Cada linha traz folga e folga_pct: quanto o campeão está abaixo da mediana da própria praça. É o que separa oportunidade de preço de mercado — um posto a R$ 5,84 num município onde a mediana é R$ 7,10 é oportunidade; o mesmo R$ 5,84 onde a mediana é R$ 5,90 é só o preço dali.

Praça com um fornecedor só vem com folga: null, e não zero. Ali o campeão é igual à mediana por construção — não há com o que comparar. Um zero seria lido como “não há oportunidade”, que é uma afirmação que não podemos fazer com um fornecedor só. O campo fornecedores vem em toda linha para você poder descartá-la.

natureza, por fornecedor

O campeão de cada cidade traz a própria natureza: nota_fiscal é venda faturada, pesquisa é preço afixado na bomba. Duas cidades vizinhas na mesma resposta podem ter naturezas diferentes, e isso muda o que o número significa. Nunca misturamos as duas no mesmo fornecedor.

GET /api/v1/combustivel/cobertura

Onde a API enxerga hoje, por praça e produto, com quantidade de fornecedores e a data do dado mais recente.

Chame esta rota para montar o seletor de cidade do seu app. A alternativa — chumbar no código a lista que combinamos por e-mail — fica errada no dia em que ligarmos uma praça nova, e ninguém percebe.

{
  "ok": true,
  "janela_dias": 7,
  "pracas": [
    {
      "cidade": "Alta Floresta", "uf": "MT",
      "produtos": [
        { "produto": "diesel_s10", "rotulo": "Diesel S10",
          "postos": 12, "notas": 40, "apurado_ate": "2026-08-19" }
      ]
    }
  ]
}

Erros

Código	Significa	O que fazer
`401`	Chave ausente, inválida, revogada ou expirada.	Conferir o cabeçalho. Se estava funcionando, fale conosco.
`403`	A camada não está no seu contrato, ou o contrato está inativo.	O corpo traz `camadas_da_chave`.
`400`	Parâmetro faltando ou inválido.	O corpo lista os valores aceitos.
`404`	Não há apuração para essa combinação.	Ver abaixo — este não é um erro comum.
`429`	Cota diária atingida.	`libera_em` diz quando reabre. Não faça retry em laço.

O 404 é informativo, não um defeito. Devolvemos 404 com motivo e o bloco cobertura em vez de 200 com lista vazia — porque "não medimos nesta praça" e "não há fornecedor barato aqui" levam a decisões opostas, e uma lista vazia não distingue as duas. Repasse o motivo ao seu usuário em vez de mostrar uma tela em branco:

praca_ou_produto_fora_da_cobertura — não coletamos ali (ainda).
recorte_sem_fornecedor — coletamos, mas o recorte pedido não tem ninguém. fornecedores_por_tipo mostra o que existe.

Boas práticas de integração

Cache de 1 a 6 horas. Preço de combustível muda por dia, não por minuto. Consultar a cada carregamento de tela gasta a sua cota sem melhorar a resposta.
Mostre sempre a data. ultima_venda_em e apurado_ate existem para aparecer na tela. Preço sem data envelhece em silêncio, e combustível envelhece rápido.
Trate a praça vazia com texto, não com tela em branco.
Não faça retry em laço no 429. Respeite libera_em.
Agrupe por CNPJ, nunca por nome. Se você reprocessar nossos dados: o mesmo nome fantasia aparece em CNPJs diferentes, e o mesmo CNPJ aparece com nomes diferentes. Nós já agrupamos por CNPJ — mantenha assim.

Sobre o dado

Os preços vêm de notas fiscais efetivamente emitidas — venda que aconteceu, não tabela de fábrica, anúncio ou estimativa — e, onde a nota não alcança, de levantamento oficial de campo do preço de bomba. As duas naturezas são declaradas linha a linha e nunca somadas na mesma média.

Informamos a natureza do preço e a data. Não informamos de qual portal o dado foi captado, e isso vale para todos os clientes, sem exceção.

O que você não pode fazer com o dado. A chave dá acesso de consulta para o uso combinado em contrato. Ela não autoriza revenda do dado bruto, redistribuição a terceiros, nem reconstituição da base por varredura sistemática dos endpoints. O consumo de cada chave é registrado.

Suporte

Dúvida de integração, chave comprometida ou praça nova: contato@meuradaragro.com. Ao relatar um problema, mande a URL chamada, o código de resposta e o prefixo da chave (os primeiros caracteres, tipo rd_KdXFGuPH) — nunca a chave inteira.