Listar Eventos de Saldo

Descrição: Lista os eventos de saldo de forma paginada. O filtro por produtor é feito através do CPF/CNPJ (producerDocument). Quando o documento não é informado, retorna todos os eventos de saldo do cliente (paginado).

A listagem inclui tanto as entregas (event_type: "DELIVERY", volume positivo) quanto os estornos (event_type: "REVERSAL", volume negativo). Nos estornos, o campo original_event_id aponta para a entrega estornada. O saldo efetivo de uma entrega é a soma dos volumes dos seus eventos.

Endpoint

GET/api/v1/integration/balance-events/-:filter

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
producerDocument	CPF ou CNPJ do produtor	String	Não	Deve conter 11 dígitos (CPF) ou 14 dígitos (CNPJ), apenas números
page	Número da página (inicia em 0)	Number	Não	Padrão 0
size	Quantidade de itens por página	Number	Não	Padrão 30; máximo 100

Exemplo de Requisição

cURL

curl -G \
  -H "Authorization: {SUA_API_KEY}" \
  --data-urlencode "producerDocument=52998224725" \
  --data-urlencode "page=0" \
  --data-urlencode "size=50" \
  "https://api.merx.tech/api/v1/integration/balance-events/-:filter"

Java

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

String url = "https://api.merx.tech/api/v1/integration/balance-events/-:filter"
    + "?producerDocument=52998224725&page=0&size=50";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Authorization", "{SUA_API_KEY}")
    .GET()
    .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 params = new URLSearchParams({
  producerDocument: '52998224725',
  page: '0',
  size: '50',
});

const response = await fetch(
  `https://api.merx.tech/api/v1/integration/balance-events/-:filter?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': '{SUA_API_KEY}',
    },
  }
);
const data = await response.json();
console.log(data);

Python

import requests

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

headers = {
    "Authorization": "{SUA_API_KEY}",
}

params = {
    "producerDocument": "52998224725",
    "page": 0,
    "size": 50,
}

response = requests.get(url, headers=headers, params=params)
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

Parâmetros de Query

Nome	Descrição	Tipo	Obrigatório
producerDocument	CPF ou CNPJ do produtor	String	Não
page	Número da página (inicia em 0)	Number	Não
size	Itens por página (máximo 100)	Number	Não

Respostas

• 200 - OK

{
  "content": [
    {
      "id": "93bb82bc-a6e2-45a9-af2f-e671ab55ec3e",
      "producer_id": "1e9c2b3a-4d5e-6f70-8a90-b1c2d3e4f506",
      "delivery_identifier": "NF-12345",
      "delivery_date": "2024-01-15",
      "volume": 150.5,
      "unit_of_measurement_id": "0c9f3d2a-1b4c-4d5e-8f90-a1b2c3d4e5f6",
      "harvest_id": "2b3c4d5e-6f70-8a90-b1c2-d3e4f5061728",
      "product_id": "76a8440d-9a02-4a06-8c21-8caf529616d0",
      "cooperative_id": "8c2db7cc-1020-4423-98cc-02e829299e40",
      "event_type": "DELIVERY",
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:00:00Z"
    },
    {
      "id": "5f8e7d6c-3b2a-4190-8f7e-6d5c4b3a2918",
      "producer_id": "1e9c2b3a-4d5e-6f70-8a90-b1c2d3e4f506",
      "delivery_identifier": "NF-12345",
      "delivery_date": "2024-01-15",
      "volume": -50.5,
      "unit_of_measurement_id": "0c9f3d2a-1b4c-4d5e-8f90-a1b2c3d4e5f6",
      "harvest_id": "2b3c4d5e-6f70-8a90-b1c2-d3e4f5061728",
      "product_id": "76a8440d-9a02-4a06-8c21-8caf529616d0",
      "cooperative_id": "8c2db7cc-1020-4423-98cc-02e829299e40",
      "event_type": "REVERSAL",
      "original_event_id": "93bb82bc-a6e2-45a9-af2f-e671ab55ec3e",
      "created_at": "2024-01-20T09:30:00Z",
      "updated_at": "2024-01-20T09:30:00Z"
    }
  ],
  "number": 0,
  "size": 50,
  "total_elements": 2,
  "total_pages": 1,
  "first": true,
  "last": true,
  "number_of_elements": 2
}

• 400 - Bad Request

{
  "messages": ["message.entidade.campo-invalido"]
}

• 401 - Unauthorized

• 404 - Not Found

Retornado quando o producerDocument informado não corresponde a nenhum produtor (message.producer.not-found).