Gerar Relatório 2BSVS

Descrição: Gera um relatório 2BSVS (Biomass-Based Voluntary Sustainability) de forma síncrona. O relatório é processado por completo e retornado na mesma resposta HTTP. É utilizado para verificar a conformidade de propriedades rurais com critérios de sustentabilidade, incluindo análises de desmatamento, áreas de proteção permanente, reservas legais e outros indicadores ambientais.

Cada requisição bem-sucedida consome saldo do produto BSVS da cooperativa dona do token. A cooperativa precisa ter saldo previamente cadastrado — caso contrário, o relatório ainda é gerado, mas o débito é registrado com erro e precisa ser reconciliado manualmente.

Endpoint

POST/api/v1/integration/bsvs

Regras

Atributos	Descrição	Tipo	Obrigatório
producer_name	Nome do produtor	String	Sim
producer_document	CPF ou CNPJ do produtor (com ou sem máscara)	String	Sim
cooperative_name	Nome da cooperativa emissora	String	Sim
username	E-mail/login do operador responsável (usado em auditoria)	String	Sim
name	Rótulo do relatório (aparece no histórico do backoffice)	String	Sim
layer	Camada de análise. Valores: SOY, CORN	Enum	Sim
civil_year	Ano civil de referência (ex: 2024)	Integer	Sim
harvest_code	Código da safra (ver seção específica abaixo)	Integer	Sim
cars	Lista de códigos CAR do produtor	Array	Recomendado
preserve_on_backoffice_history	Preservar no histórico do backoffice (default true)	Boolean	Não

Exemplo de Requisição

Exemplo de Requisição

curl -X POST \
-H "Authorization: [[apiKey]]" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
"https://homolog.api.merx.tech/api/v1/integration/bsvs" \
--data '{
    "producer_name": "João da Silva",
    "producer_document": "39053344705",
    "cooperative_name": "Cooperativa ABC",
    "username": "operador@cooperativa.com.br",
    "name": "2BSVS João da Silva - Safra 23/24",
    "layer": "SOY",
    "civil_year": 2024,
    "harvest_code": 2324,
    "cars": ["MT-5107925-7515B28AEE9240ACAB464D8DF624D470"]
}'

Parâmetros

Parâmetros de Cabeçalho

Nome	Descrição	Tipo	Obrigatório
Authorization	Token de autenticação (UUID cru, sem prefixo Bearer)	String	Sim
Content-Type	application/json	String	Sim

Importante: não envie o header cooperative-id. Ele é injetado automaticamente pelo API gateway (Kong + plugin merx-custom-auth) resolvendo o owner do token. Qualquer valor enviado pelo cliente é ignorado ou sobrescrito.

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório
producer_name	Nome do produtor	String	Sim
producer_document	CPF ou CNPJ do produtor (com ou sem pontuação)	String	Sim
cooperative_name	Nome da cooperativa emissora	String	Sim
username	E-mail/login do operador responsável (usado em auditoria)	String	Sim
name	Rótulo do relatório (aparece no histórico)	String	Sim
layer	Camada de análise. Valores: SOY, CORN	Enum	Sim
civil_year	Ano civil de referência	Integer	Sim
harvest_code	Código da safra (ver tabela abaixo)	Integer	Sim
cars	Lista de códigos CAR para análise	Array	Recomendado
preserve_on_backoffice_history	Preservar no histórico do backoffice (default true)	Boolean	Não

Código da safra (harvest_code)

O harvest_code segue o formato AAAB, onde AAA são os três últimos dígitos do ano inicial e B é o último dígito do ano final da safra. Na prática: ano inicial com 2 dígitos + ano final com 2 dígitos.

Exemplo: 2324 representa a safra 2023/2024. Não envie 2024 (o ano civil sozinho), isso é motivo recorrente de erro 500 no backend.

Valores válidos atualmente cadastrados em homologação:

layer	harvest_code	Descrição
SOY	1819	Safra 2018/2019 (soja)
SOY	1920	Safra 2019/2020 (soja)
SOY	2021	Safra 2020/2021 (soja)
SOY	2122	Safra 2021/2022 (soja)
SOY	2223	Safra 2022/2023 (soja)
SOY	2324	Safra 2023/2024 (soja)
SOY	2425	Safra 2024/2025 (soja)
CORN	2122	Safrinha 2022 (milho)
CORN	2324	Safrinha 2024 (milho)

Dicionário de Dados da Resposta

