Processar Saldos de Produtores em Lote

Descrição: Processa uma lista de saldos de produtores. Comportamento de rollback total: se qualquer item falhar na validação, nenhum item é processado.

Endpoint

POST/api/v1/integration/balances/batch

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
(root)	Lista de saldos	Array	Sim	Não pode ser array vazio
[].cpf_cnpj	CPF (11 dígitos) ou CNPJ (14 dígitos) do produtor	String	Sim	Deve ser um CPF ou CNPJ válido (com verificação de dígito)
[].crops	Lista de culturas com saldos	Array	Sim	Não pode ser nulo ou vazio
[].crops[].name	Nome da cultura (ex: SOJA, MILHO)	String	Sim	Não pode ser vazio ou nulo
[].crops[].deposit_balance_ton	Saldo em depósito (toneladas)	Number	Sim	Deve ser maior ou igual a zero
[].crops[].to_fix_balance_ton	Saldo a fixar (toneladas)	Number	Sim	Deve ser maior ou igual a zero
[].crops[].total_balance_ton	Saldo total (toneladas)	Number	Sim	Deve ser maior ou igual a zero

Exemplo de Requisição

cURL

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "cpf_cnpj": "52998224725",
      "crops": [
        {
          "name": "SOJA",
          "deposit_balance_ton": 100,
          "to_fix_balance_ton": 200,
          "total_balance_ton": 300
        }
      ]
    },
    {
      "cpf_cnpj": "12345678000195",
      "crops": [
        {
          "name": "MILHO",
          "deposit_balance_ton": 50,
          "to_fix_balance_ton": 100,
          "total_balance_ton": 150
        }
      ]
    }
  ]' \
  "https://api.merx.tech/api/v1/integration/balances/batch"

Java

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

String body = "[{\"cpf_cnpj\": \"52998224725\", \"crops\": [{\"name\": \"SOJA\", \"deposit_balance_ton\": 100, \"to_fix_balance_ton\": 200, \"total_balance_ton\": 300}]}]";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/balances/batch"))
    .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/balances/batch',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([
      {
        cpf_cnpj: '52998224725',
        crops: [
          {
            name: 'SOJA',
            deposit_balance_ton: 100,
            to_fix_balance_ton: 200,
            total_balance_ton: 300,
          },
        ],
      },
    ]),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.merx.tech/api/v1/integration/balances/batch"

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

payload = [
    {
        "cpf_cnpj": "52998224725",
        "crops": [
            {
                "name": "SOJA",
                "deposit_balance_ton": 100,
                "to_fix_balance_ton": 200,
                "total_balance_ton": 300
            }
        ]
    }
]

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

Exemplo de Requisição (cURL legado)

curl -X POST "https://api.merx.tech/api/v1/integration/balances/batch" \
-H "Authorization: {SUA_API_KEY}" \
-H "Content-Type: application/json" \
-d '[
    {
        "cpf_cnpj": "52998224725",
        "crops": [
            {
                "name": "SOJA",
                "deposit_balance_ton": 100,
                "to_fix_balance_ton": 200,
                "total_balance_ton": 300
            }
        ]
    },
    {
        "cpf_cnpj": "12345678000195",
        "crops": [
            {
                "name": "MILHO",
                "deposit_balance_ton": 50,
                "to_fix_balance_ton": 100,
                "total_balance_ton": 150
            }
        ]
    }
]'

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

Array de objetos de saldo. Cada objeto segue a mesma estrutura do endpoint singular.

Nome	Descrição	Tipo	Obrigatório
[].cpf_cnpj	CPF ou CNPJ do produtor	String	Sim
[].crops	Lista de culturas com saldos	Array	Sim
[].crops[].name	Nome da cultura	String	Sim
[].crops[].deposit_balance_ton	Saldo em depósito (toneladas)	Number	Sim
[].crops[].to_fix_balance_ton	Saldo a fixar (toneladas)	Number	Sim
[].crops[].total_balance_ton	Saldo total (toneladas)	Number	Sim

Respostas

• 200 - OK

Response sem body (HTTP 200 com corpo vazio).

• 400 - Bad Request

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

Cenário	Mensagem de erro
Array vazio	batch cannot be empty
CPF/CNPJ inválido em item	Item at index {n}: cpf_cnpj is invalid
Array crops vazio em item	Item at index {n}: crops cannot be empty

Nota: O índice é zero-based (o primeiro item é index 0). Se múltiplos itens possuem erros, todos são reportados. O rollback é total: se qualquer item falhar, nenhum item é processado.

• 415 - Unsupported Media Type

Content-Type diferente de application/json.