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

# Integração

> Cronograma de integração offsite, arquitetura de contas e etapas de configuração.

export const OffsiteVendorAccountArchitectureDiagram = () => <div className="offsite-vendor-account-architecture not-prose" style={{
  margin: "1.5rem 0",
  overflowX: "auto"
}}>
    <style>{`
      .offsite-vendor-account-architecture svg {
        display: block;
        width: 100%;
        max-width: 882px;
        height: auto;
      }

      .offsite-vendor-account-architecture .marketplace-box {
        fill: #dcfce7;
        stroke: #16a34a;
      }

      .offsite-vendor-account-architecture .topsort-box {
        fill: #dbeafe;
        stroke: #2563eb;
      }

      .offsite-vendor-account-architecture .section-title,
      .offsite-vendor-account-architecture .box-label,
      .offsite-vendor-account-architecture .legend-label,
      .offsite-vendor-account-architecture .column-label {
        fill: #111827;
        font-family: Inter, system-ui, -apple-system, sans-serif;
      }

      .offsite-vendor-account-architecture .section-title {
        font-size: 15px;
        font-weight: 700;
      }

      .offsite-vendor-account-architecture .box-label {
        font-size: 12px;
        font-weight: 600;
      }

      .offsite-vendor-account-architecture .column-label,
      .offsite-vendor-account-architecture .legend-label {
        font-size: 11px;
        font-weight: 500;
      }

      .offsite-vendor-account-architecture .connector {
        stroke: #6b7280;
        stroke-width: 1.5;
        fill: none;
      }

      .dark .offsite-vendor-account-architecture .marketplace-box {
        fill: #14532d;
        stroke: #4ade80;
      }

      .dark .offsite-vendor-account-architecture .topsort-box {
        fill: #1e3a8a;
        stroke: #60a5fa;
      }

      .dark .offsite-vendor-account-architecture .section-title,
      .dark .offsite-vendor-account-architecture .box-label,
      .dark .offsite-vendor-account-architecture .legend-label,
      .dark .offsite-vendor-account-architecture .column-label {
        fill: #f3f4f6;
      }

      .dark .offsite-vendor-account-architecture .connector {
        stroke: #9ca3af;
      }
    `}</style>

    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 882 540" role="img" aria-label="Diagram of Google and Meta offsite account architecture showing retailer and Topsort-managed brand accounts">
      <text className="section-title" x="221" y="28" textAnchor="middle">
        Google Offsite Accounts
      </text>
      <text className="section-title" x="662" y="28" textAnchor="middle">
        Meta Offsite Accounts
      </text>

      <line className="connector" x1="477" y1="40" x2="477" y2="470" strokeDasharray="4 4" />

      <text className="column-label" x="144" y="58" textAnchor="middle">
        Merchant Center
      </text>
      <text className="column-label" x="360" y="58" textAnchor="middle">
        Ad Accounts
      </text>

      <rect className="marketplace-box" x="63" y="72" width="162" height="44" rx="8" strokeWidth="2" />
      <text className="box-label" x="144" y="99" textAnchor="middle">
        Retailer MCA
      </text>

      <line className="connector" x1="144" y1="116" x2="144" y2="132" />

      <rect className="topsort-box" x="86" y="132" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="144" y="153" textAnchor="middle">
        Brand MC Acct 1
      </text>

      <line className="connector" x1="144" y1="164" x2="144" y2="176" />

      <rect className="topsort-box" x="86" y="176" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="144" y="197" textAnchor="middle">
        Brand MC Acct 2
      </text>

      <text className="column-label" x="144" y="224" textAnchor="middle">
        ...
      </text>

      <line className="connector" x1="144" y1="232" x2="144" y2="244" />

      <rect className="topsort-box" x="86" y="244" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="144" y="265" textAnchor="middle">
        Brand MC Acct N
      </text>

      <rect className="marketplace-box" x="279" y="72" width="162" height="44" rx="8" strokeWidth="2" />
      <text className="box-label" x="360" y="99" textAnchor="middle">
        Retailer MCC
      </text>

      <line className="connector" x1="360" y1="116" x2="360" y2="132" />

      <rect className="topsort-box" x="279" y="132" width="162" height="44" rx="8" strokeWidth="2" />
      <text className="box-label" x="360" y="159" textAnchor="middle">
        Topsort MCC
      </text>

      <line className="connector" x1="360" y1="176" x2="360" y2="192" />

      <rect className="topsort-box" x="302" y="192" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="360" y="213" textAnchor="middle">
        Brand Ad Acct 1
      </text>

      <line className="connector" x1="360" y1="224" x2="360" y2="236" />

      <rect className="topsort-box" x="302" y="236" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="360" y="257" textAnchor="middle">
        Brand Ad Acct 2
      </text>

      <text className="column-label" x="360" y="284" textAnchor="middle">
        ...
      </text>

      <line className="connector" x1="360" y1="292" x2="360" y2="304" />

      <rect className="topsort-box" x="302" y="304" width="117" height="32" rx="6" strokeWidth="2" />
      <text className="box-label" x="360" y="325" textAnchor="middle">
        Brand Ad Acct N
      </text>

      <rect className="marketplace-box" x="572" y="72" width="180" height="44" rx="8" strokeWidth="2" />
      <text className="box-label" x="662" y="99" textAnchor="middle">
        Retailer Business Manager
      </text>

      <line className="connector" x1="662" y1="116" x2="662" y2="145" />
      <line className="connector" x1="590" y1="145" x2="734" y2="145" />
      <line className="connector" x1="590" y1="145" x2="590" y2="165" />
      <line className="connector" x1="734" y1="145" x2="734" y2="165" />

      <rect className="topsort-box" x="536" y="165" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="590" y="188" textAnchor="middle">
        Brand Ad Acct 1
      </text>

      <rect className="topsort-box" x="536" y="215" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="590" y="238" textAnchor="middle">
        Brand Ad Acct 2
      </text>

      <text className="column-label" x="590" y="272" textAnchor="middle">
        ...
      </text>

      <rect className="topsort-box" x="536" y="285" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="590" y="308" textAnchor="middle">
        Brand Ad Acct N
      </text>

      <rect className="topsort-box" x="680" y="165" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="734" y="188" textAnchor="middle">
        Brand Child BM 1
      </text>

      <rect className="topsort-box" x="680" y="215" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="734" y="238" textAnchor="middle">
        Brand Child BM 2
      </text>

      <text className="column-label" x="734" y="272" textAnchor="middle">
        ...
      </text>

      <rect className="topsort-box" x="680" y="285" width="108" height="36" rx="6" strokeWidth="2" />
      <text className="box-label" x="734" y="308" textAnchor="middle">
        Brand Child BM N
      </text>

      <rect className="marketplace-box" x="36" y="470" width="18" height="18" rx="3" strokeWidth="2" />
      <text className="legend-label" x="61" y="484">
        Marketplace provides and manages
      </text>

      <rect className="topsort-box" x="320" y="470" width="18" height="18" rx="3" strokeWidth="2" />
      <text className="legend-label" x="345" y="484">
        Topsort creates and manages
      </text>
    </svg>
  </div>;

