Criar Nova Negociação

Descrição: Cria uma nova negociação para um usuário específico.

Endpoint

POST/api/v1/integration/order-commitments

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
amount	Volume	Number	Sim	Quantidade referente a unidade de medida escolhida
producer_id	Id do produtor vinculado a negociação	UUID	Sim	Verifica se é válido
issuer_id	Id do emissor da negociação	UUID	Sim	Verifica se é válido
currency	Moeda escolhida para negociação	String	Condicional	Código da moeda (ex.: BRL). Campo de texto livre — a API não valida os valores contra uma lista fixa. O valor é resolvido por busca do código. Obrigatório para os tipos COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA e FIXACAO_DEPOSITO; opcional para ANTECIPACAO e A_FIXAR.
product	Produto negociado	String	Sim	Nome do produto (ex.: SOJA). Campo de texto livre — a API não valida os valores contra uma lista fixa. O valor é resolvido por busca do nome.
delivery_place_id	Id da unidade de entrega	UUID	Sim	Verifica se é válido
initial_delivery_date	Data inicial da entrega	Date	Condicional	Utilizar o padrão YYYY-MM-DD. Obrigatório apenas quando order_type é COMPRA ou VENDA; opcional para todos os demais tipos.
end_delivery_date	Data final da entrega	Date	Condicional	Utilizar o padrão YYYY-MM-DD. Obrigatório apenas quando order_type é COMPRA ou VENDA; opcional para todos os demais tipos.
haverst	Safra do produto negociado	String	Sim	Seguir o padrão 'ano/ano' ou 'ano - Safrinha'. Ex: 2021/2022
modality	Modalidade da negociação	Enum	Condicional	BALCAO, DISPONIVEL, FUTURO, EXPORTACAO. Obrigatório para os tipos COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA e FIXACAO_DEPOSITO; opcional para ANTECIPACAO e A_FIXAR.
payday	Data do pagamento	Date	Condicional	Utilizar o padrão YYYY-MM-DD. Obrigatório para os tipos COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA e FIXACAO_DEPOSITO; opcional para ANTECIPACAO e A_FIXAR.
payment_type	Tipo do pagamento	Enum	Condicional	DINHEIRO, TROCA. Obrigatório para os tipos COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA e FIXACAO_DEPOSITO; opcional para ANTECIPACAO e A_FIXAR.
order_type	Tipo da negociação	Enum	Sim	COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA, FIXACAO_DEPOSITO, ANTECIPACAO, A_FIXAR. `FIXACAO_COMPRA` é convertido para `FIXACAO_VENDA` antes de gravar, então a consulta devolve o tipo convertido. E em `FIXACAO_VENDA`, `FIXACAO_DEPOSITO` e `A_FIXAR` o objeto `shipping` é descartado sem erro
order_date	Data do pedido	Date	Sim	Formatos aceitos: YYYY-MM-DD e ISO 8601 (Ex.: 2024-02-21T00:00:00Z)
price	Preço por cada unidade de medida	Number	Condicional	Utilizar o valor com duas casas decimais. Ex: 130.33. Obrigatório para os tipos COMPRA, VENDA, FIXACAO_COMPRA, FIXACAO_VENDA e FIXACAO_DEPOSITO; opcional para ANTECIPACAO e A_FIXAR.
unit_of_measurement	Unidade de medida	String	Sim	Código da unidade (ex.: SC, KG, TON). Campo de texto livre — a API não valida os valores contra uma lista fixa.
price_unit_of_measurement	Unidade de medida de preço	String	Não	Código da unidade (ex.: SC, KG, TON). Campo de texto livre — a API não valida os valores contra uma lista fixa. Quando não preenchido, recebe o mesmo valor de unit_of_measurement — exceto quando order_type é A_FIXAR, caso em que permanece nulo.
shipping.type	Modalidade de frete	Enum	Condicional	FOB, CIF, TPT, SOT. Caso o campo order_type seja "COMPRA", o objeto shipping e este atributo passam a ser obrigatórios. A disponibilidade de cada modalidade depende do cadastro do ambiente; outras modalidades existentes na plataforma não são aceitas por esta API. Se a modalidade informada não estiver cadastrada no ambiente, a negociação é criada sem frete e a requisição ainda responde 200. Atenção: quando este campo falta, a chave devolvida é `message.shipping.state.mandatory` — a mensagem aponta o estado, não o tipo.
shipping.city	Cidade em que o produto será entregue	String	Condicional	Até 50 caracteres — o limite é aplicado pelo serviço de negociações, que devolve 400 `message.city.length`. Obrigatório apenas quando order_type é "COMPRA" e shipping.type é FOB.
shipping.state	Estado em que o produto será entregue	String	Condicional	UF. Ex: SP. Até 50 caracteres, limite aplicado pelo serviço de negociações (400 `message.state.length`). Obrigatório apenas quando order_type é "COMPRA" e shipping.type é FOB.
shipping.price	Custo do frete	Number	Não	Utilizar o valor com duas casas decimais. Ex: 950.33
shipping.description	Descrição do frete	String	Não	Até 1000 caracteres, limite aplicado pelo serviço de negociações (400 `message.description.length`)
internal_id	Código da negociação no erp do cliente	String	Não	Sem limite de tamanho validado pela API. Precisa ser único na cooperativa: se já existir negociação com o mesmo código, a criação é recusada com 400 `message.internal-id.already.exists`
description	Descrição	String	Não	Até 1000 caracteres, limite aplicado pelo serviço de negociações (400 `message.description.length`)
wallet_id	Identificador da carteira vinculada a negociação	UUID	Sim	Verifica se é válido

