Gerar Relatório CBIOS

Descrição: Gera um relatório CBIOS (Créditos de Descarbonização) de forma síncrona. O relatório é processado por completo e retornado na mesma resposta HTTP. É utilizado para verificar a elegibilidade de propriedades rurais para a geração de créditos de carbono, analisando a supressão de vegetação nativa e a conformidade com os critérios do programa RenovaBio.

Cada requisição bem-sucedida consome saldo do produto CBIOS 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/cbios

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
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 o relatório no histórico do backoffice (default true)	Boolean	Não
preserve_result	Preservar o resultado persistido (default false)	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/cbios" \
--data '{
    "producer_name": "João da Silva",
    "producer_document": "39053344705",
    "username": "operador@cooperativa.com.br",
    "name": "CBIOS 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
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
preserve_result	Preservar o resultado persistido (default false)	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
show_farm_null_values	Indica se fazendas com valores nulos devem ser exibidas	Boolean
producer_data	Dados do produtor	Object
producer_data.producer_id	ID do produtor	UUID
producer_data.document	CPF ou CNPJ 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
cbios	Lista de resultados por CAR	Array
cbios[].property_data	Dados da propriedade	Object
cbios[].property_data.farm_name	Nome da fazenda	String
cbios[].property_data.car	Código CAR	String
cbios[].property_data.area	Área do imóvel (ha)	Number
cbios[].property_data.geometry	Geometria da propriedade (GeoJSON)	String
cbios[].property_data.centroid	Centróide da propriedade	String
cbios[].property_data.latitude	Latitude	Number
cbios[].property_data.longitude	Longitude	Number
cbios[].property_data.car_status	Status do CAR. Valores: AT, CA, SU, PE	Enum
cbios[].property_data.car_status_updated_at	Data de atualização do status	DateTime
cbios[].car_declaration_sigef	Dados da declaração CAR/SIGEF	Object
cbios[].car_declaration_sigef.declared_area	Área declarada	Number
cbios[].car_declaration_sigef.legal_reserve_area	Área de reserva legal	Number
cbios[].car_declaration_sigef.permanent_protection_area	Área de proteção permanente	Number
cbios[].car_declaration_sigef.tax_modules	Módulos fiscais	Number
cbios[].car_declaration_sigef.analysis_date	Data de análise	String
cbios[].car_declaration_sigef.registration_date	Data de registro	String
cbios[].car_declaration_sigef.rectification_date	Data de retificação	String
cbios[].car_declaration_sigef.merx_updated_at	Data de atualização no Merx	DateTime
cbios[].productivity	Dados de produtividade	Array
cbios[].productivity[].crop	Cultura	String
cbios[].productivity[].harvest	Safra	String
cbios[].productivity[].planted_area	Área plantada	Number
cbios[].productivity[].layer	Camada (SOY ou CORN)	Enum
cbios[].productivity[].projected_productivity_year	Ano de produtividade projetada	Integer
cbios[].productivity[].projected_productivity	Produtividade projetada	Number
cbios[].productivity[].estimated_total_annual_production_year	Ano de produção total estimada	Integer
cbios[].productivity[].estimated_total_annual_production	Produção total anual estimada	Number
cbios[].cbios_data_information	Informações específicas CBIOS	Object
cbios[].cbios_data_information.native_area2017	Área nativa em 2017 (ha)	Number
cbios[].cbios_data_information.native_area_civil_year	Área nativa no ano civil (ha)	Number
cbios[].cbios_data_information.supressed_area	Área suprimida (ha)	Number
cbios[].cbios_data_information.harvest_biomass_area	Área de biomassa da safra (ha)	Number
cbios[].cbios_data_information.biomass_area_supressed	Área de biomassa suprimida (ha)	Number
cbios[].cbios_data_information.harvest_supression	Houve supressão na safra. Valores: SIM, NAO, NAO_APLICAVEL	Enum
cbios[].cbios_data_information.cbios_status	Status CBIOS	Enum
cbios[].cbios_data_information.cbios_manual_status	Status CBIOS manual	Enum
cbios[].cbios_data_information.geometries	Geometrias relacionadas	Array
cbios[].cbios_data_information.geometries[].geometry_type	Tipo de geometria	Enum
cbios[].cbios_data_information.geometries[].geo_json	Geometria em formato GeoJSON	String
cbios[].cbios_data_information.geometries[].subtitle	Legenda da geometria	String

Valores de Enums

Status CBIOS

Valor	Descrição
NAO_ENCONTRADO	Não encontrado
ELEGIVEL	Elegível para geração de CBIOS
NAO_ELEGIVEL	Não elegível para geração de CBIOS
NAO_APLICAVEL	Não aplicável

Supressão na Safra (harvest_supression)

Valor	Descrição
SIM	Houve supressão de vegetação
NAO	Não houve supressão de vegetação
NAO_APLICAVEL	Não aplicável

Status CAR

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

Layer (Camada)

Valor	Descrição
SOY	Soja
CORN	Milho

Geometry Type (Tipo de Geometria)

Valor	Descrição
SUPRESSED_AREA	Área suprimida
SOY_AREA	Área de soja
CORN_AREA	Área de milho
SOY_IN_ACCUMULATED_SUPPRESSION_AREA	Área de soja em supressão acumulada
CORN_IN_ACCUMULATED_SUPPRESSION_AREA	Área de milho em supressão acumulada
PERMANENT_PROTECTION_AREA	Área de proteção permanente
INDIGENOUS_AREA	Área indígena
CONSERVATION_UNIT_AREA	Área de unidade de conservação
QUILOMBOLA_AREA	Área quilombola

Respostas

• 200 - Ok

{
    "status": "GENERATED",
    "created_at": 1711564200000,
    "report_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "cooperative_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cooperative_name": "Cooperativa Exemplo",
    "layer": "SOY",
    "civil_year": 2024,
    "harvest": "2023/2024",
    "show_farm_null_values": false,
    "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
    },
    "cbios": [
        {
            "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,
                "merx_updated_at": "2024-01-15T10:30:00Z"
            },
            "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
                }
            ],
            "cbios_data_information": {
                "native_area2017": 150.25,
                "native_area_civil_year": 145.50,
                "supressed_area": 4.75,
                "harvest_biomass_area": 350.00,
                "biomass_area_supressed": 0.0,
                "harvest_supression": "NAO",
                "cbios_status": "ELEGIVEL",
                "cbios_manual_status": null,
                "geometries": [
                    {
                        "geometry_type": "SOY_AREA",
                        "geo_json": "{\"type\":\"Polygon\",\"coordinates\":[...]}",
                        "subtitle": "Área de Soja 2023/2024"
                    }
                ]
            }
        }
    ]
}

• 400 - Bad Request

{
    "timestamp": "2026-03-11T14:30:00Z",
    "status": 400,
    "error": "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	Campos obrigatórios do body não enviados	Preencher name e username 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)