Integrações com Marketplaces

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

GET /integrations/connect?channel=meli

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

Callback OAuth

GET /integrations/callback

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

Listar conexões

GET /integrations/connections

Resposta:

{
  "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

GET /integrations/connections/:id

Reconectar / Renovar token

GET /integrations/reconnect/:id

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

Desconectar

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

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

Sincronização manual

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

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

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

Consulte a documentação de Anúncios para mais detalhes.

Introdução

Guias Práticos (Manuais)

Para Desenvolvedores

Sistema

Funcional

Integrações com Marketplaces

Visão geral

Marketplaces suportados

Fluxo de conexão

Endpoints

Iniciar conexão OAuth

Callback OAuth

Listar conexões

Detalhar conexão

Reconectar / Renovar token

Desconectar

Status das conexões

Webhooks recebidos

Sincronização manual

​Visão geral

​Marketplaces suportados

​Fluxo de conexão

​Endpoints

​Iniciar conexão OAuth

​Callback OAuth

​Listar conexões

​Detalhar conexão

​Reconectar / Renovar token

​Desconectar

​Status das conexões

​Webhooks recebidos

​Sincronização manual

Visão geral

Marketplaces suportados

Fluxo de conexão

Endpoints

Iniciar conexão OAuth

Callback OAuth

Listar conexões

Detalhar conexão

Reconectar / Renovar token

Desconectar

Status das conexões

Webhooks recebidos

Sincronização manual