Exemplo de Requisição

cURL
Java
JavaScript
Python
SDK Java

curl -X POST \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "producer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "issuer_id": "4fb96a75-6828-5673-c4ad-3d074a77bab7",
    "product": "SOJA",
    "delivery_place_id": "5bc07b86-7939-6784-d5be-4e185b88cbc8",
    "haverst": "2024/2025",
    "unit_of_measurement": "SC",
    "order_type": "COMPRA",
    "order_date": "2024-06-30",
    "wallet_id": "6cd18c97-8040-7895-e6cf-5f296c99d1d1",
    "currency": "BRL",
    "initial_delivery_date": "2024-10-01",
    "end_delivery_date": "2024-11-30",
    "modality": "DISPONIVEL",
    "payday": "2024-12-15",
    "payment_type": "DINHEIRO",
    "price": 85.00,
    "shipping": {
      "type": "FOB",
      "city": "Sorriso",
      "state": "MT"
    }
  }' \
  "https://api.merx.tech/api/v1/integration/order-commitments"

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

String body = "{\"amount\": 1000.00, \"producer_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"issuer_id\": \"4fb96a75-6828-5673-c4ad-3d074a77bab7\", \"product\": \"SOJA\", \"delivery_place_id\": \"5bc07b86-7939-6784-d5be-4e185b88cbc8\", \"haverst\": \"2024/2025\", \"unit_of_measurement\": \"SC\", \"order_type\": \"COMPRA\", \"order_date\": \"2024-06-30\", \"wallet_id\": \"6cd18c97-8040-7895-e6cf-5f296c99d1d1\", \"currency\": \"BRL\", \"initial_delivery_date\": \"2024-10-01\", \"end_delivery_date\": \"2024-11-30\", \"modality\": \"DISPONIVEL\", \"payday\": \"2024-12-15\", \"payment_type\": \"DINHEIRO\", \"price\": 85.00, \"shipping\": {\"type\": \"FOB\", \"city\": \"Sorriso\", \"state\": \"MT\"}}";

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/order-commitments"))
    .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/order-commitments',
  {
    method: 'POST',
    headers: {
      'Authorization': '{SUA_API_KEY}',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 1000.00,
      producer_id: '3fa85f64-5717-4562-b3fc-2c963f66afa6',
      issuer_id: '4fb96a75-6828-5673-c4ad-3d074a77bab7',
      product: 'SOJA',
      delivery_place_id: '5bc07b86-7939-6784-d5be-4e185b88cbc8',
      haverst: '2024/2025',
      unit_of_measurement: 'SC',
      order_type: 'COMPRA',
      order_date: '2024-06-30',
      wallet_id: '6cd18c97-8040-7895-e6cf-5f296c99d1d1',
      currency: 'BRL',
      initial_delivery_date: '2024-10-01',
      end_delivery_date: '2024-11-30',
      modality: 'DISPONIVEL',
      payday: '2024-12-15',
      payment_type: 'DINHEIRO',
      price: 85.00,
      shipping: {
        type: 'FOB',
        city: 'Sorriso',
        state: 'MT',
      },
    }),
  }
);
const data = await response.json();
console.log(data);

import requests

url = "https://api.merx.tech/api/v1/integration/order-commitments"

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

payload = {
    "amount": 1000.00,
    "producer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "issuer_id": "4fb96a75-6828-5673-c4ad-3d074a77bab7",
    "product": "SOJA",
    "delivery_place_id": "5bc07b86-7939-6784-d5be-4e185b88cbc8",
    "haverst": "2024/2025",
    "unit_of_measurement": "SC",
    "order_type": "COMPRA",
    "order_date": "2024-06-30",
    "wallet_id": "6cd18c97-8040-7895-e6cf-5f296c99d1d1",
    "currency": "BRL",
    "initial_delivery_date": "2024-10-01",
    "end_delivery_date": "2024-11-30",
    "modality": "DISPONIVEL",
    "payday": "2024-12-15",
    "payment_type": "DINHEIRO",
    "price": 85.00,
    "shipping": {
        "type": "FOB",
        "city": "Sorriso",
        "state": "MT"
    }
}

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

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;
import com.merx.sdk.model.order.commitment.CreateOrderCommitmentRequest;
import com.merx.sdk.model.order.commitment.CreateShippingOrderCommitmentRequest;
import com.merx.sdk.model.order.enums.ModalityType;
import com.merx.sdk.model.order.enums.OrderPaymentType;
import com.merx.sdk.model.order.enums.OrderType;
import com.merx.sdk.model.order.enums.ShippingType;
import com.merx.sdk.model.common.IdResponse;
import java.util.UUID;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;

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

