Processar Saldo de Produtor por Unidade de Entrega

Descrição: Processa o saldo de um produtor por unidade de entrega (delivery_place_id). Endpoint separado do Processar Saldo de Produtor para manter compatibilidade com integrações que enviam saldo agregado por cultura.

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

Importante: delivery_place_id é o identificador da Unidade de Entrega cadastrada via API de Locais de entrega. Não corresponde ao domínio de armazém (warehouse) do baseline.

Endpoint

POST/api/v1/integration/balances/by-delivery-place

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[].delivery_places	Lista de saldos por unidade de entrega	Array	Sim	Não pode ser nulo ou vazio
crops[].delivery_places[].delivery_place_id	ID da unidade de entrega	UUID	Sim	Deve ser um UUID válido retornado por Buscar Unidades de Entrega
crops[].delivery_places[].deposit_balance_ton	Saldo em depósito (toneladas)	Number	Sim	Deve ser maior ou igual a zero
crops[].delivery_places[].to_fix_balance_ton	Saldo a fixar (toneladas)	Number	Sim	Deve ser maior ou igual a zero
crops[].delivery_places[].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",
        "delivery_places": [
          {
            "delivery_place_id": "1c2db7cc-1020-4423-98cc-02e829299e49",
            "deposit_balance_ton": 100,
            "to_fix_balance_ton": 200,
            "total_balance_ton": 300
          },
          {
            "delivery_place_id": "ad2db7cc-1020-4423-98cc-02e829299e49",
            "deposit_balance_ton": 200,
            "to_fix_balance_ton": 400,
            "total_balance_ton": 600
          }
        ]
      }
    ]
  }' \
  "https://api.merx.tech/api/v1/integration/balances/by-delivery-place"

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\", \"delivery_places\": [{\"delivery_place_id\": \"1c2db7cc-1020-4423-98cc-02e829299e49\", \"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/by-delivery-place"))
    .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/by-delivery-place',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      cpf_cnpj: '52998224725',
      crops: [
        {
          name: 'SOJA',
          delivery_places: [
            {
              delivery_place_id: '1c2db7cc-1020-4423-98cc-02e829299e49',
              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/by-delivery-place"

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

payload = {
    "cpf_cnpj": "52998224725",
    "crops": [
        {
            "name": "SOJA",
            "delivery_places": [
                {
                    "delivery_place_id": "1c2db7cc-1020-4423-98cc-02e829299e49",
                    "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/by-delivery-place" \
-H "Authorization: {SUA_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
    "cpf_cnpj": "52998224725",
    "crops": [
        {
            "name": "SOJA",
            "delivery_places": [
                {
                    "delivery_place_id": "1c2db7cc-1020-4423-98cc-02e829299e49",
                    "deposit_balance_ton": 100,
                    "to_fix_balance_ton": 200,
                    "total_balance_ton": 300
                },
                {
                    "delivery_place_id": "ad2db7cc-1020-4423-98cc-02e829299e49",
                    "deposit_balance_ton": 200,
                    "to_fix_balance_ton": 400,
                    "total_balance_ton": 600
                }
            ]
        }
    ]
}'

Com múltiplas culturas:

Exemplo de Requisição com múltiplas culturas

curl -X POST "https://api.merx.tech/api/v1/integration/balances/by-delivery-place" \
-H "Authorization: {SUA_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
    "cpf_cnpj": "52998224725",
    "crops": [
        {
            "name": "SOJA",
            "delivery_places": [
                {
                    "delivery_place_id": "1c2db7cc-1020-4423-98cc-02e829299e49",
                    "deposit_balance_ton": 100,
                    "to_fix_balance_ton": 200,
                    "total_balance_ton": 300
                }
            ]
        },
        {
            "name": "MILHO",
            "delivery_places": [
                {
                    "delivery_place_id": "ad2db7cc-1020-4423-98cc-02e829299e49",
                    "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[].delivery_places	Lista de saldos por unidade de entrega	Array	Sim
crops[].delivery_places[].delivery_place_id	ID da unidade de entrega (Buscar Unidades de Entrega)	UUID	Sim
crops[].delivery_places[].deposit_balance_ton	Saldo em depósito (toneladas)	Number	Sim
crops[].delivery_places[].to_fix_balance_ton	Saldo a fixar (toneladas)	Number	Sim
crops[].delivery_places[].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
Array delivery_places vazio	delivery_places cannot be empty
delivery_place_id ausente	delivery_place_id is required
Valor de saldo negativo	deposit_balance_ton must be greater than or equal to zero
Produtor não encontrado	message.producer.not-found
Cultura/produto não encontrado	message.product.not-found

• 404 - Not Found

Produtor ou produto (cultura) não encontrado para a cooperativa informada.

• 415 - Unsupported Media Type

Content-Type diferente de application/json.