Registrar Entrega

Descrição: Registra o volume entregue de uma negociação. O efeito real da chamada é atualizar o volume entregue da negociação identificada por contract_id.

Atenção: este endpoint não cria um registro de entrega. O campo id devolvido na resposta é gerado no momento da requisição e não é persistido: ele não pode ser consultado depois, não identifica nenhum recurso na plataforma e não serve como chave de idempotência. Reenviar a mesma entrega aplica o volume novamente.

Endpoint

POST/api/v1/integration/deliveries

Regras

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

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"))
    .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',
  {
    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',
    }),
  }
);
const data = await response.json();
console.log(data);

Python

import requests

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

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"
}

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;

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

var delivery = merx.deliveries().create(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" \
-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"
}'

Com CAR:

Exemplo de Requisição com CAR

curl -X POST "https://api.merx.tech/api/v1/integration/deliveries" \
-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",
    "car": "MT-5107602-ABC123456789"
}'

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
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",
    "car": "MT-5107602-ABC123456789"
}

Nota: O campo car só aparece no response quando informado no request (campos nulos são omitidos).

• 400 - Bad Request

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

Cenário	Mensagem de erro
contract_id ausente	contract_id is required
delivered_volume ausente	delivered_volume is required
delivered_volume_unit_of_measure ausente	delivered_volume_unit_of_measure is required
delivery_date ausente	delivery_date is required
Unidade de medida inválida	delivered_volume_unit_of_measure must be one of: kg, sc, ton
Formato de data inválido	delivery_date must follow the format YYYY-MM-DD
Volume negativo ou zero	delivered_volume must be greater than zero
Body vazio ou JSON malformado	message.malformed-request

• 404 - Not Found

Nenhuma negociação encontrada para o contract_id informado.

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.