> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domsoftware.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Anúncios (Listings)

> Sincronize anúncios dos marketplaces e vincule ao catálogo interno de produtos.

## 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.

<Note>
  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.
</Note>

***

## Endpoints

### Listar anúncios

```http theme={null}
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:**

```json theme={null}
{
  "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

```http theme={null}
GET /listings/:id
```

***

### Vincular produto ao anúncio

```http theme={null}
PATCH /listings/:id/product
Content-Type: application/json
```

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

**Body:**

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
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:**

```json theme={null}
{
  "connectionId": "uuid-da-conexao"
}
```

**Resposta:**

```json theme={null}
{
  "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:

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.