Guia: Comercial

Fluxo para criar negociações, registrar entregas e rastreabilidade.

Mapa de dependências

A negociação (order-commitment) é o ponto central. A entrega pode ser independente (basta um contract_id conhecido) e a rastreabilidade exige uma negociação existente.

Pré-requisitos

Antes de criar uma negociação, os seguintes registros do guia de Cadastros devem existir:

Registro	Usado em	Referência
Produtor (producer_id)	order-commitments, traceability	Cadastros §1
Emissor (issuer_id — UUID de um usuário)	order-commitments	—
Carteira vinculada ao Produtor (wallet_id)	order-commitments	Cadastros §4
Local de Entrega (delivery_place_id)	order-commitments	Cadastros §6

1. Criar negociação

Endpoint: POST /api/v1/integration/order-commitments

Campos obrigatórios em qualquer order_type: amount, producer_id, issuer_id, product, delivery_place_id, haverst, unit_of_measurement, order_type, order_date, wallet_id. Os campos currency, price, initial_delivery_date, end_delivery_date, modality, payday, payment_type são condicionais — obrigatórios para order_type = COMPRA, opcionais para A_FIXAR.

Atenção ao campo haverst (sim, com esse nome no contrato): é o nome oficial do atributo da safra na API.

curl -X POST \
  https://api.merx.tech/api/v1/integration/order-commitments \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000.00,
    "producer_id": "{producer_id}",
    "issuer_id": "{user_id}",
    "product": "SOJA",
    "delivery_place_id": "{delivery_place_id}",
    "haverst": "2024/2025",
    "unit_of_measurement": "SC",
    "order_type": "COMPRA",
    "order_date": "2024-06-30",
    "wallet_id": "{wallet_id}",
    "currency": "BRL",
    "price": 85.00,
    "initial_delivery_date": "2024-10-01",
    "end_delivery_date": "2024-11-30",
    "modality": "DISPONIVEL",
    "payday": "2024-12-15",
    "payment_type": "DINHEIRO"
  }'

Enums principais:

• product: SOJA, TRIGO, MILHO
• unit_of_measurement: SC, KG, TON
• order_type: COMPRA, FIXACAO_COMPRA, FIXACAO_DEPOSITO, A_FIXAR
• modality: BALCAO, DISPONIVEL, FUTURO, EXPORTACAO
• currency: BRL, USD, EUR
• payment_type: DINHEIRO, TROCA

Response: {"id": "uuid-da-negociação"} — guarde como order_commitment_id. Detalhes completos em Criar Negociação.

2. Registrar entrega

Endpoint: POST /api/v1/integration/deliveries

A entrega se associa a uma negociação via contract_id (identificador do contrato, String).

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

Campos obrigatórios: contract_id, delivered_volume, delivered_volume_unit_of_measure (valores: kg, sc, ton), delivery_date (formato YYYY-MM-DD). O campo car é opcional e, quando informado, vincula a entrega a uma propriedade.

Response 201 Created: {"id": "...", "contract_id": "...", "delivered_volume": ..., ...}. Detalhes em Registrar Entrega.

3. Registrar rastreabilidade

Endpoint: POST /api/v1/integration/traceability/-/commitments/{order_commitment_id}

O order_commitment_id vai no path. No body, producer_id e user_id são obrigatórios; farm_id, allocated_volume e unit_of_measurement são opcionais.

curl -X POST \
  https://api.merx.tech/api/v1/integration/traceability/-/commitments/{order_commitment_id} \
  -H "Authorization: {SUA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "farm_id": "{farm_id}",
    "producer_id": "{producer_id}",
    "user_id": "{user_id}",
    "allocated_volume": 123.12,
    "unit_of_measurement": "SC"
  }'

unit_of_measurement: SC, KG, TON (padrão TON).

Response: {"id": "uuid-da-rastreabilidade"}. Detalhes em Criar Rastreabilidade.

4. Consultar negociação

curl -X GET \
  https://api.merx.tech/api/v1/integration/order-commitments/{order_commitment_id} \
  -H "Authorization: {SUA_API_KEY}"

Ver também: listagem paginada e detalhes por código ERP.

Erros comuns

Erro	Causa	Solução
{"messages": ["message.wallet.not-found"]}	wallet_id inválido	Crie a carteira em Cadastros §4
{"messages": ["message.wallet.producer-not-linked"]}	Produtor não vinculado à carteira	Execute o POST de vínculo em Cadastros §4
{"messages": ["message.producer.not-found"]}	producer_id inválido	Verifique o UUID do produtor
{"messages": ["message.delivery-place.not-found"]}	delivery_place_id inválido	Cadastre o local em Cadastros §6
400 com campo-inválido em COMPRA	Falta um dos campos condicionais (currency, price, modality, payday, payment_type, initial_delivery_date, end_delivery_date)	Inclua todos os campos condicionais obrigatórios para order_type = COMPRA