A YOM pode notificar o sistema do cliente sobre cada solicitação de devolução registrada pelos vendedores ou pelos comércios sobre um pedido já criado. Quando a solicitação é registrada, a YOM envia uma chamada HTTP POST ao endpoint do cliente com o detalhe da devolução, do Order, do Commerce e do Seller.
A devolução é de mercadoria: declara-se quais linhas do pedido são devolvidas, em que quantidade e por qual motivo. A YOM não emite nem administra notas de crédito.
O resultado da revisão é informado pelo cliente de volta à YOM por meio de um webhook de estado, linha por linha.
<aside> ⚙️
O módulo de devoluções é habilitado por cliente a partir da YOM. Para ativá-lo é preciso informar à YOM a URL do endpoint de recebimento; diferentemente de outras integrações, aqui não existe uma rota padrão obrigatória. Os requisitos gerais de autenticação e formato estão em Requisitos técnicos
</aside>
POST <tu_dominio>/webhooks/yom/refunds
Corpo da requisição
{
"refundRequest": { ... },
"order": { ... },
"commerce": { ... },
"seller": { ... }
}
A entidade refundRequest: a solicitação de devolução propriamente dita.
| Campo | Tipo | Obrigatoriedade | Descrição | Exemplos |
|---|---|---|---|---|
requestId |
📝 Texto | 🟢 Obrigatório | Identificador único da Solicitação de devolução. Formato RF-AAAAMMDD-<16 caracteres>. |
|
| É a chave com a qual o cliente responde o resultado da revisão. | "RF-20260914-9f3c1a2b8d4e5f60" |
|||
domain |
📝 Texto | 🟢 Obrigatório | Domínio do cliente ao qual a solicitação pertence. | "cliente.youorder.me" |
externalOrderId |
📝 Texto | ⚪ Opcional | Código do Pedido no sistema do cliente. Identifica o pedido sobre o qual a devolução é pedida. | "PED-000123456" |
orderDate |
📅 Data | ⚪ Opcional | Data de criação do Pedido original, no formato ISO 8601. | "2026-09-10T14:22:31.004Z" |
externalCommerceId |
📝 Texto | ⚪ Opcional | Código do Comércio no sistema do cliente. | "CL-0099231" |
externalSellerId |
📝 Texto | ⚪ Opcional | Código do Vendedor no sistema do cliente. | "V-0451" |
channel |
📝 Texto | 🟢 Obrigatório | Canal a partir do qual a solicitação foi registrada. | |
"app" → aplicativo do vendedor |
||||
"ecommerce" → plataforma do comércio |
"app" |
|||
status |
📝 Texto | 🟢 Obrigatório | Estado geral da solicitação. Nesta chamada é sempre "in_review". |
|
"in_review" · "approved" · "rejected" · "partial" |
||||
| É recalculado a partir do estado de cada linha. | "in_review" |
|||
items |
🔡 Lista de Objetos → RefundItem | 🟢 Obrigatório | Linhas que são devolvidas. Máximo de 200 por solicitação. Ver detalhe abaixo. | |
events |
🔡 Lista de Objetos | ⚪ Opcional | Trilha de auditoria interna da YOM: type, name, message e createdAt. |
|
createdAt |
📅 Data | 🟢 Obrigatório | Data de criação da solicitação, no formato ISO 8601. | "2026-09-14T11:05:12.881Z" |
updatedAt |
📅 Data | 🟢 Obrigatório | Data da última modificação da solicitação, no formato ISO 8601. | "2026-09-14T11:05:12.881Z" |
Cada linha de refundRequest.items.
| --- | --- | --- | --- | --- |
Cada resposta de items[].extraFields. O formulário de devolução é configurável por cliente, portanto o conjunto de campos depende da configuração de cada um.
| --- | --- | --- | --- | --- |
Os objetos order, commerce e seller são enviados completos, com a mesma estrutura que nas demais integrações.