Criar Rastreabilidade

Descrição: Cria Rastreabilidade de uma ou mais Fazendas para uma Negociação.

A rastreabilidade pode ser criada em dois modos:

Fluxo A (padrão): o sistema gera os relatórios socioambiental (ESG) e EUDR a partir do CAR da fazenda e do CPF/CNPJ do produtor. Use este fluxo quando a integração ainda não tem um relatório pré-gerado.
Fluxo B (relatórios pré-gerados): quando o integrador já gerou os relatórios socioambiental e EUDR previamente (por exemplo, durante a importação de uma Nota Fiscal), é possível reaproveitá-los informando invoice_import_id, esg_report_request_id, eudr_report_request_id e use_pre_generated_reports. Isso evita reprocessamento e reduz tempo de resposta.

Endpoint

POST/api/v1/integration/traceability/-/commitments/{order_commitment_id}

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
order_commitment_id	ID da Negociação	UUID	Sim

Exemplo de Requisição — Fluxo A (geração padrão de relatórios)

cURL
Java
JavaScript
Python
SDK Java

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "farm_id": "e168db8c-4fa2-4728-9ec3-945207fa474c",
    "producer_id": "8846b788-1438-40c8-84c3-28389063e6b8",
    "user_id": "4b5e9d45-da34-460f-98b9-bbd92f847c3b",
    "allocated_volume": 123.12,
    "unit_of_measurement": "SC"
  }' \
  "https://api.merx.tech/api/v1/integration/traceability/-/commitments/{order_commitment_id}"

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

String body = "{\"farm_id\": \"e168db8c-4fa2-4728-9ec3-945207fa474c\", \"producer_id\": \"8846b788-1438-40c8-84c3-28389063e6b8\", \"user_id\": \"4b5e9d45-da34-460f-98b9-bbd92f847c3b\", \"allocated_volume\": 123.12, \"unit_of_measurement\": \"SC\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/traceability/-/commitments/{order_commitment_id}"))
    .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/traceability/-/commitments/{order_commitment_id}',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      farm_id: 'e168db8c-4fa2-4728-9ec3-945207fa474c',
      producer_id: '8846b788-1438-40c8-84c3-28389063e6b8',
      user_id: '4b5e9d45-da34-460f-98b9-bbd92f847c3b',
      allocated_volume: 123.12,
      unit_of_measurement: 'SC',
    }),
  }
);
const data = await response.json();
console.log(data);

import requests

url = "https://api.merx.tech/api/v1/integration/traceability/-/commitments/{order_commitment_id}"

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

payload = {
    "farm_id": "e168db8c-4fa2-4728-9ec3-945207fa474c",
    "producer_id": "8846b788-1438-40c8-84c3-28389063e6b8",
    "user_id": "4b5e9d45-da34-460f-98b9-bbd92f847c3b",
    "allocated_volume": 123.12,
    "unit_of_measurement": "SC"
}

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.order.traceability.CreateTraceabilityRequest;
import com.merx.sdk.model.common.IdResponse;
import java.util.UUID;
import java.math.BigDecimal;

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

IdResponse trace = merx.traceability().create(UUID.fromString("00000000-0000-0000-0000-000000000000"), CreateTraceabilityRequest.builder()
    .farmId(UUID.fromString("00000000-0000-0000-0000-000000000000"))
    .allocatedVolume(new BigDecimal("50"))
    .unitOfMeasurement("KG")
    .build());
System.out.println(trace.getId());

Exemplo de Requisição — Fluxo B (reaproveitamento de relatórios pré-gerados)

Use quando os relatórios ESG e EUDR já foram gerados previamente — tipicamente quando a rastreabilidade está sendo criada a partir de uma Nota Fiscal já importada que gerou os relatórios.

Fluxo B — relatórios pré-gerados
curl -X POST \
-H "Authorization: {SUA_API_KEY}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
"https://api.merx.tech/api/v1/integration/traceability/-/commitments/17b75d09-bcca-43d1-a656-cb6226b74a83" \
--data '{
    "farm_id":"e168db8c-4fa2-4728-9ec3-945207fa474c",
    "producer_id": "8846b788-1438-40c8-84c3-28389063e6b8",
    "user_id":"4b5e9d45-da34-460f-98b9-bbd92f847c3b",
    "allocated_volume": 123.12,
    "unit_of_measurement": "SC",
    "invoice_import_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "esg_report_request_id": "b2c3d4e5-f678-9012-abcd-ef3456789012",
    "eudr_report_request_id": "c3d4e5f6-7890-1234-bcde-f45678901234",
    "use_pre_generated_reports": true
}'

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 de Caminho

