Registrar Entregas em Lote

Descrição: Registra uma lista de entregas. Comportamento de rollback total: se qualquer item falhar na validação, nenhum registro é criado.

Endpoint

POST/api/v1/integration/deliveries/batch

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
(root)	Lista de entregas	Array	Sim	Não pode ser array vazio
[].contract_id	Identificador do contrato	String	Sim	Não pode ser vazio ou nulo
[].delivered_volume	Volume entregue	Number	Sim	Deve ser maior que zero
[].delivered_volume_unit_of_measure	Unidade de medida do volume	String (enum)	Sim	Valores aceitos: kg, sc, ton
[].delivery_date	Data da entrega	String	Sim	Formato obrigatório: YYYY-MM-DD
[].car	Código CAR (Cadastro Ambiental Rural)	String	Não	-
[].delivery_mode	Modo de entrega. FULL substitui o volume entregue da negociação; PARTIAL incrementa	String (enum)	Não	Valores aceitos: FULL, PARTIAL. Padrão: PARTIAL

Exemplo de Requisição

cURL

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "contract_id": "000122",
      "delivered_volume": 10,
      "delivered_volume_unit_of_measure": "ton",
      "delivery_date": "2026-03-02"
    },
    {
      "contract_id": "000123",
      "delivered_volume": 500,
      "delivered_volume_unit_of_measure": "sc",
      "delivery_date": "2026-03-03",
      "car": "GO-5201405-XYZ987"
    }
  ]' \
  "https://api.merx.tech/api/v1/integration/deliveries/batch"

Java

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

String body = "[{\"contract_id\": \"000122\", \"delivered_volume\": 10, \"delivered_volume_unit_of_measure\": \"ton\", \"delivery_date\": \"2026-03-02\"}]";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/deliveries/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/deliveries/batch',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([
      {
        contract_id: '000122',
        delivered_volume: 10,
        delivered_volume_unit_of_measure: 'ton',
        delivery_date: '2026-03-02',
      },
      {
        contract_id: '000123',
        delivered_volume: 500,
        delivered_volume_unit_of_measure: 'sc',
        delivery_date: '2026-03-03',
        car: 'GO-5201405-XYZ987',
      },
    ]),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

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

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

payload = [
    {
        "contract_id": "000122",
        "delivered_volume": 10,
        "delivered_volume_unit_of_measure": "ton",
        "delivery_date": "2026-03-02"
    },
    {
        "contract_id": "000123",
        "delivered_volume": 500,
        "delivered_volume_unit_of_measure": "sc",
        "delivery_date": "2026-03-03",
        "car": "GO-5201405-XYZ987"
    }
]

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

SDK Java

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;
import com.merx.sdk.model.order.delivery.CreateDeliveryRequest;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .environment(Environment.SANDBOX)
    .build();

var deliveries = merx.deliveries().createBatch(List.of(CreateDeliveryRequest.builder()
    .contractId("CONTRATO-123")
    .deliveredVolume(new BigDecimal("100"))
    .deliveryDate(LocalDate.parse("2024-01-10"))
    .build()));

Exemplo de Requisição (cURL legado)

curl -X POST "https://api.merx.tech/api/v1/integration/deliveries/batch" \
-H "Authorization: {SUA_API_KEY}" \
-H "Content-Type: application/json" \
-d '[
    {
        "contract_id": "000122",
        "delivered_volume": 10,
        "delivered_volume_unit_of_measure": "ton",
        "delivery_date": "2026-03-02"
    },
    {
        "contract_id": "000123",
        "delivered_volume": 500,
        "delivered_volume_unit_of_measure": "sc",
        "delivery_date": "2026-03-03",
        "car": "GO-5201405-XYZ987"
    }
]'

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 entrega. Cada objeto segue a mesma estrutura do endpoint singular.

Nome	Descrição	Tipo	Obrigatório
[].contract_id	Identificador do contrato	String	Sim
[].delivered_volume	Volume entregue	Number	Sim
[].delivered_volume_unit_of_measure	Unidade de medida do volume	String (enum)	Sim
[].delivery_date	Data da entrega (formato YYYY-MM-DD)	String	Sim
[].car	Código CAR (Cadastro Ambiental Rural)	String	Não
[].delivery_mode	Modo de entrega (FULL ou PARTIAL). Padrão: PARTIAL	String (enum)	Não

Respostas

• 201 - Created

[
    {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "contract_id": "000122",
        "delivered_volume": 10,
        "delivered_volume_unit_of_measure": "ton",
        "delivery_date": "2026-03-02"
    },
    {
        "id": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
        "contract_id": "000123",
        "delivered_volume": 500,
        "delivered_volume_unit_of_measure": "sc",
        "delivery_date": "2026-03-03",
        "car": "GO-5201405-XYZ987"
    }
]

Atenção: assim como no endpoint singular, o id de cada item não é persistido. Ele é gerado no momento da resposta, não identifica nenhum recurso consultável na plataforma e não serve como chave de idempotência. O efeito real de cada item é atualizar o volume entregue da negociação correspondente.

• 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
Item inválido (identifica índice)	Item at index {n}: delivered_volume must be greater than zero
Unidade inválida em item	Item at index {n}: delivered_volume_unit_of_measure must be one of: kg, sc, ton

Nota: O índice é zero-based (o primeiro item é index 0). 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, contract_id sem negociação correspondente), as atualizações de volume dos itens aplicados antes dele permanecem e não são revertidas.

• 404 - Not Found

Nenhuma negociação encontrada para o contract_id de algum item do lote. Como essa verificação só acontece durante o processamento, o erro pode ocorrer no meio do lote — nesse caso as atualizações dos itens aplicados antes dele permanecem.

Cenário	Mensagem de erro
contract_id sem negociação correspondente	message.order-commitment.not-found

• 415 - Unsupported Media Type

Content-Type diferente de application/json.