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

# Integrações com Marketplaces

> Como conectar o OmniDom ao Mercado Livre, Shopee e outros marketplaces via OAuth.

## Visão geral

O OmniDom se conecta a marketplaces externos via **OAuth 2.0**. Cada loja de um marketplace é chamada de **Conexão** (`Connection`). Uma conta do OmniDom pode ter múltiplas conexões com o mesmo ou diferentes marketplaces.

Após autorizar, o sistema passa a:

* **Sincronizar anúncios** (`Listings`) automaticamente.
* **Receber webhooks** de pedidos e atualizações de status.
* **Ler e atualizar estoque** no marketplace (quando suportado pelo canal).

***

## Marketplaces suportados

| Marketplace   | Canal    | Pedidos | Sync de Estoque |
| ------------- | -------- | ------- | --------------- |
| Mercado Livre | `meli`   | ✅       | ✅               |
| Shopee        | `shopee` | ✅       | ✅ (parcial)     |

***

## Fluxo de conexão

```
1. GET /integrations/connect?channel=meli
        │
        ▼
2. Redireciona para a página de autorização do marketplace
        │
        ▼
3. Usuário autoriza o OmniDom na conta do marketplace
        │
        ▼
4. Marketplace redireciona para o callback do OmniDom com código de autorização
        │
        ▼
5. OmniDom troca o código por access_token e refresh_token
        │
        ▼
6. Conexão criada com status "active"
```

***

## Endpoints

### Iniciar conexão OAuth

```http theme={null}
GET /integrations/connect?channel=meli
```

Redireciona o usuário para a página de autorização do marketplace.

***

### Callback OAuth

```http theme={null}
GET /integrations/callback
```

Este endpoint é chamado pelo marketplace após autorização. Você não deve chamar este endpoint diretamente.

***

### Listar conexões

```http theme={null}
GET /integrations/connections
```

**Resposta:**

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "channel": "meli",
      "accountName": "Loja Exemplo",
      "status": "active",
      "lastSyncAt": "2025-06-10T14:30:00Z",
      "expiresAt": "2025-07-10T14:30:00Z"
    }
  ]
}
```

***

### Detalhar conexão

```http theme={null}
GET /integrations/connections/:id
```

***

### Reconectar / Renovar token

```http theme={null}
GET /integrations/reconnect/:id
```

Redireciona para autorização novamente. Use quando uma conexão estiver com status `expired` ou `error`.

***

### Desconectar

```http theme={null}
DELETE /integrations/connections/:id
```

Remove a conexão do OmniDom. O marketplace não é notificado. Os anúncios importados permanecem no sistema.

***

## Status das conexões

| Status    | Descrição                                               |
| --------- | ------------------------------------------------------- |
| `active`  | Conexão funcionando normalmente                         |
| `expired` | Token expirado. Reconecte para renovar.                 |
| `paused`  | Sync pausado manualmente                                |
| `error`   | Erro ao comunicar com o marketplace. Verifique os logs. |

***

## Webhooks recebidos

O OmniDom expõe endpoints de webhook para receber notificações em tempo real dos marketplaces.

| Evento             | Ação no OmniDom                             |
| ------------------ | ------------------------------------------- |
| `payment.approved` | Confirma o pedido e deduz estoque reservado |
| `order.created`    | Cria o pedido e reserva estoque             |
| `order.cancelled`  | Cancela o pedido e libera estoque reservado |
| `item.updated`     | Atualiza anúncio no catálogo de listings    |

<Warning>
  Os webhooks chegam de IPs dos marketplaces. Não bloqueie esses IPs no firewall ou o processamento automático de pedidos falhará.
</Warning>

***

## Sincronização manual

Para forçar um sync sem esperar o intervalo automático, use:

```http theme={null}
POST /listings/sync
Content-Type: application/json

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

Consulte a documentação de [Anúncios](/omnidom/listings) para mais detalhes.