Nome	Descrição	Tipo	Obrigatório
order_commitment_id	ID da Negociação	UUID	Sim

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório	Validações
producer_id	ID do produtor	UUID	Sim	-
user_id	ID do usuário responsável pela operação (auditoria)	UUID	Sim	-
farm_id	ID da Fazenda. Quando ausente, a rastreabilidade é criada apenas no nível do produtor	UUID	Não	-
allocated_volume	Volume alocado para a rastreabilidade	Number	Não	Valor decimal estritamente positivo, com no máximo 13 dígitos inteiros e 2 casas decimais
unit_of_measurement	Unidade de medida do volume alocado. Padrão: `TON`	String	Não	Sem validação de valores: a API aceita qualquer string. Use `SC`, `KG` ou `TON`
invoice_import_id	ID da Nota Fiscal previamente importada que originou os relatórios ESG e EUDR. Use no Fluxo B	UUID	Não	Não é exigido pela validação de `use_pre_generated_reports`; quando informado, passa pelas validações de NF abaixo
esg_report_request_id	ID do relatório socioambiental (ESG) pré-gerado que será reaproveitado. Use no Fluxo B	UUID	Não	Obrigatório quando `use_pre_generated_reports` é `true`. Deve ser informado junto com `eudr_report_request_id`
eudr_report_request_id	ID do relatório EUDR pré-gerado que será reaproveitado. Use no Fluxo B	UUID	Não	Obrigatório quando `use_pre_generated_reports` é `true`. Deve ser informado junto com `esg_report_request_id`
use_pre_generated_reports	Indica que a rastreabilidade deve reaproveitar os relatórios informados em `esg_report_request_id` e `eudr_report_request_id` em vez de gerar novos	Boolean	Não	Quando `true`, exige `esg_report_request_id` e `eudr_report_request_id`. `invoice_import_id` não é exigido por essa regra

Fluxo A × Fluxo B:
No Fluxo A, omita invoice_import_id, esg_report_request_id, eudr_report_request_id e use_pre_generated_reports (ou envie use_pre_generated_reports: false). Os relatórios serão gerados a partir do CAR da fazenda e do CPF/CNPJ do produtor.
No Fluxo B, envie use_pre_generated_reports: true junto com esg_report_request_id e eudr_report_request_id — apenas esses dois são exigidos pela validação. O invoice_import_id é opcional e serve para amarrar a rastreabilidade a uma Nota Fiscal já importada; quando informado, ativa as validações de NF listadas abaixo. O sistema validará que os relatórios informados pertencem à cooperativa e estão em status válido antes de vinculá-los à rastreabilidade.

Respostas

200 - Ok

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Nome	Descrição	Tipo
id	Identificador único da rastreabilidade criada	UUID

400 - Bad Request

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

Principais cenários:

Cenário	Mensagem retornada
`producer_id` ausente	`message.producer-id.not-null`
`user_id` ausente	`message.user-id.not-null`
`allocated_volume` igual ou menor que zero	`message.allocated-volume.zero-or-under`
`allocated_volume` excede o tamanho ou casas decimais permitidos	`message.allocated-volume.wrong-value`
Produtor não encontrado	`message.traceability.producer.not-found`

Validações específicas do Fluxo B (relatórios pré-gerados):

Cenário	Mensagem retornada
`use_pre_generated_reports = true` sem `esg_report_request_id`	`message.esg-report-request-id.mandatory`
`use_pre_generated_reports = true` sem `eudr_report_request_id`	`message.eudr-report-request-id.mandatory`
`allocated_volume` ausente quando `use_pre_generated_reports = true`	`message.traceability.invoice.allocatedVolumeRequired`
Nota Fiscal referenciada em `invoice_import_id` não encontrada	`message.traceability.invoice.notFound`
Nota Fiscal cancelada	`message.traceability.invoice.cancelled`
Nota Fiscal não pertence à mesma negociação informada na rota	`message.traceability.invoice.commitmentMismatch`
Nota Fiscal não pertence à cooperativa do token	`message.traceability.invoice.cooperativeMismatch`
Volume alocado excede o volume remanescente da Nota Fiscal	`message.traceability.invoice.volumeExceedsInvoice`
Relatório ESG (`esg_report_request_id`) não encontrado	`message.traceability.report.esg.notFound`
Relatório EUDR (`eudr_report_request_id`) não encontrado	`message.traceability.report.eudr.notFound`
Relatório informado não está vinculado à Nota Fiscal de `invoice_import_id`	`message.traceability.report.notFromInvoice`
Relatório informado pertence a outra cooperativa	`message.traceability.report.cooperative.mismatch`
Cooperativa do relatório não pôde ser determinada	`message.traceability.report.cooperative.unknown`

401 - Unauthorized

Token ausente ou inválido.

404 - Not Found

Cenário	Mensagem retornada
Resumo ESG do produtor não encontrado	`message.esg.producer.not-found`

Nota: este serviço não valida a existência da negociação informada em order_commitment_id. Um 404 nesta rota vem da busca do resumo ESG do produtor ou é repassado pelo serviço de negociações consultado internamente.

409 - Conflict

{
    "messages": [
        "message.traceability.already-exists"
    ]
}

Já existe rastreabilidade para a combinação (commitment, producer) (quando farm_id não foi informado) ou (commitment, farm) (quando farm_id foi informado).

Criar Rastreabilidade

Endpoint​

Regras​

Exemplo de Requisição — Fluxo A (geração padrão de relatórios)​

Exemplo de Requisição — Fluxo B (reaproveitamento de relatórios pré-gerados)​

Parâmetros​

Parâmetros de Cabeçalho​

Parâmetros de Caminho​

Parâmetros do Corpo​

Respostas​