Gerar Relatório Socioambiental

Descrição: Gera um relatório pré-invoice de compliance socioambiental (ESG) a partir de um CAR ou CPF/CNPJ do produtor, de forma síncrona. O relatório é processado por completo e retornado na mesma resposta HTTP, com timeout máximo de 30 segundos.

Endpoint

POST/api/v1/integration/socioambiental

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
car	Código CAR do imóvel	String	Condicional	Pelo menos um entre `car` e `producer_document` deve ser preenchido. Torna-se obrigatório quando `validate_producer_ownership` for `true`
producer_name	Nome do produtor	String	Não
producer_document	CPF ou CNPJ do produtor	String	Condicional	Pelo menos um entre `car` e `producer_document` deve ser preenchido. Com ou sem pontuação. Torna-se obrigatório e deve ser um CPF ou CNPJ válido quando `validate_producer_ownership` for `true`
validate_producer_ownership	Quando `true`, valida se o produtor (identificado por `producer_document`) é titular do CAR informado	Boolean	Não	Quando `true`, torna `car` e `producer_document` obrigatórios e exige `producer_document` como CPF ou CNPJ válido

Exemplo de Requisição

cURL
Java
JavaScript
Python
SDK Java

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "car": "MT-5107925-A1B2C3D4E5F6",
    "producer_name": "Nome do Produtor",
    "producer_document": "00000000000",
    "validate_producer_ownership": false
  }' \
  "https://api.merx.tech/api/v1/integration/socioambiental"

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

String body = "{\"car\": \"MT-5107925-A1B2C3D4E5F6\", \"producer_name\": \"Nome do Produtor\", \"producer_document\": \"00000000000\", \"validate_producer_ownership\": false}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/socioambiental"))
    .header("Authorization", "{SUA_API_KEY}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .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();
}

const response = await fetch(
  'https://api.merx.tech/api/v1/integration/socioambiental',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      car: 'MT-5107925-A1B2C3D4E5F6',
      producer_name: 'Nome do Produtor',
      producer_document: '00000000000',
      validate_producer_ownership: false,
    }),
  }
);
const data = await response.json();
console.log(data);

import requests

url = "https://api.merx.tech/api/v1/integration/socioambiental"

