Buscar Produtividade por CAR e Cultura

Descrição: Busca dados de produtividade agrícola por Cadastro Ambiental Rural (CAR) filtrados por tipo de cultura específica.

Endpoint

GET/api/v1/integration/productivity/{car}/cultures/{culture}

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
car	Cadastro Ambiental Rural	String	Sim	Código CAR válido
culture	Tipo de cultura agrícola	String (Enum)	Sim	Valores: SOY, CORN, SUGAR_CANE, RICE, COTTON, COFFEE, CITRUS, PALM
harvest	Safra	String	Sim	Identificador da safra
source	Fonte dos dados	String (Enum)	Não	Valores: MERX (padrão), MAPBIOMAS
excludeSmallerAreas	Excluir áreas menores	Boolean	Não	Padrão: true
includeGeoJson	Incluir geometria na resposta	Boolean	Não	Padrão: false

Exemplo de Requisição

cURL

curl -X GET \
  -H "Authorization: {SUA_API_KEY}" \
  "https://api.merx.tech/api/v1/integration/productivity/MT-5107909-XXXXXXXXXXXXXXXXXXXXXXXX/cultures/SOY?harvest=2022%2F2023&source=MERX"

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String car = "MT-5107909-XXXXXXXXXXXXXXXXXXXXXXXX";
String culture = "SOY";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/productivity/" + car + "/cultures/" + culture + "?harvest=2022%2F2023&source=MERX"))
    .header("Authorization", "{SUA_API_KEY}")
    .GET()
    .build();

HttpClient client = HttpClient.newHttpClient();
try {
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
} catch (Exception e) {
    e.printStackTrace();
}

JavaScript

const car = 'MT-5107909-XXXXXXXXXXXXXXXXXXXXXXXX';
const culture = 'SOY';
const params = new URLSearchParams({ harvest: '2022/2023', source: 'MERX' });
const response = await fetch(
  `https://api.merx.tech/api/v1/integration/productivity/${car}/cultures/${culture}?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': '{SUA_API_KEY}',
    },
  }
);
const data = await response.json();
console.log(data);

Python

import requests

car = "MT-5107909-XXXXXXXXXXXXXXXXXXXXXXXX"
culture = "SOY"
url = f"https://api.merx.tech/api/v1/integration/productivity/{car}/cultures/{culture}"

headers = {
    "Authorization": "{SUA_API_KEY}",
}

params = {
    "harvest": "2022/2023",
    "source": "MERX"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

SDK Java

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;
import com.merx.sdk.model.productivity.Culture;
import com.merx.sdk.model.productivity.Source;

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .environment(Environment.SANDBOX)
    .build();

var productivity = merx.productivity().findByCarAndCulture("PR-1234567890", Culture.SOY, "2023/2024", Source.MERX, false, false);

Parâmetros

Parâmetros de Caminho:

Nome	Descrição	Tipo	Obrigatório
car	Cadastro Ambiental Rural (CAR)	String	Sim
culture	Tipo de cultura agrícola	String (Enum)	Sim

Parâmetros de Query:

Nome	Descrição	Tipo	Obrigatório	Padrão
harvest	Identificador da safra	String	Sim	-
source	Fonte dos dados de produtividade	String (Enum)	Não	MERX
excludeSmallerAreas	Excluir áreas menores da análise	Boolean	Não	true
includeGeoJson	Incluir geometria GeoJSON na resposta	Boolean	Não	false

Parâmetros de Cabeçalho

Nome	Descrição	Tipo	Obrigatório
Authorization	Chave de API obtida via support-api@merx.tech	String	Sim

Culturas Disponíveis

Valor	Descrição
SOY	Soja
CORN	Milho
SUGAR_CANE	Cana-de-açúcar
RICE	Arroz
COTTON	Algodão
COFFEE	Café
CITRUS	Citrus
PALM	Palma

Respostas

• 200 - Ok

[
  {
    "car": "MT-5107909-XXXXXXXXXXXXXXXXXXXXXXXX",
    "year_area": "2023",
    "year_productivity": "2023",
    "harvest": "2022/2023",
    "product": "SOY",
    "county_productivity": 55.5,
    "planted_area": 150.75,
    "declared_area": 200.0,
    "estimated_total_annual_production": 8366.625
  }
]

• 400 - Bad Request

Parâmetro enviado com tipo inválido (por exemplo culture fora dos valores do enum, ou um booleano malformado em excludeSmallerAreas / includeGeoJson):

{
  "timestamp": "2026-03-11T14:30:00.000",
  "status": 400,
  "error": "Bad Request",
  "message": "message.culture.invalid"
}

A chave em message é derivada do nome do parâmetro em letras minúsculas, no formato message.{parametro}.invalid.

• 401 - Unauthorized