Alteração de Negociação

Descrição: Informações atualizadas de uma Negociação quando editada dentro da plataforma Merx. Este payload é enviado pelo servidor Merx ao endpoint cadastrado no webhook quando uma negociação é alterada.

Payload Recebido

Payload recebido pelo seu servidor

{
  "commitment_id": "7ee50d8f-9ec9-4668-a03f-e424993eb886",
  "commitment_friendly_id": "240228D0DW3OOV",
  "commitment_fixed_amount": 125.0,
  "commitment_status": "OPEN",
  "price": 100.0,
  "cooperative_id": "8c2db7cc-1020-4423-98cc-02e829299e40",
  "issuer_id": "4b5e9d45-da34-460f-98b9-bbd92f847c3b",
  "issuer_name": "Usucom Cpfcinco",
  "cooperative_name": "Cooperativa Exemplo",
  "owner_id": "8c2db7cc-1020-4423-98cc-02e829299e40",
  "owner_name": "Cooperativa Exemplo",
  "description": "202020",
  "payday": "2024-12-15",
  "type": "COMPRA",
  "status": "OPEN",
  "unit_of_measurement": {
    "id": "7af33d9f-baaf-4e90-a44e-b3a5307d4989",
    "code": "Sc",
    "enabled": false,
    "removed": false
  },
  "price_unit_of_measurement": {
    "id": "7af33d9f-baaf-4e90-a44e-b3a5307d4989",
    "code": "Sc",
    "enabled": false,
    "removed": false
  },
  "delivery_place": {
    "id": "e0b2ad8f-209d-4690-aff6-87d2e24438d8",
    "place": "Cariri",
    "enabled": false,
    "removed": false
  },
  "created_at": 1.734102E9,
  "updated_at": 1.734102E9,
  "fixed_amount_measurement_reference": 125.0,
  "delivered_amount": 125.0,
  "total_price_commitment": 12500.0,
  "original_amount": 125.0,
  "shipping_detail_id": "a1215ba9-80bf-4f60-8abb-fa1b7342daeb",
  "committed_id": "b2f1c9e4-7d3a-4e58-9f21-6c8d0a5b7e33",
  "producer_id": "b2f1c9e4-7d3a-4e58-9f21-6c8d0a5b7e33",
  "initial_delivery_date": 1734048000000,
  "end_delivery_date": 1734048000000,
  "friendly_id": "240228D0DW3OOV",
  "erp_commitment_id": "ERP-REF-12345",
  "wallets": [
    {
      "id": "fc0a1c0f-6d12-46c7-9249-6f6f855c9ef2",
      "name": "Carteira Automação"
    }
  ],
  "wallet_id": "fc0a1c0f-6d12-46c7-9249-6f6f855c9ef2",
  "harvest": {
    "id": "7279dcf4-9b1c-49f5-bd16-660fc7711060",
    "name": "2022/2023"
  },
  "shipping_detail": {
    "description": "Frete por conta do comprador",
    "shipping": {
      "id": "9f5f9649-5814-470c-bac9-a871b41ad348",
      "name": "CIF"
    },
    "city": "Goiânia",
    "state": "GO",
    "price": 0.0
  },
  "modality": {
    "id": "e546a0b5-f32e-4787-a5ca-9104664c1ba5",
    "name": "Disponível"
  },
  "product": {
    "id": "3281a9df-8312-4483-968b-479e793ef960",
    "name": "Soja",
    "enabled": false,
    "removed": false
  },
  "currency": {
    "id": "882bdbf7-922d-4f94-8deb-b3b24433d63d",
    "code": "BRL",
    "enabled": false,
    "removed": false
  },
  "payment_type": "DINHEIRO"
}

As chaves nulas não são entregues. Antes de sair, o corpo é desserializado e reserializado pela API de integração, que omite campos sem valor — inclusive dentro de objetos aninhados e de itens de lista. Ou seja: campo ausente significa "sem valor", e o seu parser não deve exigir a presença de nenhuma chave opcional.

Formatos de número e data neste payload. payday chega como string yyyy-MM-dd. created_at e updated_at são epoch em segundos, emitidos em notação científica (1.7341020001234567E9) — a reserialização os converte para ponto flutuante. A fração de segundo sobrevive; a forma curta 1.734102E9 só aparece quando a fração é exatamente zero, que é exceção. initial_delivery_date e end_delivery_date são epoch em milissegundos, inteiros. Valores decimais também passam por ponto flutuante e perdem a escala original (125.00 chega como 125.0).

Campos do payload

A coluna Presença diz quando esperar cada campo. Onde está Nunca, o campo existe no contrato mas a plataforma não o preenche hoje — a chave simplesmente não chega.

