Estornar Evento de Saldo

Descrição: Registra o estorno (total ou parcial) de uma entrega, identificada pelo seu delivery_identifier. O estorno não altera nem remove a entrega original: é criado um novo evento de saldo com volume negativo, vinculado à mesma entrega. A resposta da listagem não traz campo que classifique o evento nem ponteiro para o evento de origem — a distinção é pelo sinal do volume. O saldo efetivo da entrega é a soma dos volumes dos seus eventos (ex.: entrega de 150 + estorno de -50 = 100 restantes).

Endpoint

POST/api/v1/integration/balance-events/-:reversal

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
delivery_identifier	Identificador externo da entrega a ser estornada	String	Sim	Deve corresponder a uma entrega já registrada
volume	Quantidade estornada	Number	Sim	Deve ser maior que zero e não pode exceder o volume entregue menos os estornos anteriores
unit_of_measurement	Código da unidade de medida (ex.: SC, KG, TON)	String	Não	Se omitida, é utilizada a unidade registrada na entrega original. Se informada, deve ser a mesma unidade da entrega (não há conversão entre unidades)

• Uma mesma entrega pode receber múltiplos estornos parciais, desde que a soma não ultrapasse o volume entregue.
• Os dados de produtor, produto, safra e data de entrega do estorno são herdados automaticamente da entrega original.
• Os estornos aparecem na listagem de eventos de saldo com volume negativo e o mesmo delivery_identifier da entrega estornada. A listagem não expõe um campo que classifique o evento nem um ponteiro para o evento de origem — use o sinal de volume e o delivery_identifier para relacioná-los.

Exemplo de Requisição

cURL

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "delivery_identifier": "NF-12345",
    "volume": 50.5,
    "unit_of_measurement": "SC"
  }' \
  "https://api.merx.tech/api/v1/integration/balance-events/-:reversal"

Java

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

String body = "{\"delivery_identifier\": \"NF-12345\", \"volume\": 50.5, \"unit_of_measurement\": \"SC\"}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/balance-events/-:reversal"))
    .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/-:reversal',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      delivery_identifier: 'NF-12345',
      volume: 50.5,
      unit_of_measurement: 'SC',
    }),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

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

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

payload = {
    "delivery_identifier": "NF-12345",
    "volume": 50.5,
    "unit_of_measurement": "SC"
}

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
delivery_identifier	Identificador externo da entrega a ser estornada	String	Sim
volume	Quantidade estornada	Number	Sim
unit_of_measurement	Código da unidade de medida	String	Não

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
delivery_identifier ausente	delivery_identifier is required
volume ausente	volume is required
volume menor ou igual a zero	volume must be greater than zero
Volume estornado excede o volume entregue (menos estornos anteriores)	message.balance-event.reversal.volume.exceeds-delivered
Unidade de medida diferente da registrada na entrega	message.balance-event.reversal.unit-of-measurement.mismatch

• 404 - Not Found

Cenário	Mensagem de erro
Nenhuma entrega encontrada com o delivery_identifier	message.balance-event.reversal.delivery-not-found
Unidade de medida não encontrada	message.unit-of-measurement.not-found

• 415 - Unsupported Media Type

Content-Type diferente de application/json.