Skip to main content

​
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 é:
  1. A integração puxa os anúncios do marketplace e os salva no OmniDom.
  2. Você vincula cada anúncio a um produto do catálogo interno.
  3. 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âmetroTipoDescrição
pagenumberPágina (padrão: 1)
limitnumberRegistros 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

StatusDescrição
activeAnúncio ativo e visível no marketplace
pausedPausado (sem visibilidade, mas ainda vinculado)
closedEncerrado no marketplace
inactiveInativo (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:
  1. O sistema identifica o externalId do anúncio.
  2. Localiza o productId vinculado.
  3. Reserva o estoque correspondente.
  4. Ao confirmar o pedido, a reserva é consumida.