Anúncios (Listings)

Visão geral

No OmniDom, um anúncio (Listing) representa um produto publicado em um marketplace externo (ex: Mercado Livre, Shopee). Os anúncios são sincronizados automaticamente a partir das integrações. O fluxo padrão é:

A integração puxa os anúncios do marketplace e os salva no OmniDom.
Você vincula cada anúncio a um produto do catálogo interno.
A partir daí, pedidos nesse anúncio deduzem o estoque do produto vinculado.

Listings não são criados manualmente. Eles vêm dos marketplaces via sync. Use os endpoints abaixo para consultá-los e vinculá-los ao seu catálogo.

Endpoints

Listar anúncios

GET /listings

Retorna os anúncios vinculados ao tenant autenticado. Query params:

Parâmetro	Tipo	Descrição
`page`	number	Página (padrão: 1)
`limit`	number	Registros por página (padrão: 20)

Resposta:

{
  "data": [
    {
      "id": "uuid",
      "externalId": "MLB123456789",
      "title": "Camiseta Branca P - 100% Algodão",
      "price": 59.90,
      "status": "active",
      "thumbnail": "https://...",
      "connectionId": "uuid-da-conexao",
      "productId": null,
      "product": null
    }
  ],
  "total": 120,
  "page": 1,
  "limit": 20
}

Listings sem productId ainda não foram vinculados ao catálogo.

Detalhar anúncio

GET /listings/:id

Vincular produto ao anúncio

PATCH /listings/:id/product
Content-Type: application/json

Associa um produto do catálogo interno ao anúncio do marketplace. Body:

{
  "productId": "uuid-do-produto-interno"
}

Após a vinculação, pedidos do marketplace que referenciam esse anúncio passam a movimentar o estoque do produto vinculado.

Desvincular produto

DELETE /listings/:id/product

Remove a associação entre o anúncio e o produto do catálogo. O anúncio permanece no sistema, mas sem vínculo de estoque.

Sincronizar anúncios manualmente

POST /listings/sync
Content-Type: application/json

Força a sincronização imediata dos anúncios de uma conexão. Normalmente o sync ocorre automaticamente em intervalos configurados. Body:

{
  "connectionId": "uuid-da-conexao"
}

Resposta:

{
  "message": "Sync iniciado",
  "jobId": "uuid-do-job"
}

A sincronização é assíncrona (processada em background pelo BullMQ). Use o status da conexão para acompanhar.

Estados de um listing

Status	Descrição
`active`	Anúncio ativo e visível no marketplace
`paused`	Pausado (sem visibilidade, mas ainda vinculado)
`closed`	Encerrado no marketplace
`inactive`	Inativo (geralmente por falta de estoque)

Relação entre Listing, Produto e Estoque

Marketplace (ex: Mercado Livre)
   └── Listing (MLB123)
          │
          └─ vinculado a ──▶ Produto (SKU: CAM-BCO-P)
                                  │
                                  └─ estoque por depósito

Quando um pedido chega via webhook do marketplace:

O sistema identifica o externalId do anúncio.
Localiza o productId vinculado.
Reserva o estoque correspondente.
Ao confirmar o pedido, a reserva é consumida.

Introdução

Guias Práticos (Manuais)

Para Desenvolvedores

Sistema

Funcional

Anúncios (Listings)

Visão geral

Endpoints

Listar anúncios

Detalhar anúncio

Vincular produto ao anúncio

Desvincular produto

Sincronizar anúncios manualmente

Estados de um listing

Relação entre Listing, Produto e Estoque

​Visão geral

​Endpoints

​Listar anúncios

​Detalhar anúncio

​Vincular produto ao anúncio

​Desvincular produto

​Sincronizar anúncios manualmente

​Estados de um listing

​Relação entre Listing, Produto e Estoque

Visão geral

Endpoints

Listar anúncios

Detalhar anúncio

Vincular produto ao anúncio

Desvincular produto

Sincronizar anúncios manualmente

Estados de um listing

Relação entre Listing, Produto e Estoque