API de Afiliados Shopee: Tutorial Completo (Node.js, Python, PHP)

A Shopee oferece uma das APIs de afiliados mais ricas do mercado brasileiro, mas a documentacao oficial e confusa, o esquema de autenticacao SHA256 derruba metade dos devs no primeiro contato, e o erro generico 90309999 quebra projetos sem dar pista do que esta errado.

Este tutorial cobre, passo a passo, como obter App ID, gerar a assinatura correta, fazer requisicoes GraphQL e tratar os erros mais comuns. Inclui codigo funcional em Node.js, Python e PHP.

Pre-requisitos

Antes de comecar:

• Conta ativa no Shopee Affiliate Brasil (affiliate.shopee.com.br)
• Status "Aprovado" no programa
• Conhecimento basico de HTTP, JSON e GraphQL
• Ambiente de desenvolvimento configurado (Node 18+, Python 3.10+ ou PHP 8.1+)

Passo 1: Obter App ID e App Secret

A obtencao do App ID e o primeiro filtro tecnico.

1. Acesse open.shopee.com (nao confundir com a Shopee Brasil normal)
2. Faca login com a mesma conta que usa em affiliate.shopee.com.br
3. Va em "My Apps" → "Create App"
4. Preencha: App name, App description, Region: Brazil, Category: Affiliate Program
5. Aceite os termos de uso da Open Platform
6. Apos criacao, anote: App ID (numerico) e App Secret (string longa)

Guarde o secret em variavel de ambiente. Nunca commit em repositorio publico.

Passo 2: Estrutura da requisicao

Toda requisicao a API de afiliados usa GraphQL e exige cabecalho de autenticacao calculado dinamicamente.

Endpoint

POST https://open-api.affiliate.shopee.com.br/graphql

Cabecalhos obrigatorios

Content-Type: application/json
Authorization: SHA256 Credential={APP_ID}, Timestamp={TIMESTAMP}, Signature={SIGNATURE}

Calculo da assinatura

A assinatura e o hash SHA256 da concatenacao de:

APP_ID + TIMESTAMP + PAYLOAD + APP_SECRET

Onde:

• APP_ID = seu app ID numerico
• TIMESTAMP = unix timestamp em segundos (nao milissegundos)
• PAYLOAD = string exata do body JSON da requisicao
• APP_SECRET = seu app secret

Resultado em hexadecimal lowercase.

Passo 3: Implementacao em Node.js

Instalacao

npm install axios

Cliente Shopee Affiliate

import axios from 'axios';
import crypto from 'crypto';

const APP_ID = process.env.SHOPEE_APP_ID;
const APP_SECRET = process.env.SHOPEE_APP_SECRET;
const ENDPOINT = 'https://open-api.affiliate.shopee.com.br/graphql';

function buildSignature(payload) {
  const timestamp = Math.floor(Date.now() / 1000);
  const baseString = `${APP_ID}${timestamp}${payload}${APP_SECRET}`;
  const signature = crypto.createHash('sha256').update(baseString).digest('hex');
  return { timestamp, signature };
}

export async function shopeeQuery(query, variables = {}) {
  const payload = JSON.stringify({ query, variables });
  const { timestamp, signature } = buildSignature(payload);

  try {
    const response = await axios.post(ENDPOINT, payload, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `SHA256 Credential=${APP_ID}, Timestamp=${timestamp}, Signature=${signature}`,
        'User-Agent': 'MyApp/1.0',
      },
      timeout: 15000,
    });
    return response.data;
  } catch (error) {
    if (error.response) {
      throw new Error(`Shopee API erro ${error.response.status}: ${JSON.stringify(error.response.data)}`);
    }
    throw error;
  }
}

Exemplo: gerar link curto

const query = `
  mutation generateShortLink($input: ShortLinkInput!) {
    generateShortLink(input: $input) {
      shortLink
    }
  }
`;

const variables = {
  input: {
    originUrl: 'https://shopee.com.br/product/12345/67890',
    subIds: ['campanha_whatsapp', 'grupo_principal'],
  },
};

const result = await shopeeQuery(query, variables);
console.log(result.data.generateShortLink.shortLink);

Exemplo: buscar produtos por palavra-chave

const query = `
  query productOfferV2($keyword: String!, $limit: Int!) {
    productOfferV2(keyword: $keyword, limit: $limit) {
      nodes {
        productName
        itemId
        commissionRate
        sales
        priceMin
        priceMax
        imageUrl
        productLink
        offerLink
      }
    }
  }
`;

const variables = { keyword: 'fone bluetooth', limit: 10 };
const result = await shopeeQuery(query, variables);
console.log(result.data.productOfferV2.nodes);

Passo 4: Implementacao em Python

Instalacao

pip install requests

Cliente Shopee Affiliate

import os
import time
import json
import hashlib
import requests

APP_ID = os.environ['SHOPEE_APP_ID']
APP_SECRET = os.environ['SHOPEE_APP_SECRET']
ENDPOINT = 'https://open-api.affiliate.shopee.com.br/graphql'


def build_signature(payload: str) -> tuple[int, str]:
    timestamp = int(time.time())
    base_string = f"{APP_ID}{timestamp}{payload}{APP_SECRET}"
    signature = hashlib.sha256(base_string.encode('utf-8')).hexdigest()
    return timestamp, signature