Campo	Descrição	Tipo	Presença
commitment_id	Identificador da negociação	UUID	Sempre
commitment_friendly_id	Código amigável da negociação	String	Sempre
commitment_fixed_amount	Volume fixado	Number	Sempre
total_contractual_pending	Total contratual pendente	Integer	Nunca
commitment_status	Situação da negociação — mesma origem de status	String	Sempre
price	Preço por unidade de medida	Number	Sempre
cooperative_id	Identificador da cooperativa	UUID	Sempre
issuer_id	Identificador de quem emitiu	String	Sempre
issuer_name	Nome de quem emitiu	String	Quando disponível
issuer_email	E-mail de quem emitiu	String	Nunca
cooperative_name	Nome da cooperativa	String	Quando disponível
owner_id	Preenchido com o identificador da cooperativa — igual a cooperative_id	UUID	Sempre
owner_name	Nome da cooperativa — mesma origem de cooperative_name	String	Quando disponível
description	Descrição da negociação	String	Quando preenchida
payday	Data de pagamento — string yyyy-MM-dd	String	Quando preenchida
type	Tipo da negociação	String	Sempre
status	Situação — mesma origem de commitment_status	String	Sempre
unit_of_measurement	Unidade de medida do volume — só id e code são preenchidos	Object	Sempre
price_unit_of_measurement	Unidade de medida do preço — só id e code são preenchidos	Object	Sempre
delivery_place	Local de entrega — place depende de consulta ao cadastro	Object	Sempre
removed	Indica remoção lógica	Boolean	Nunca
created_at	Criação — epoch em segundos, notação científica	Number	Sempre
updated_at	Última atualização — epoch em segundos, notação científica	Number	Sempre
commitment_amount	Volume negociado	Number	Nunca
fixed_amount_measurement_reference	Volume fixado na unidade de referência	Number	Sempre
delivered_amount	Volume entregue	Number	Sempre
total_price_commitment	Valor total da negociação	Number	Sempre
original_amount	Volume original da negociação	Number	Sempre
shipping_detail_id	Identificador do detalhe de frete	UUID	Sempre
order_friendly_id	Código amigável da ordem	String	Nunca
committed_at	Data em que foi negociada	Number	Nunca
committed_id	Identificador do produtor — mesma origem de producer_id	UUID	Sempre
producer_id	Identificador do produtor — mesma origem de committed_id	UUID	Sempre
commitment_user_name	Nome do usuário que negociou	String	Nunca
initial_delivery_date	Data inicial de entrega — epoch em milissegundos	Number	Quando preenchida
end_delivery_date	Data final de entrega — epoch em milissegundos	Number	Quando preenchida
parent_id	Identificador da negociação de origem	UUID	Nunca
friendly_id	Código amigável — mesma origem de commitment_friendly_id	String	Sempre
committed_company_name	Nome da empresa que negociou	String	Nunca
erp_commitment_id	Referência externa no ERP do cliente	String	Quando preenchida
wallets	Carteiras vinculadas — só id e name são preenchidos	Array	Quando há carteira
wallet_id	Identificador da carteira	UUID	Quando há carteira
harvest	Safra — só id e name são preenchidos	Object	Sempre
shipping_detail	Frete (description, shipping, city, state, price)	Object	Quando há frete
modality	Modalidade — só id e name são preenchidos	Object	Sempre
product	Produto — só id e name são preenchidos	Object	Sempre
currency	Moeda — só id e code são preenchidos	Object	Sempre
buyer	Comprador	String	Nunca
seller	Vendedor	String	Nunca
payment_type	Tipo de pagamento: DINHEIRO ou TROCA	Enum	Sempre

Objetos podem chegar vazios. harvest, modality e currency são sempre enviados, mas o conteúdo depende da referência existir. Sem safra ou modalidade associada, harvest e modality chegam como {}. Já currency nunca chega vazio: os campos enabled e removed dele são booleanos primitivos, que a omissão de nulos não suprime, então sem moeda associada ele chega como {"enabled": false, "removed": false}.

Três campos repetem o mesmo dado. commitment_status e status vêm da mesma coluna; commitment_friendly_id e friendly_id também; e committed_id e producer_id recebem ambos o identificador do produtor. Não trate como informações distintas.

enabled e removed dentro dos objetos aninhados chegam sempre com o valor false. Esse false é o padrão do tipo no serviço de origem, que não lê essas colunas do banco — não representa o estado real do cadastro, e não deve ser usado para decidir se um registro está ativo ou removido.

Entrega

Este payload chega ao seu endpoint com os headers Content-Type: application/json, app-hash (identificador da cooperativa), event-type (o tipo do evento), Content-Hmac (assinatura sempre enviada, que não serve para validar a entrega — ver o Guia: Webhooks) e, se basic_authentication estiver configurado no webhook, Authorization: Basic <base64>.

O endpoint precisa responder 2xx em menos de 5 segundos. Responder 5xx devolve a mensagem à fila; responder 4xx encerra a entrega. Ver Guia: Webhooks — Requisitos do endpoint receptor.