export const LastUpdatedPt = ({date}) => {
  const label = "Última atualização:";
  return <>
      <style>{`
        .last-updated-component {
          display: inline-flex;
          align-items: center;
          gap: 8px;
          padding: 10px 16px;
          border-radius: 8px;
          margin-top: 12px;
          margin-bottom: 16px;
          font-size: 14px;
          background-color: rgba(0, 0, 0, 0.05);
          border: 1px solid rgba(0, 0, 0, 0.12);
          color: rgba(0, 0, 0, 0.75);
          line-height: 1;
        }

        .last-updated-component svg {
          flex-shrink: 0;
          vertical-align: middle;
        }

        .last-updated-component span {
          display: inline-flex !important;
          align-items: center !important;
          line-height: 1 !important;
        }

        [data-theme="dark"] .last-updated-component {
          background-color: #3a3a3a;
          border: 2px solid #888888;
          color: #ffffff;
        }

        [data-theme="dark"] .last-updated-component svg {
          stroke: #ffffff;
        }
      `}</style>
      <div className="last-updated-component">
        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
          <circle cx="12" cy="12" r="10" />
          <polyline points="12 6 12 12 16 14" />
        </svg>
        <span>
          <strong style={{
    fontWeight: 600
  }}>{label}</strong> 
          <time dateTime={date}>{date}</time>
        </span>
      </div>
    </>;
};

