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 (volume positivo) quanto os estornos (volume negativo). A resposta não traz um campo que classifique o evento nem um ponteiro para a entrega estornada: use o sinal de volume para distinguir os dois casos e agrupe os eventos por delivery_identifier para reconstituir a relação entre uma entrega e seus estornos. 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	Máscara é removida antes da busca. Documento inválido não gera 400: a API apenas registra um alerta e segue, e a falha aparece como 404 message.producer.not-found quando nenhum produtor casa com o documento
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
sort	Ordenação no formato campo,direção	String	Não	Repassado ao serviço de origem. Quando ausente, vale a ordenação padrão desse serviço

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
sort	Ordenação no formato campo,direção	String	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",
      "created_at": 1705320000.000000000,
      "updated_at": 1705320000.000000000
    },
    {
      "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",
      "created_at": 1705743000.000000000,
      "updated_at": 1705743000.000000000
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": false,
      "empty": false
    },
    "page_number": 0,
    "page_size": 50,
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "number": 0,
  "size": 50,
  "total_elements": 2,
  "total_pages": 1,
  "sort": {
    "sorted": true,
    "unsorted": false,
    "empty": false
  },
  "first": true,
  "last": true,
  "number_of_elements": 2,
  "empty": false
}

• 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).