def shopee_query(query: str, variables: dict | None = None) -> dict:
    payload = json.dumps({'query': query, 'variables': variables or {}}, separators=(',', ':'))
    timestamp, signature = build_signature(payload)

    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'SHA256 Credential={APP_ID}, Timestamp={timestamp}, Signature={signature}',
        'User-Agent': 'MyApp/1.0',
    }

    response = requests.post(ENDPOINT, data=payload, headers=headers, timeout=15)
    response.raise_for_status()
    return response.json()

Exemplo: gerar link curto

query = """
  mutation generateShortLink($input: ShortLinkInput!) {
    generateShortLink(input: $input) {
      shortLink
    }
  }
"""

variables = {
    'input': {
        'originUrl': 'https://shopee.com.br/product/12345/67890',
        'subIds': ['campanha_whatsapp', 'grupo_principal'],
    }
}

result = shopee_query(query, variables)
print(result['data']['generateShortLink']['shortLink'])

Passo 5: Implementacao em PHP

Cliente Shopee Affiliate

<?php

class ShopeeAffiliateClient
{
    private string $appId;
    private string $appSecret;
    private string $endpoint = 'https://open-api.affiliate.shopee.com.br/graphql';

    public function __construct(string $appId, string $appSecret)
    {
        $this->appId = $appId;
        $this->appSecret = $appSecret;
    }

    private function buildSignature(string $payload): array
    {
        $timestamp = time();
        $baseString = $this->appId . $timestamp . $payload . $this->appSecret;
        $signature = hash('sha256', $baseString);
        return ['timestamp' => $timestamp, 'signature' => $signature];
    }

    public function query(string $query, array $variables = []): array
    {
        $payload = json_encode(['query' => $query, 'variables' => $variables], JSON_UNESCAPED_SLASHES);
        $auth = $this->buildSignature($payload);

        $ch = curl_init($this->endpoint);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $payload,
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                "Authorization: SHA256 Credential={$this->appId}, Timestamp={$auth['timestamp']}, Signature={$auth['signature']}",
                'User-Agent: MyApp/1.0',
            ],
            CURLOPT_TIMEOUT => 15,
        ]);

        $response = curl_exec($ch);
        if (curl_errno($ch)) {
            throw new RuntimeException('cURL error: ' . curl_error($ch));
        }
        curl_close($ch);

        return json_decode($response, true);
    }
}

Erros comuns e solucao

Erro 90309999 — Anti-bot detection

O mais frequente. Significa que a API detectou comportamento suspeito. Checklist:

1. Timestamp: confirme que esta em segundos (nao milissegundos) e dentro de 5 minutos do horario atual
2. Assinatura: a string base deve ser exatamente APP_ID + TIMESTAMP + PAYLOAD + APP_SECRET, sem espacos
3. Payload: o JSON enviado tem que ser identico, byte a byte, ao usado pra calcular a assinatura
4. User-Agent: nunca envie sem User-Agent. Use algo descritivo
5. IP: se voce fez muitas requisicoes erradas, espere 10 minutos antes de tentar novamente

Erro 429 — Too Many Requests

Voce passou do rate limit. Implemente backoff exponencial:

async function queryWithRetry(query, variables, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await shopeeQuery(query, variables);
    } catch (error) {
      if (error.message.includes('429')) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
        continue;
      }
      throw error;
    }
  }
}

Erro 401 — Unauthorized

Credenciais erradas. Verifique se App ID e App Secret estao corretos e se o app esta aprovado no Open Platform.

Erro 500 — Internal Server Error

Problema do lado da Shopee. Tente novamente em alguns segundos. Se persistir por mais de 30 minutos, abra ticket no Open Platform.

Boas praticas em producao

1. Cache agressivo de produtos: a mesma busca pode rodar muitas vezes. Cache no Redis com TTL de 1 hora.
2. Filas pra requisicoes em lote: nunca chame a API direto do request HTTP do usuario. Use fila (BullMQ, Celery, RabbitMQ).
3. Monitoramento: alarme quando taxa de erro passar de 5% em 5 minutos.
4. Rotacao de subIds: use subIds descritivos por canal (whatsapp_grupo01, instagram_bio, etc.) pra rastrear performance.
5. Logs estruturados: salve cada request e response em formato JSON pra debug.

Alternativa sem codigo

Se voce precisa de integracao funcional sem manter o codigo proprio, plataformas como o Afilira ja implementam tudo isso (Shopee + Mercado Livre + Amazon + AliExpress) e expoem dashboard pronto, geracao de link em massa e disparo automatico em grupos de WhatsApp. Veja tambem nosso comparativo das melhores ferramentas pra entender onde encaixar essa stack.

Conclusao

A API de afiliados da Shopee e poderosa, mas exige cuidado com timestamp, assinatura e rate limit. Com os exemplos acima funcionando em Node.js, Python ou PHP, voce consegue gerar links em massa, buscar produtos por categoria, monitorar comissao e construir bots inteligentes. O segredo e tratar cada erro com retry inteligente e respeitar os limites da plataforma.