Comodatos

A YOM notifica o sistema do cliente sobre cada solicitação de comodato registrada pelos vendedores no aplicativo ou pelos comércios na plataforma B2B. O comodato é um equipamento que o cliente entrega em empréstimo ao comércio — um freezer, um refrigerador, um expositor —, e a solicitação é o formulário com o qual essa entrega é pedida.

Quando a solicitação é registrada, e cada vez que é modificada depois, a YOM envia uma chamada HTTP POST ao endpoint do cliente com o detalhe do Comércio e as respostas do formulário.

O mesmo endpoint recebe os cadastros e as modificações. Cada mensagem traz o identificador da solicitação em comodatoId, e o sistema do cliente deve tratá-lo como um upsert: registrar a solicitação se for a primeira vez que vê esse identificador, ou substituí-la se já a conhece.

<aside> ⚙️

O módulo de comodatos é habilitado por cliente a partir da YOM. Para ativá-lo é preciso informar à YOM a URL do endpoint de recebimento e as credenciais com as quais a YOM deve se autenticar nele. Os requisitos gerais de autenticação e formato estão em Requisitos técnicos

</aside>

Quando a YOM o chama

Cadastro pelo aplicativo do vendedor, quando o vendedor envia o formulário no ponto de venda → eventType: "created".
Cadastro pela plataforma B2B, quando o próprio comércio registra a solicitação → eventType: "created".
Modificação de uma solicitação existente, quando suas respostas são corrigidas → eventType: "updated".

<aside> ⚠️

As solicitações que o próprio cliente carrega na YOM em lote não geram nenhuma chamada. Devolvê-las duplicaria no ERP o que o cliente acabou de enviar.

</aside>

<aside> ℹ️

O formulário de comodato é configurável por cliente: os campos, suas opções e sua obrigatoriedade são definidos na YOM. Por isso o conteúdo de responses muda de um cliente para outro, e este documento descreve o formato de cada resposta, não a lista de perguntas.

</aside>

Endpoint

POST <tu_dominio>/webhooks/yom/comodatos

Corpo da requisição

{
  "eventType": "created",
  "comodatoId": "66f0a1b2c3d4e5f6a7b8c9d0",
  "externalId": "COM-000123",
  "commerce": { ... },
  "responses": [ ... ]
}

Campos

Solicitação de comodato

O corpo da mensagem.

Campo	Tipo	Obrigatoriedade	Descrição	Exemplos
`eventType`	📝 Texto	🟢 Obrigatório	O que originou a chamada.
`"created"` → a solicitação acabou de ser registrada
`"updated"` → as respostas de uma solicitação já enviada foram modificadas	`"created"`
`comodatoId`	📝 Texto	🟢 Obrigatório	Identificador único da Solicitação de comodato na YOM. É a chave do upsert: nunca muda e é o mesmo no cadastro e em todas as suas modificações posteriores.	`"66f0a1b2c3d4e5f6a7b8c9d0"`
`externalId`	📝 Texto	⚪ Opcional	Código da Solicitação no sistema do cliente. Só viaja nas solicitações que o próprio cliente carregou na YOM; as que um vendedor ou um comércio registra não têm nenhum.	`"COM-000123"`
`commerce`	📝 Objeto → Commerce	🟢 Obrigatório	O Comércio que recebe o equipamento, completo. Seu código no sistema do cliente está em `contact.externalId`. Ver detalhe abaixo.
`responses`	🔡 Lista de Objetos → Response	🟢 Obrigatório	As respostas do formulário. Ver detalhe abaixo.

Response

Cada resposta de responses. A lista chega ordenada igual ao formulário na tela e contém apenas os campos visíveis que foram respondidos: os campos opcionais não respondidos e os que ficaram ocultos pela lógica condicional do formulário não viajam.

| --- | --- | --- | --- | --- |