Créditos e cobrança

Cada solicitação bem-sucedida de chave de API consome créditos mensais de API. Este guia explica a cota, quando ela é reiniciada, o que é considerado uma solicitação faturável e como monitorar o uso.

A cota#

Quando a cota for atingida, todas as solicitações subsequentes retornarão:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

O contador é reiniciado automaticamente no início do próximo mês — não é necessário fazer nada.

O que conta (e o que não conta)#

Cada chamada programática com cobrança por uso tenta debitar 1 crédito antes da execução do trabalho principal. Se o servidor encontrar um erro não interceptado após a cobrança, o crédito é reembolsado — você não será cobrado por essa falha.

As rotas com tarifação por quilômetro incluem:

• Todos /api/v1/tiktok-shop/* pontos finais.
• GET /api/v1/adlibrary.
• POST /api/v1/magic-ai.
• GET /api/v1/store-tracker, POST /api/v1/store-explorer.
• GET /api/v1/marcas.

Sem versão /api/adlibrary, /api/store-tracker, e /api/store-explorer continuam sendo aceitos como aliases (mesma medição). /api/magic-ai e /api/marcas são painel rotas — para uso com uma chave de API /api/v1/magic-ai e /api/v1/marcas.

Antes de qualquer crédito ser debitado, essas respostas são retornadas sem cobrança (e não contam para o limite da tarifa por minuto):

• 401 Acesso não autorizado — chave ausente ou inválida.
• 403 — O acesso à API não está habilitado para esta conta.

Respostas corretas e a maioria 429 linhas são registrados e contabilizados para o 60 rpm janela (ver Limites de taxa).

Painel vs API#

O aplicativo do navegador pode aplicar uma política de medição diferente daquela das chamadas diretas à API. Para integrações, considere 1 crédito por solicitação mediada bem-sucedida, a menos que seu contrato indique o contrário.

Acompanhamento do uso do crédito#

Programático#

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

Retorna o mesmo { usado, limite, restante } a forma que o corpo 429 apresenta. Custa 1 crédito (sim, verificar o saldo consome um crédito; armazene-o no lado do cliente).

Painel#

Enquanto estiver conectado:

• GET /api — widget de créditos visuais + gráfico de uso de 14 dias + registro de solicitações recentes.
• GET /api/usage — JSON: { usage: [{ day, requests }, …], credits: { used, limit, remaining } }.
• GET /api/logs?page=N — Registro de solicitações paginado em páginas de 50 entradas, com códigos de status e endereços IP.

Esses três são cookies de sessão. Eles não consomem créditos.

MCP e créditos#

Protocolo de Contexto de Modelo usa o mesmo fundo comum mensal (20.000). Cada MCP bem-sucedido ferramentas/chamada acusações 1 crédito — incluindo ferramentas como verificar créditos. inicializar, ferramentas/lista, ping, etc. fazem não cobrança.

O tráfego da ferramenta MCP tem o seu próprio limite de tráfego por minuto (ver MCP); não substitui a seção sobre limitação de taxa REST deste guia para /api/*.

Planejamento de capacidade#

Para cargas de trabalho contínuas de ETL ou preenchimento retroativo, baseie o projeto na capacidade diária, e não na capacidade por minuto. O limite de taxa restringe os picos (60/min); a cota de crédito restringe o volume (20.000/mês).

Estratégias para aproveitar ao máximo seus créditos#

• Lote com POST JSON. Conjuntos grandes de filtros em uma única solicitação são mais eficientes do que muitos conjuntos pequenos.
• Armazene em cache as consultas estáveis. Hierarquias de categorias, listas de países, predefinições de filtro — recupere no máximo uma vez por dia.
• Utilização contar antes explorar quando você só precisa de um número.
• Não faça a votação créditos de forma agressiva — cada chamada custa 1 crédito. Acompanhe o uso no lado do cliente por meio do seu próprio contador de respostas e sincronize novamente a partir de /api/v1/tiktok-shop/créditos uma vez por hora.

Comportamento de reinicialização#

A contagem de uso é reiniciada no início de cada mês civil (UTC) no servidor. A primeira solicitação contabilizada em um novo mês recebe automaticamente um novo contador.

E quanto às alterações no plano?#

• Atualização no meio do mês: seu contador de crédito atual continua acumulando; o limite permanece em 20.000 (a cota é por usuário, não por plano).
• Perda de acesso à API: as chamadas cobradas por uso retornam o código 403 até que o acesso seja restaurado; os contadores de uso anteriores geralmente são mantidos se você reativar o acesso no mesmo período — verifique no painel.
• Necessidades de volume maior: entre em contato com o suporte para discutir um limite personalizado.