IdResponse commitment = merx.orderCommitments().create(CreateOrderCommitmentRequest.builder()
    .amount(new BigDecimal("1000.00"))
    .producerId(UUID.fromString("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
    .issuerId(UUID.fromString("4fb96a75-6828-5673-c4ad-3d074a77bab7"))
    .deliveryPlaceId(UUID.fromString("5bc07b86-7939-6784-d5be-4e185b88cbc8"))
    .walletId(UUID.fromString("6cd18c97-8040-7895-e6cf-5f296c99d1d1"))
    .currency("BRL")
    .product("SOJA")
    .harvest("2024/2025")
    .unitOfMeasurement("SC")
    .orderType(OrderType.COMPRA)
    .orderDate(OffsetDateTime.parse("2024-06-30T00:00:00Z"))
    .initialDeliveryDate(LocalDate.parse("2024-10-01"))
    .endDeliveryDate(LocalDate.parse("2024-11-30"))
    .modality(ModalityType.DISPONIVEL)
    .payday(LocalDate.parse("2024-12-15"))
    .paymentType(OrderPaymentType.DINHEIRO)
    .price(new BigDecimal("85.00"))
    .shipping(CreateShippingOrderCommitmentRequest.builder()
        .type(ShippingType.FOB)
        .city("Sorriso")
        .state("MT")
        .build())
    .build());
System.out.println(commitment.getId());

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	application/json	String	Sim

Parâmetros do Corpo

Nome	Descrição	Tipo	Obrigatório
amount	Quantidade (volume) da negociação	Number	Sim
producer_id	Identificador da Companhia Produtora	UUID	Sim
issuer_id	Identificador do emissor da negociação	UUID	Sim
product	Produto da negociação	String	Sim
delivery_place_id	Identificador do local de entrega	UUID	Sim
haverst	Safra da negociação	String	Sim
unit_of_measurement	Unidade de medida do volume	String	Sim
order_type	Tipo da negociação	Enum	Sim
order_date	Data da negociação (formato yyyy-MM-dd)	String	Sim
wallet_id	Identificador da carteira	UUID	Sim
currency	Moeda da negociação	String	Condicional (obrigatório para COMPRA, VENDA, FIXACAO_*)
initial_delivery_date	Data inicial de entrega (formato yyyy-MM-dd)	String	Condicional (obrigatório para COMPRA, VENDA)
end_delivery_date	Data final de entrega (formato yyyy-MM-dd)	String	Condicional (obrigatório para COMPRA, VENDA)
modality	Modalidade da negociação	Enum	Condicional (obrigatório para COMPRA, VENDA, FIXACAO_*)
payday	Data de pagamento (formato yyyy-MM-dd)	String	Condicional (obrigatório para COMPRA, VENDA, FIXACAO_*)
payment_type	Tipo de pagamento	Enum	Condicional (obrigatório para COMPRA, VENDA, FIXACAO_*)
price	Preço unitário	Number	Condicional (obrigatório para COMPRA, VENDA, FIXACAO_*)
shipping	Dados de frete	Object	Condicional (obrigatório para COMPRA)
shipping.type	Tipo de frete	Enum	Condicional (obrigatório para COMPRA)
shipping.city	Cidade de destino do frete	String	Condicional (obrigatório para COMPRA quando o tipo é FOB)
shipping.state	Estado de destino do frete	String	Condicional (obrigatório para COMPRA quando o tipo é FOB)
shipping.description	Descrição do frete	String	Não
shipping.price	Valor do frete	Number	Não
internal_id	Identificador interno (ERP)	String	Não
description	Descrição da negociação	String	Não
price_unit_of_measurement	Unidade de medida do preço	String	Não

Respostas

200 - OK

{
    "id": "string"
}

400 - Bad Request

{
  "messages": ["message.entidade.campo-inválido"]
}

401 - Unauthorized
404 - Not Found

Emissor informado em issuer_id não encontrado para a cooperativa do token.

{
  "messages": ["message.order-commitment.invalid-issuer"]
}

Criar Nova Negociação

Endpoint​

Regras​

Exemplo de Requisição​

Parâmetros​

Parâmetros de Cabeçalho​

Parâmetros do Corpo​

Respostas​

Endpoint

Regras

Exemplo de Requisição

Parâmetros

Parâmetros de Cabeçalho

Parâmetros do Corpo

Respostas