## Visão geral

Para lançar anúncios offsite em uma plataforma específica, o marketplace concede ao Topsort acesso às contas de anúncios necessárias, implementa o rastreamento de eventos offsite e o Topsort cuida do restante da integração (por exemplo, sincronização de catálogo e eventos offline com o marketplace, validação).

O Topsort executa um cronograma de implementação de 2 semanas para cada plataforma offsite (por exemplo, Google ou Meta) para garantir um lançamento POC bem-sucedido, com recursos cross-funcionais dedicados do cliente:

* **Engenharia:** \~1 dia de esforço de um engenheiro do marketplace (integração e validação). O desenvolvimento provavelmente pode ser concluído em uma única chamada de 90 minutos com engenheiros do Topsort.
* **Ad Operations:** \~1 dia de suporte de ad ops do marketplace para configuração de campanhas, QA e lançamento.

## Arquitetura de contas

O provisionamento automatizado de contas escala para milhares de vendedores com separação clara de orçamento e configuração manual mínima. Abaixo está a estrutura de contas recomendada.

<OffsiteVendorAccountArchitectureDiagram />

### Google

* **O marketplace fornece:** Acesso ao MCC (conta administradora) + MCA (conta multicliente do Merchant Center)
* **O Topsort cria:** Contas do Google Ads por vendedor com a vinculação necessária ao Merchant Center

### Meta

* **O marketplace fornece:** Acesso ao Business Manager principal
* **O Topsort cria:** Business Manager filho e conta de anúncios por vendedor

### TikTok

* **O marketplace fornece:** Acesso ao TikTok Business Center / Business Manager, com permissão para gerenciar contas de anunciantes e assets
* **O Topsort cria:** Uma conta de anúncios TikTok dedicada para a integração offsite do Topsort, normalmente uma conta de anúncios para o marketplace/varejista, não uma por vendedor

### Snap

* **O marketplace fornece:** Acesso ao Snap Business Manager / Organization, com permissão para gerenciar contas de anúncios e billing/assets
* **O Topsort cria:** Uma conta de anúncios Snap dedicada para a integração offsite do Topsort, normalmente uma conta de anúncios para o marketplace/varejista, não uma por vendedor

## Etapas de configuração

### Configuração de contas

#### Acesso às contas (marketplace)

