🔑 Como Solicitar Acesso à API

Para usar a API de Afiliados Shopee, você precisa solicitar suas credenciais (App ID e Secret). Siga o passo a passo:

Campos do Formulário de Solicitação

📌 Importante: Após enviar, você verá a mensagem "Seu caso será enviado para análise. Em breve retornamos!". A equipe Shopee irá analisar e enviar suas credenciais por e-mail. O tempo de resposta pode variar em até 2 semanas.

🔐 Autenticação

Todas as requisições à API Shopee requerem autenticação via header Authorization com assinatura SHA256. Esse método garante que apenas você (com seu App ID e Secret) pode fazer requisições em nome da sua conta de afiliado.

🔒 Por que usar SHA256? A assinatura SHA256 é um hash criptográfico que valida sua identidade sem expor seu Secret. Mesmo que alguém intercepte a requisição, não conseguirá replicá-la sem conhecer seu Secret.

Estrutura do Header Authorization

O header deve seguir exatamente este formato, com os 3 componentes separados por vírgula:

Authorization: SHA256 Credential={AppId}, Timestamp={Timestamp}, Signature={Signature}

Como calcular a Signature

A assinatura é um hash SHA256 da concatenação (sem espaços ou separadores) de 4 valores nesta ordem exata:

Signature = SHA256(AppId + Timestamp + Payload + Secret)

⚠️ Atenção: O timestamp deve estar próximo do horário atual do servidor. Diferenças maiores que alguns minutos podem causar erro de autenticação.

📡 Formato das Requisições

A API Shopee utiliza GraphQL, uma linguagem de consulta que permite solicitar exatamente os dados que você precisa. Diferente de REST, você especifica quais campos quer receber, otimizando a resposta.

Especificações Técnicas

• URL Base: https://open-api.affiliate.shopee.com.br/graphql
• Método HTTP: POST (sempre POST, mesmo para consultas)
• Content-Type: application/json
• Encoding: UTF-8

Estrutura do Body (GraphQL)

O corpo da requisição é um JSON com a query GraphQL. Você pode incluir variáveis para parametrizar suas consultas:

{
  "query": "{ ... }",
  "operationName": "NomeOperacao",  // opcional - útil quando há múltiplas operações
  "variables": { ... }               // opcional - valores dinâmicos para a query
}

Estrutura da Resposta

A resposta sempre retorna um objeto JSON. Em caso de sucesso, os dados vêm no campo data. Em caso de erro, os detalhes vêm no campo errors:

// ✅ Sucesso - dados retornados normalmente
{
  "data": {
    "nomeDoEndpoint": { ... }
  }
}

// ❌ Erro - detalhes do problema
{
  "errors": [
    {
      "message": "Descrição do erro",
      "path": ["nomeDoEndpoint"],
      "extensions": {
        "code": 10020,
        "message": "Detalhes específicos do erro"
      }
    }
  ]
}

💡 Dica: Você pode receber data e errors simultaneamente se parte da query funcionou e parte falhou. Sempre verifique ambos os campos.

📦 1.1 Shopee Offer List

Este endpoint retorna campanhas e ofertas especiais da Shopee disponíveis para divulgação. São promoções criadas pela própria Shopee, como campanhas sazonais (Black Friday, Natal, etc.), coleções temáticas e ofertas flash.

📌 Quando usar: Ideal para divulgar promoções gerais da Shopee. Os links já vêm com seu tracking de afiliado embutido no campo offerLink.

Query GraphQL

{
  shopeeOfferV2(
    keyword: "promocao",
    sortType: 1,
    page: 1,
    limit: 10
  ) {
    nodes {
      commissionRate
      imageUrl
      offerLink
      originalLink
      offerName
      offerType
      categoryId
      collectionId
      periodStartTime
      periodEndTime
    }
    pageInfo {
      page
      limit
      hasNextPage
    }
  }
}

Parâmetros

Campos de Resposta

🏬 1.2 Shop Offer List

Este endpoint retorna lojas que oferecem comissão diferenciada para afiliados. São vendedores que optaram por pagar uma comissão extra além da comissão padrão da Shopee, tornando mais atrativo divulgar seus produtos.

📌 Quando usar: Ideal para encontrar lojas parceiras com boas comissões. Você pode filtrar por tipo de loja (Mall, Star, Star+) e ordenar por taxa de comissão para encontrar as melhores oportunidades.

O que é Key Seller?

Key Sellers são vendedores estratégicos selecionados pela Shopee. Geralmente são lojas com alto volume de vendas, boa reputação e que participam ativamente do programa de afiliados com comissões atrativas.

Query GraphQL

{
  shopOfferV2(
    keyword: "loja",
    shopType: [1, 4],
    isKeySeller: true,
    sortType: 2,
    page: 1,
    limit: 10
  ) {
    nodes {
      shopId
      shopName
      commissionRate
      ratingStar
      shopType
      imageUrl
      offerLink
      remainingBudget
      sellerCommCoveRatio
      periodStartTime
      periodEndTime
    }
    pageInfo { page limit hasNextPage }
  }
}

Parâmetros

Tipos de Loja (shopType)

🛒 1.3 Product Offer List

Este endpoint é o mais utilizado pelos afiliados. Retorna produtos específicos com suas comissões detalhadas, permitindo buscar itens por palavra-chave, categoria, loja ou diversos outros filtros.