Nome	Descrição	Tipo
status	Status do processamento. Valores: GENERATED, PROCESSING, ERROR	Enum
created_at	Data de criação do relatório (timestamp Unix em milissegundos)	Long
report_request_id	Identificador único do relatório gerado	UUID
cooperative_id	ID da cooperativa (injetado pelo gateway)	UUID
cooperative_name	Nome da cooperativa	String
layer	Camada de análise. Valores: SOY, CORN	Enum
civil_year	Ano civil de referência	Integer
harvest	Nome da safra no formato AAAA/AAAA (ex: "2023/2024")	String
error	Mensagem de erro, se houver	String
producer_data	Dados do produtor	Object
producer_data.producer_id	ID do produtor	UUID
producer_data.document	Documento do produtor	String
producer_data.name	Nome do produtor	String
producer_data.dap_code	Código DAP	String
producer_data.caf_code	Código CAF	String
producer_data.ricaf_code	Código RICAF	String
bsvs	Lista de resultados por CAR	Array
bsvs[].property_data	Dados da propriedade	Object
bsvs[].property_data.farm_name	Nome da fazenda	String
bsvs[].property_data.car	Código CAR	String
bsvs[].property_data.area	Área do imóvel (ha)	Number
bsvs[].property_data.geometry	Geometria da propriedade (GeoJSON)	String
bsvs[].property_data.centroid	Centróide da propriedade	String
bsvs[].property_data.latitude	Latitude	Number
bsvs[].property_data.longitude	Longitude	Number
bsvs[].property_data.car_status	Status do CAR. Valores: AT, CA, SU, PE	Enum
bsvs[].property_data.car_status_updated_at	Data de atualização do status	DateTime
bsvs[].car_declaration_sigef	Dados da declaração CAR/SIGEF	Object
bsvs[].car_declaration_sigef.declared_area	Área declarada	Number
bsvs[].car_declaration_sigef.legal_reserve_area	Área de reserva legal	Number
bsvs[].car_declaration_sigef.permanent_protection_area	Área de proteção permanente	Number
bsvs[].car_declaration_sigef.tax_modules	Módulos fiscais	Number
bsvs[].productivity	Dados de produtividade	Array
bsvs[].productivity[].crop	Cultura	String
bsvs[].productivity[].harvest	Safra	String
bsvs[].productivity[].planted_area	Área plantada	Number
bsvs[].productivity[].layer	Camada (SOY ou CORN)	Enum
bsvs[].productivity[].projected_productivity	Produtividade projetada	Number
bsvs[].productivity[].estimated_total_annual_production	Produção total anual estimada	Number
bsvs[].bsvs_data_information	Informações específicas 2BSVS	Object
bsvs[].bsvs_data_information.conservation_unit_area	Área em unidade de conservação	Number
bsvs[].bsvs_data_information.conservation_unit_status	Status da unidade de conservação	Enum
bsvs[].bsvs_data_information.indigenous_area	Área indígena	Number
bsvs[].bsvs_data_information.indigenous_area_status	Status da área indígena	Enum
bsvs[].bsvs_data_information.quilombola_area	Área quilombola	Number
bsvs[].bsvs_data_information.quilombola_area_status	Status da área quilombola	Enum
bsvs[].bsvs_data_information.biomass_area	Área de biomassa	Number
bsvs[].bsvs_data_information.biomass_status	Status da biomassa	Enum
bsvs[].bsvs_data_information.app_area	Área de APP	Number
bsvs[].bsvs_data_information.biomass_app_area	Área de biomassa em APP	Number
bsvs[].bsvs_data_information.biomass_app_status	Status da biomassa em APP	Enum
bsvs[].bsvs_data_information.accumulated_supression	Supressão acumulada	Number
bsvs[].bsvs_data_information.biomass_supression_area	Área de supressão de biomassa	Number
bsvs[].bsvs_data_information.biomass_supression_status	Status da supressão de biomassa	Enum
bsvs[].bsvs_data_information.biomass_supression_eligibility	Elegibilidade da supressão de biomassa	Enum
bsvs[].bsvs_data_information.biomass_total_production	Produção total de biomassa	Number
bsvs[].layer_esg_data	Dados de camadas ESG	Array
bsvs[].layer_esg_data[].embargo_type	Tipo de embargo	String
bsvs[].layer_esg_data[].layer_name	Nome da camada	String
bsvs[].layer_esg_data[].esg_status	Status ESG	Enum
bsvs[].layer_esg_data[].total_area	Área total	Number
bsvs[].layer_esg_data[].total_issues	Total de apontamentos	Integer
bsvs[].environmental_protection_layers	Camadas de proteção ambiental	Array
bsvs[].environmental_protection_layers[].layer_name	Nome da camada	String
bsvs[].environmental_protection_layers[].total_area	Área total	Number
bsvs[].environmental_protection_layers[].total_issues	Total de apontamentos	Integer
bsvs[].environmental_protection_layers[].environmental_protection_status	Status de proteção ambiental	Enum
bsvs[].permanent_protection_areas	Áreas de proteção permanente	Array
bsvs[].permanent_protection_areas[].area	Área em hectares	Number
bsvs[].permanent_protection_areas[].city	Cidade	String
bsvs[].permanent_protection_areas[].state	Estado	String
bsvs[].permanent_protection_areas[].description	Descrição	String