O marketplace concede ao Topsort acesso de administrador às contas de plataforma de anúncios de nível superior necessárias para os canais sendo integrados. Consulte [Arquitetura de contas](#arquitetura-de-contas) acima para as contas específicas às quais conceder acesso em cada plataforma.

#### Criação de contas (Topsort)

O Topsort provisiona a estrutura de contas em nível de vendedor sob esses contêineres do marketplace, incluindo contas de anúncios filhas, business managers ou contas do Merchant Center necessárias para a integração. Consulte [Arquitetura de contas](#arquitetura-de-contas) acima para o que o Topsort cria em cada plataforma. O marketplace pode fornecer ao Topsort uma lista de vendedores a habilitar para offsite.

### Sincronização de catálogo (Topsort)

Quando formatos offsite baseados em catálogo estão no escopo, o Topsort sincroniza o catálogo do marketplace com a plataforma offsite, mapeando os produtos de cada vendedor na estrutura de conta da plataforma correspondente para esse vendedor.

### Configuração de rastreamento de eventos (marketplace)

A única área em que o marketplace precisará fazer desenvolvimento é o rastreamento de eventos. Para reportar eventos offsite, use o mesmo endpoint [`/v2/events`](/pt/api-reference/events/report-events) dos eventos onsite, passando parâmetros adicionais no corpo da solicitação.

#### ID de usuário opaco

O mesmo `opaqueUserId` usado para eventos onsite também deve ser reutilizado para atribuição offsite. Não é necessário um identificador offsite separado. O Topsort precisa de um identificador de usuário persistente e seguro para privacidade para conectar cliques e compras entre canais.

Os mesmos requisitos onsite se aplicam ao uso offsite:

* **Persistência:** Deve permanecer estável durante a janela de atribuição (normalmente 7–30 dias).
* **Consistência:** O mesmo usuário deve receber o mesmo ID em visitas e canais quando possível.
* **Seguro para privacidade:** Não deve conter PII como email, número de telefone ou nome.

#### URL de clique

A URL que o usuário tem ao chegar ao seu site a partir de um clique de anúncio offsite terá parâmetros de consulta importantes anexados.

Exemplo de URL de clique:

```
https://www.retailer.com/search?q=shampoo&
externalCampaignId=9d2d7d7d-5d4f-4d8e-a8d0-2d7a6f9c1234&
externalVendorId=vendor_abc123&
gclid=CjwKCAj_example123&
utm_source=google&
utm_medium=c
```

Parâmetros de consulta:

* `gclid` — ID de clique anexado pelo Google
* `externalCampaignId` e `externalVendorId` — parâmetros de consulta contendo o ID da campanha e o ID do vendedor do Topsort, anexados pelo Topsort. Devem persistir junto com o estado de atribuição do usuário por pelo menos a duração da janela de atribuição (configurável 7–30 dias). Devem sobreviver à navegação e visitas repetidas para que eventos de compra subsequentes possam ser corretamente vinculados ao clique de anúncio offsite originador.

#### Reportar cliques

Envie o evento abaixo quando um usuário chegar ao seu site a partir de um clique de anúncio offsite. Todos os campos são obrigatórios.

```http theme={null}
POST /v2/events
```

```json theme={null}
{
  "clicks": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "entity": {
        "id": "product1",
        "type": "product"
      },
      "externalCampaignId": "<Topsort UUID>",
      "externalVendorId": "<Topsort externalVendorId>",
      "dsp_metadata": {
        "gclid": "<Google click ID>"
      },
      "channel": "offsite"
    }
  ]
}
```

#### Reportar compras

Todos os campos são obrigatórios.

```http theme={null}
POST /v2/events
```

```json theme={null}
{
  "purchases": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "items": [
        {
          "productId": "product1",
          "vendorId": "<externalVendorId>",
          "unitPrice": 75.0,
          "quantity": 1
        },
        {
          "productId": "product2",
          "vendorId": "<externalVendorId>",
          "unitPrice": 25.0,
          "quantity": 1
        }
      ]
    }
  ]
}
```

#### Compartilhar eventos com plataformas offsite

O cliente não precisa reportar separadamente eventos de conversão à plataforma offsite. O Topsort envia automaticamente eventos de compra elegíveis vinculados ao ID de clique correspondente (por exemplo, Google Click ID ou GCLID) por meio da API de conversões offline da plataforma.

## Cronograma de integração

### Semana 1 – Acesso e configuração de rastreamento de eventos

* Conceder acesso às contas necessárias
* Iniciar a implementação do rastreamento de eventos
* Sincronizar catálogo se necessário com a plataforma offsite
* Iniciar a configuração inicial do sistema

### Semana 2 – Integração e configuração de dados

* Finalizar a integração e iniciar testes
* Validar rastreamento de eventos e estrutura/qualidade do catálogo
* Após tudo configurado, validar com uma campanha ao vivo e monitorar desempenho

***

<LastUpdatedPt date="2026-05-23" />