📌 Quando usar: Perfeito para criar listas de produtos, comparadores de preços, bots de ofertas ou qualquer aplicação que precise buscar produtos específicos. É o endpoint mais flexível e completo.

Entendendo as Comissões

A comissão total de um produto pode vir de duas fontes:

• Comissão Shopee: Paga pela plataforma (geralmente 2-5%)
• Comissão Seller: Paga pelo vendedor como incentivo extra (varia muito)

A soma das duas resulta na commissionRate total que você receberá.

Query GraphQL

{
  productOfferV2(
    keyword: "celular",
    listType: 1,
    sortType: 5,
    page: 1,
    limit: 20
  ) {
    nodes {
      itemId
      productName
      productLink
      offerLink
      imageUrl
      priceMin
      priceMax
      priceDiscountRate
      sales
      ratingStar
      commissionRate
      sellerCommissionRate
      shopeeCommissionRate
      commission
      shopId
      shopName
      shopType
      periodStartTime
      periodEndTime
    }
    pageInfo { page limit hasNextPage }
  }
}

Parâmetros

Campos de Comissão

🔗 2. Generate Short Link

Este endpoint permite transformar qualquer URL da Shopee em um link curto com seu tracking de afiliado embutido. Útil quando você tem uma URL de produto ou loja e quer gerar um link rastreável.

📌 Quando usar: Quando você já tem o link de um produto/loja e precisa adicionar seu tracking. Por exemplo, se um usuário compartilhou um link de produto e você quer convertê-lo em link de afiliado.

Sobre os SubIds

Os subIds são identificadores personalizados que você define para rastrear a origem das suas conversões. Eles aparecem no campo utmContent do relatório de conversões, permitindo saber exatamente qual campanha, canal ou post gerou cada venda.

Exemplos de uso:

• ["instagram", "stories", "promo_maio"] - Venda veio do Instagram Stories
• ["telegram", "grupo_ofertas", "flash"] - Venda veio do grupo Telegram
• ["site", "banner_home", "v2"] - Venda veio do banner do site

Mutation GraphQL

mutation {
  generateShortLink(
    input: {
      originUrl: "https://shopee.com.br/produto-exemplo-i.123.456"
      subIds: ["campanha1", "banner_home", "instagram"]
    }
  ) {
    shortLink
  }
}

Parâmetros

Resposta

{
  "data": {
    "generateShortLink": {
      "shortLink": "https://shope.ee/abc123xyz"
    }
  }
}

💡 Dica: Use os subIds para rastrear de onde vieram suas conversões. Exemplo: ["facebook", "stories", "promo_verao"] aparecerá no relatório de conversão.

📈 3.1 Conversion Report

Este endpoint retorna o relatório de conversões com todos os pedidos gerados através dos seus links de afiliado. Você pode ver cliques, pedidos, status de cada compra e comissões estimadas.

📌 Quando usar: Para acompanhar suas vendas em tempo real, analisar performance de campanhas (via utmContent) e prever sua comissão do período. As comissões aqui são estimadas - o valor final só é confirmado após validação.

Fluxo de uma Conversão

Quando alguém clica no seu link e compra, a conversão passa por estes estágios:

1. UNPAID: Pedido criado, aguardando pagamento
2. PENDING: Pago, produto em trânsito/aguardando confirmação
3. COMPLETED: Entrega confirmada, comissão será paga ✓
4. CANCELLED: Cancelado/devolvido, sem comissão ✗

Query GraphQL

{
  conversionReport(
    purchaseTimeStart: 1704067200,
    purchaseTimeEnd: 1704153600,
    orderStatus: "COMPLETED",
    limit: 50
  ) {
    nodes {
      purchaseTime
      clickTime
      conversionId
      totalCommission
      sellerCommission
      shopeeCommissionCapped
      buyerType
      device
      utmContent
      orders {
        orderId
        orderStatus
        items {
          itemId
          itemName
          shopName
          itemPrice
          qty
          itemTotalCommission
          attributionType
        }
      }
    }
    pageInfo {
      limit
      hasNextPage
      scrollId
    }
  }
}

Principais Filtros

Status do Pedido

✅ 3.2 Validated Report

Este endpoint retorna as conversões já validadas pela Shopee, com os valores finais de comissão que serão efetivamente pagos. Diferente do Conversion Report, aqui os valores são definitivos.

📌 Quando usar: Para conferir os valores finais de comissão antes do pagamento. Use o validationId (período de validação) para consultar conversões específicas.

Diferença entre Conversion Report e Validated Report

Query GraphQL

{
  validatedReport(
    validationId: 12345,
    limit: 100
  ) {
    nodes {
      conversionId
      netCommission
      totalCommission
      orders {
        orderId
        items {
          itemName
          itemTotalCommission
          refundAmount
        }
      }
    }
    pageInfo {
      hasNextPage
      scrollId
    }
  }
}

⚠️ Paginação: O scrollId é válido por apenas 30 segundos. Use-o imediatamente na próxima requisição para continuar a paginação.

⚠️ Códigos de Erro

Quando algo dá errado, a API retorna um código de erro no campo extensions.code da resposta. Abaixo estão os erros mais comuns e como resolvê-los:

Dicas para evitar erros

• Use timestamps em segundos (não milissegundos)
• Não deixe trailing commas na query GraphQL
• Escape strings corretamente no JSON
• Verifique se o App está ativo no painel Shopee