Valores de Enums

Status 2BSVS

Valor	Descrição
CONFORME	Propriedade em conformidade
NAO_CONFORME	Propriedade não conforme
NAO_APLICAVEL	Não aplicável
NAO_ELEGIVEL	Não elegível
ELEGIVEL	Elegível
NAO_ENCONTRADO	Não encontrado

Status CAR

Valor	Descrição
AT	Ativo
CA	Cancelado
SU	Suspenso
PE	Pendente

Layer (Camada)

Valor	Descrição
SOY	Soja
CORN	Milho

Respostas

• 200 - Ok

{
    "status": "GENERATED",
    "created_at": 1711564200000,
    "report_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cooperative_id": "12345678-1234-1234-1234-123456789012",
    "cooperative_name": "Cooperativa ABC",
    "layer": "SOY",
    "civil_year": 2024,
    "harvest": "2023/2024",
    "error": null,
    "producer_data": {
        "producer_id": "b2c3d4e5-f678-9012-abcd-ef3456789012",
        "document": "39053344705",
        "name": "João da Silva",
        "dap_code": null,
        "caf_code": null,
        "ricaf_code": null
    },
    "bsvs": [
        {
            "property_data": {
                "farm_name": "Fazenda São José",
                "car": "MT-5107925-7515B28AEE9240ACAB464D8DF624D470",
                "area": 500.50,
                "geometry": "{...}",
                "centroid": "POINT(-55.123 -15.456)",
                "latitude": -15.456,
                "longitude": -55.123,
                "car_status": "AT",
                "car_status_updated_at": "2024-01-10T00:00:00Z"
            },
            "car_declaration_sigef": {
                "declared_area": 500.50,
                "legal_reserve_area": 100.10,
                "permanent_protection_area": 25.25,
                "tax_modules": 5.5,
                "analysis_date": "2024-01-01",
                "registration_date": "2020-06-15",
                "rectification_date": null
            },
            "productivity": [
                {
                    "crop": "Soja",
                    "harvest": "2023/2024",
                    "planted_area": 350.00,
                    "layer": "SOY",
                    "projected_productivity_year": 2024,
                    "projected_productivity": 60.0,
                    "estimated_total_annual_production_year": 2024,
                    "estimated_total_annual_production": 21000.0
                }
            ],
            "bsvs_data_information": {
                "conservation_unit_area": 0.0,
                "conservation_unit_status": "CONFORME",
                "indigenous_area": 0.0,
                "indigenous_area_status": "CONFORME",
                "quilombola_area": 0.0,
                "quilombola_area_status": "CONFORME",
                "biomass_area": 125.35,
                "biomass_status": "APLICAVEL",
                "app_area": 25.25,
                "biomass_app_area": 0.0,
                "biomass_app_status": "CONFORME",
                "accumulated_supression": 0.0,
                "biomass_supression_area": 0.0,
                "biomass_supression_status": "CONFORME",
                "biomass_supression_eligibility": "ELEGIVEL",
                "biomass_total_production": 21000.0
            },
            "layer_esg_data": [
                {
                    "embargo_type": "EMBARGOS_IBAMA",
                    "layer_name": "IBAMA - EMBARGOS",
                    "esg_status": "CONFORME",
                    "total_area": 0.0,
                    "total_issues": 0
                }
            ],
            "environmental_protection_layers": [
                {
                    "layer_name": "Unidades de Conservação",
                    "total_area": 0.0,
                    "total_issues": 0,
                    "environmental_protection_status": "CONFORME"
                }
            ],
            "permanent_protection_areas": []
        }
    ]
}

• 400 - Bad Request

{
    "timestamp": "2026-03-11T14:30:00Z",
    "status": 400,
    "error": "cooperative_name is required"
}

• 401 - Unauthorized

Token ausente ou inválido.

• 500 - Internal Server Error

Erro interno. Causas conhecidas: harvest_code sem cadastro para a layer informada, cars ausente/vazio (bug latente) ou CPF/CNPJ em formato inválido.

Erros comuns

Sintoma	Causa provável	Como resolver
401 Unauthorized	Header Authorization ausente ou com prefixo Bearer	Enviar o token UUID cru, sem o prefixo Bearer
400 Bad Request com name is required / username is required / cooperative_name is required	Campos obrigatórios do body não enviados	Preencher name, username e cooperative_name sempre
500 Internal Server Error após poucos milissegundos	harvest_code enviado como ano civil (2024) em vez de código da safra (2324)	Consultar a tabela de harvest_code válidos acima
500 Internal Server Error com stacktrace de NullPointerException no carbon-api	cars ausente ou vazio	Enviar sempre pelo menos um CAR no array cars
500 Internal Server Error citando CPF/CNPJ	Documento em formato inválido	Verificar o producer_document (aceita com ou sem máscara, mas precisa ser um CPF/CNPJ válido)