Processar Saldo de Produtor

Descrição: Processa o saldo de um produtor. Semântica de upsert (chave: cpf_cnpj + cultura). Idempotente na camada de valida�ão — enviar o mesmo payload múltiplas vezes retorna sucesso.

Endpoint

POST/api/v1/integration/balances

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
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
      }
    ]
  }' \
  "https://api.merx.tech/api/v1/integration/balances"

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"))
    .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',
  {
    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"

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" \
-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
        }
    ]
}'

Com múltiplas culturas:

Exemplo de Requisição com múltiplas culturas

curl -X POST "https://api.merx.tech/api/v1/integration/balances" \
-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
        },
        {
            "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

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 (ex: SOJA, MILHO)	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
cpf_cnpj ausente	cpf_cnpj is required
CPF/CNPJ inválido	cpf_cnpj is invalid
crops ausente	crops is required
Array crops vazio	crops cannot be empty
Cultura sem name	name is required
Valor de saldo negativo	deposit_balance_ton must be greater than or equal to zero

• 415 - Unsupported Media Type

Content-Type diferente de application/json.