headers = {
    "Authorization": "{SUA_API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "car": "MT-5107925-A1B2C3D4E5F6",
    "producer_name": "Nome do Produtor",
    "producer_document": "00000000000",
    "validate_producer_ownership": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;
import com.merx.sdk.model.carbon.socioambiental.SocioambientalRequest;

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

var report = merx.socioambiental().createReport(SocioambientalRequest.builder()
    .car("PR-1234567890")
    .producerName("Produtor Demo")
    .producerDocument("12345678901")
    .build());

Parâmetros

Parâmetros de Cabeçalho

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

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório	Validações
car	Código CAR do imóvel	String	Condicional	Pelo menos um entre `car` e `producer_document` deve ser preenchido. Torna-se obrigatório quando `validate_producer_ownership` for `true`
producer_name	Nome do produtor	String	Não
producer_document	CPF ou CNPJ do produtor	String	Condicional	Pelo menos um entre `car` e `producer_document` deve ser preenchido. Com ou sem pontuação. Torna-se obrigatório e deve ser um CPF ou CNPJ válido quando `validate_producer_ownership` for `true`
validate_producer_ownership	Quando `true`, valida se o produtor (identificado por `producer_document`) é titular do CAR informado	Boolean	Não	Quando `true`, torna `car` e `producer_document` obrigatórios e exige `producer_document` como CPF ou CNPJ válido

Dicionário de dados

Nome	Descrição	Tipo
status	Status do processamento do relatório. Valores: "PROCESSING", "UPDATING_CAR", "ERROR_UPDATING", "GENERATING_REPORT", "GENERATED", "ERROR_TIMEOUT", "ERROR"	Enum
processing_date	Data de processamento do relatório	Number (epoch s)
created_at	Data de criação do relatório	Number (epoch ms)
report_request_id	Identificador único do relatório gerado	UUID
cooperative_id	ID da cooperativa	UUID
cooperative_name	Nome da cooperativa	String
external_id	Identificador externo do relatório (não-anonimizado), utilizado para compartilhamento público	UUID
esg_status_summary	Status consolidado de conformidade socioambiental. Valores: "CONFORME", "NAO_CONFORME", "NAO_ENCONTRADO", "PROCESSANDO"	Enum
esg_status_farms	Status consolidado das fazendas. Valores: "CONFORME", "NAO_CONFORME", "NAO_ENCONTRADO", "PROCESSANDO"	Enum
is_summary_report	Indica se o relatório é resumido (gerado a partir de um CAR único)	Boolean
prodes_source	Fonte do PRODES utilizada. Valores: "AMAZONIA_LEGAL", "BIOMA_AMAZONIA"	Enum
anonimyzed	Indica se o relatório foi gerado de forma anonimizada (sempre presente)	Boolean
producer_data	Dados do produtor	Object
producer_data.document	CPF ou CNPJ do produtor	String
producer_data.name	Nome do produtor	String
producer_data_esg	Dados ESG do produtor	Object
producer_data_esg.document	CPF ou CNPJ	String
producer_data_esg.name	Nome do produtor	String
producer_data_esg.total_issues	Total de apontamentos do produtor	Number
producer_data_esg.esg_status	Status ESG do produtor	Enum
layer_data_producer	Camadas de análise do produtor (mesma estrutura de `esg[].layer_data`)	Array
esg	Lista de resultados por propriedade (CAR)	Array
esg[].farm_id	ID da fazenda no cadastro Merx	UUID
esg[].property_data	Dados da propriedade	Object
esg[].property_data.farm_name	Nome da fazenda	String
esg[].property_data.car	Código CAR	String
esg[].property_data.area	Área do imóvel (ha)	Number
esg[].property_data.legal_reserve_area	Área de reserva legal do imóvel (ha)	Number
esg[].property_data.permanent_protection_area	Área de preservação permanente do imóvel (ha)	Number
esg[].property_data.consolidated_area	Área consolidada do imóvel (ha)	Number
esg[].property_data.mod_fiscais	Número de módulos fiscais do imóvel	Number
esg[].property_data.geometry	Geometria do imóvel (GeoJSON)	String
esg[].property_data.centroid	Centróide da geometria	String
esg[].property_data.latitude	Latitude	Number
esg[].property_data.longitude	Longitude	Number
esg[].property_data.address	Endereço da propriedade	Object
esg[].property_data.address.street	Logradouro	String
esg[].property_data.address.number	Número	String
esg[].property_data.address.complement	Complemento	String
esg[].property_data.address.neighborhood	Bairro	String
esg[].property_data.address.zip_code	CEP	String
esg[].property_data.address.city	Município (resolvido pelo CAR)	String
esg[].property_data.address.state	UF (resolvida pelo CAR)	String
esg[].property_data.address.country	País	String
esg[].property_data.state_subscription	Inscrição estadual do imóvel	String
esg[].property_data.car_status	Status do CAR. Valores: "AT", "CA", "SU", "PE"	Enum
esg[].property_data.car_status_updated_at	Data de atualização do status do CAR	Number (epoch s)
esg[].property_data.created_at	Data de criação do CAR na base do SICAR	Number (epoch s)
esg[].property_data.updated_at	Data da última atualização do CAR na base do SICAR	Number (epoch s)
esg[].property_data_esg	Dados ESG da propriedade	Object
esg[].property_data_esg.farm_name	Nome da fazenda	String
esg[].property_data_esg.car	Código CAR	String
esg[].property_data_esg.esg_status	Status ESG da propriedade	Enum
esg[].property_data_esg.total_issues	Total de apontamentos da propriedade	Number
esg[].car_declaration_sigef	Dados da declaração CAR/SIGEF	Object
esg[].car_declaration_sigef.declared_area	Área declarada (ha)	Number
esg[].car_declaration_sigef.legal_reserve_area	Área de reserva legal (ha)	Number
esg[].car_declaration_sigef.permanent_protection_area	Área de proteção permanente (ha)	Number
esg[].car_declaration_sigef.tax_modules	Módulos fiscais	Number
esg[].car_declaration_sigef.analysis_date	Data de análise	String
esg[].car_declaration_sigef.registration_date	Data de registro	String
esg[].car_declaration_sigef.rectification_date	Data de retificação	String
esg[].car_declaration_sigef.merx_updated_at	Data de atualização no Merx	Number (epoch s)
esg[].layer_data	Camadas de análise da propriedade	Array
esg[].layer_data[].layer_esg_enum	Identificador da camada/tipo de embargo (ex: "EMBARGOS_IBAMA", "PRODES_AMAZONIA", "TERRAS_INDIGENAS_SIRGAS", "UNIDADE_CONSERVACAO"). O catálogo completo pode ser consultado em `GET /api/v1/integration/environmental-embargoes/layer-types`	String
esg[].layer_data[].layer_name	Nome da camada/órgão fiscalizador	String
esg[].layer_data[].layer_color	Cor da camada para renderização (hexadecimal)	String
esg[].layer_data[].layer_question	Pergunta associada à camada	String
esg[].layer_data[].layer_updated_at	Data da última atualização da camada na base	Number (epoch s)
esg[].layer_data[].esg_status	Status ESG da camada. Valores: "CONFORME", "NAO_CONFORME", "NAO_ENCONTRADO", "PROCESSANDO"	Enum
esg[].layer_data[].total_area	Área total afetada (ha)	Number
esg[].layer_data[].total_issues	Total de apontamentos na camada (sempre presente, inclusive `0`)	Number
esg[].layer_data[].layer_columns	Nomes das colunas correspondentes a cada posição de `items[].item_values`	Array
esg[].layer_data[].items	Apontamentos encontrados na camada	Array
esg[].layer_data[].items[].item_values	Valores do apontamento, na ordem de `layer_columns`	Array
esg[].layer_data[].geometries	Geometrias dos apontamentos da camada	Array
esg[].layer_data[].geometries[].geo_json	Geometria em formato GeoJSON	String
esg[].layer_data[].geometries[].area	Área da geometria (ha)	Number
esg[].layer_data[].eu_deforestation_layer	Indica se a camada é considerada camada de desmatamento para EUDR	Boolean
esg[].layer_data[].source_link	Link da fonte oficial do dado da camada	String

Respostas

200 - Ok

{
    "status": "GENERATED",
    "processing_date": 1773239400.000000000,
    "created_at": 1773239400000,
    "report_request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "cooperative_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cooperative_name": "Cooperativa Exemplo",
    "external_id": "f6a7b8c9-0123-4567-8901-234567890123",
    "esg_status_summary": "NAO_CONFORME",
    "esg_status_farms": "NAO_CONFORME",
    "is_summary_report": true,
    "prodes_source": "BIOMA_AMAZONIA",
    "anonimyzed": false,
    "producer_data": {
        "document": "00000000000",
        "name": "Nome do Produtor"
    },
    "producer_data_esg": {
        "document": "00000000000",
        "name": "Nome do Produtor",
        "total_issues": 0,
        "esg_status": "CONFORME"
    },
    "layer_data_producer": [
        {
            "layer_esg_enum": "IBAMA_PRODUTOR",
            "layer_name": "IBAMA - EMBARGOS",
            "layer_updated_at": 1740009600.000000000,
            "esg_status": "CONFORME",
            "total_issues": 0,
            "layer_columns": ["Nome", "CPF/CNPJ", "Data", "Estado", "Cidade", "Descrição infração", "Auto de infração"],
            "items": []
        }
    ],
    "esg": [
        {
            "farm_id": "6f2b1d10-6f4e-4a54-9f0e-2a0f3c1b7e55",
            "property_data": {
                "farm_name": "Fazenda São José",
                "car": "MT-5107925-A1B2C3D4E5F6",
                "area": 259.48,
                "legal_reserve_area": 90.12,
                "permanent_protection_area": 12.4,
                "consolidated_area": 140.2,
                "mod_fiscais": 3.5,
                "address": {
                    "city": "Sorriso",
                    "state": "MT"
                },
                "car_status": "AT",
                "car_status_updated_at": 1740009600.000000000,
                "created_at": 1592179200.000000000,
                "updated_at": 1705276800.000000000
            },
            "property_data_esg": {
                "farm_name": "Fazenda São José",
                "car": "MT-5107925-A1B2C3D4E5F6",
                "esg_status": "NAO_CONFORME",
                "total_issues": 2
            },
            "car_declaration_sigef": {
                "declared_area": 259.48,
                "legal_reserve_area": 90.12,
                "permanent_protection_area": 12.4,
                "tax_modules": 3.5,
                "analysis_date": "2024-01-01",
                "registration_date": "2020-06-15",
                "rectification_date": "2023-08-22",
                "merx_updated_at": 1705315800.000000000
            },
            "layer_data": [
                {
                    "layer_esg_enum": "PRODES",
                    "layer_name": "INPE - PRODES - AMAZÔNIA",
                    "layer_color": "#335690",
                    "layer_updated_at": 1740009600.000000000,
                    "esg_status": "NAO_CONFORME",
                    "total_area": 0.319,
                    "total_issues": 2,
                    "layer_columns": ["State", "Date", "Area (ha)", "Class"],
                    "items": [
                        { "item_values": ["MT", "2023", "0.319", "d2023"] }
                    ],
                    "geometries": [
                        { "geo_json": "{\"type\":\"Polygon\",\"coordinates\":[...]}", "area": 0.319 }
                    ],
                    "eu_deforestation_layer": true,
                    "source_link": "http://terrabrasilis.dpi.inpe.br"
                }
            ]
        }
    ]
}

400 - Bad Request

{
  "messages": ["message.entidade.campo-inválido"]
}

Quando validate_producer_ownership for true e o produtor identificado por producer_document não for titular do CAR informado (nenhuma fazenda do produtor corresponde ao CAR ou produtor não encontrado), a resposta retorna o erro message.socioambiental.car-producer.mismatch:

{
  "messages": ["message.socioambiental.car-producer.mismatch"]
}

401 - Unauthorized
404 - NotFound

Gerar Relatório Socioambiental

Endpoint​

Regras​

Exemplo de Requisição​

Parâmetros​

Parâmetros de Cabeçalho​

Parâmetros do Corpo​

Dicionário de dados​

Respostas​