Registrar Evento de Saldo

Descrição: Registra um evento de saldo (entrega) de um produtor. Diferente do endpoint de Saldos (que mantém apenas o saldo final), os eventos de saldo preservam todo o histórico de entregas.

O delivery_identifier, quando informado, é único por cliente:

• Se o mesmo produtor reenviar uma entrega com um delivery_identifier já registrado, os dados da entrega existente são substituídos (data, volume, unidade, safra e produto) — não é criado um novo registro.
• Se outro produtor enviar um delivery_identifier já registrado, a requisição é rejeitada com erro de identificador duplicado (409).
• Entregas sem delivery_identifier sempre geram um novo registro, mas não podem ser estornadas nem substituídas posteriormente.

Para estornar uma entrega registrada, utilize o endpoint Estornar Evento de Saldo.

Endpoint

POST/api/v1/integration/balance-events

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
producer_document	CPF ou CNPJ do produtor	String	Sim	Deve conter 11 dígitos (CPF) ou 14 dígitos (CNPJ), apenas números
delivery_identifier	Identificador externo da entrega	String	Não	Único por cliente. Reenvio pelo mesmo produtor substitui a entrega; por outro produtor, é rejeitado
delivery_date	Data da entrega	String	Sim	Formato yyyy-MM-dd
volume	Volume entregue	Number	Sim	Deve ser maior que zero
unit_of_measurement	Código da unidade de medida (ex.: SC, KG, TON)	String	Sim	Deve existir na base
harvest	Nome da safra (ex.: 2023/2024 ou 2025 - Safrinha)	String	Não	Se informada, deve existir na base
product	Nome do produto (ex.: SOJA, MILHO)	String	Sim	Deve existir na base

Exemplo de Requisição

cURL

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "producer_document": "52998224725",
    "delivery_identifier": "NF-12345",
    "delivery_date": "2024-01-15",
    "volume": 150.5,
    "unit_of_measurement": "SC",
    "harvest": "2023/2024",
    "product": "SOJA"
  }' \
  "https://api.merx.tech/api/v1/integration/balance-events"

Java

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

String body = "{\"producer_document\": \"52998224725\", \"delivery_identifier\": \"NF-12345\", \"delivery_date\": \"2024-01-15\", \"volume\": 150.5, \"unit_of_measurement\": \"SC\", \"harvest\": \"2023/2024\", \"product\": \"SOJA\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/balance-events"))
    .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();
}

JavaScript

const response = await fetch(
  'https://api.merx.tech/api/v1/integration/balance-events',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      producer_document: '52998224725',
      delivery_identifier: 'NF-12345',
      delivery_date: '2024-01-15',
      volume: 150.5,
      unit_of_measurement: 'SC',
      harvest: '2023/2024',
      product: 'SOJA',
    }),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.merx.tech/api/v1/integration/balance-events"

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

payload = {
    "producer_document": "52998224725",
    "delivery_identifier": "NF-12345",
    "delivery_date": "2024-01-15",
    "volume": 150.5,
    "unit_of_measurement": "SC",
    "harvest": "2023/2024",
    "product": "SOJA"
}

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

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	Deve ser application/json	String	Sim

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório
producer_document	CPF ou CNPJ do produtor	String	Sim
delivery_identifier	Identificador externo da entrega	String	Não
delivery_date	Data da entrega (yyyy-MM-dd)	String	Sim
volume	Volume entregue	Number	Sim
unit_of_measurement	Código da unidade de medida	String	Sim
harvest	Nome da safra	String	Não
product	Nome do produto	String	Sim

Respostas

• 200 - OK

{
  "id": "93bb82bc-a6e2-45a9-af2f-e671ab55ec3e"
}

• 400 - Bad Request

{
  "messages": [
    "descrição do erro 1",
    "descrição do erro 2"
  ]
}

Cenário	Mensagem de erro
producer_document ausente	producer_document is required
delivery_date ausente	delivery_date is required
volume ausente	volume is required
volume menor ou igual a zero	volume must be greater than zero
unit_of_measurement ausente	unit_of_measurement is required
product ausente	product is required
Substituição com volume menor que o total já estornado da entrega	message.balance-event.volume.less-than-reversed
Substituição alterando a unidade de medida com estornos já registrados	message.balance-event.reversal.unit-of-measurement.mismatch

• 404 - Not Found

Cenário	Mensagem de erro
Produtor não encontrado pelo documento	message.producer.not-found
Unidade de medida não encontrada	message.unit-of-measurement.not-found
Produto não encontrado	message.product.not-found
Safra não encontrada	message.harvest.not-found

• 409 - Conflict

Retornado quando o delivery_identifier informado já está registrado para outro produtor no mesmo cliente (message.balance-event.delivery-identifier.duplicated).

• 415 - Unsupported Media Type

Content-Type diferente de application/json.