Processar Saldos por Unidade de Entrega em Lote

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

Para a estrutura de cada item, consulte Processar Saldo de Produtor por Unidade de Entrega.

Endpoint

POST/api/v1/integration/balances/by-delivery-place/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 caracteres) do produtor	String	Sim	Deve ser um CPF ou CNPJ válido (com verificação de dígito). Pontuação é removida antes da validação, então `529.982.247-25` e `52998224725` são equivalentes. CNPJ alfanumérico é aceito: os 12 primeiros caracteres podem conter letras (normalizadas para maiúsculas) e os 2 dígitos verificadores continuam numéricos
`[].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
Java
JavaScript
Python

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
            }
          ]
        }
      ]
    },
    {
      "cpf_cnpj": "12345678000195",
      "crops": [
        {
          "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
            }
          ]
        }
      ]
    }
  ]' \
  "https://api.merx.tech/api/v1/integration/balances/by-delivery-place/batch"

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/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();
}

const response = await fetch(
  'https://api.merx.tech/api/v1/integration/balances/by-delivery-place/batch',
  {
    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);

import requests

url = "https://api.merx.tech/api/v1/integration/balances/by-delivery-place/batch"

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/batch" \
-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
                    }
                ]
            }
        ]
    },
    {
        "cpf_cnpj": "12345678000195",
        "crops": [
            {
                "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

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

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[].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
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`
Array `delivery_places` vazio em item	`Item at index {n}: delivery_places cannot be empty`
`delivery_place_id` ausente em item	`Item at index {n}: delivery_place_id is required`

Nota: O índice é zero-based (o primeiro item é index 0). Se múltiplos itens possuem erros, todos são reportados. Apenas a validação é all-or-nothing: todos os itens são validados antes de qualquer processamento, portanto um erro de validação em qualquer item impede o processamento do lote inteiro. Não há transação no processamento: se um item falhar em tempo de execução no meio do lote (por exemplo, produtor ou produto inexistente), os itens processados antes dele permanecem gravados e não são revertidos.

404 - Not Found

Produtor ou produto (cultura) não encontrado para a cooperativa informada. Como esse erro só é detectado durante o processamento, ele pode ocorrer no meio do lote — nesse caso os itens processados antes do item que falhou permanecem gravados.

Cenário	Mensagem de erro
Produtor não encontrado	`message.producer.not-found`
Cultura/produto não encontrado	`message.product.not-found`

415 - Unsupported Media Type

Content-Type diferente de application/json.

Processar Saldos por Unidade de Entrega em Lote

Endpoint​

Regras​

Exemplo de Requisição​

Parâmetros​

Parâmetros de Cabeçalho​

Parâmetros do Corpo​

Respostas​