Primeiros passos

Dados do catálogo de produtos do TikTok Shop em JSON, cobrados por crédito. Esta é a referência da versão 1.

URL base

https://developers.sendyx.com/v1

O contrato completo em formato OpenAPI está em /openapi.json.

Autenticação

Crie uma chave no console da Sendyx e envie no cabeçalho Authorization: Bearer sdx_live_.... Guarde a chave em uma variável de ambiente e nunca a coloque em código, em repositório ou em navegador. Ela é mostrada uma única vez.

Créditos

Cada requisição de lista ou de detalhe de qualquer entidade consome 0,10 crédito. Portanto 1 crédito equivale a 10 requisições. São gratuitos a árvore de categorias (GET /v1/categories) e o saldo (GET /v1/account/usage); as demais rotas de categorias, como GET /v1/categories/ranking, consomem o mesmo que as outras. O custo de cada rota aparece no topo da página dela.

Os contatos de criador estão indisponíveis por enquanto. A rota aparece no contrato, mas responde 503 sem cobrar enquanto o recurso não é liberado.

Se o serviço de dados estiver indisponível, a resposta é 503 e nenhum crédito é cobrado.

É preciso comprar créditos para usar a API. Uma conta nova começa com saldo zero, sem crédito de cortesia, e as rotas pagas respondem 402 até a primeira compra, feita no console da Sendyx. Créditos comprados não vencem.

O custo é debitado antes de a resposta ser servida. Requisição com parâmetro inválido (400) não cobra nada, e se ela terminar em erro depois da cobrança o crédito é devolvido na hora. Sem saldo suficiente a resposta é 402.

Cabeçalhos da resposta

As rotas /v1 aceitam só GET. Um HEAD recebe 405 com Allow: GET, sem consulta e sem cobrança.

Nos cabeçalhos os créditos são texto com duas casas. No corpo JSON os números são numéricos e o JSON não preserva zeros à direita: 0.10 no cabeçalho vira 0.1 no corpo.

Idade dos dados

As rotas de vídeos, criadores, categorias (ranking e detalhe), lojas, lives e análise de produto trazem meta.fetchedAt, o instante (ISO 8601) em que o dado foi obtido. As rotas de produtos e a árvore de categorias trazem meta.dataUpTo, o dia mais recente dos dados, no formato yyyy-MM-dd; a fonte tem um dia de atraso. Se o serviço de dados estiver indisponível, a resposta é 503 e nada é cobrado.

Formato de erro

Todo erro tem o formato { "error", "message", "requestId" }. O campo error é estável e pode ser usado em código.

Limites de taxa

Até 60 requisições por minuto e 10000 por dia, por chave. Há também um limite de 300 requisições por minuto por endereço IP, que vale inclusive para tentativas com chave errada. Ao exceder, a resposta é 429 com Retry-After.

Paginação e atualidade dos dados

As listas têm página de tamanho fixo em 10, com page de 1 a 50. A resposta traz pagination com page, pageSize, total e totalPages. O total é a contagem real de resultados, e totalPages nunca passa de 50, que é a última página que a API entrega (pedir a 51 é 400). Para chegar ao que está além dos 500 primeiros, refine por filtro e ordenação.

Toda resposta de dados traz meta.dataUpTo, o dia mais recente dos dados (a fonte tem um dia de atraso), e meta.currency, a moeda dos valores.

Sua primeira chamada

Consulte seu saldo. É gratuito:

curl 'https://developers.sendyx.com/v1/account/usage' \
  -H "Authorization: Bearer $SENDYX_API_KEY"

const res = await fetch("https://developers.sendyx.com/v1/account/usage", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.SENDYX_API_KEY}` },
});

if (!res.ok) {
  const error = await res.json();
  throw new Error(`${res.status} ${error.error}: ${error.message}`);
}

console.log(
  "custo:", res.headers.get("x-credits-cost"),
  "saldo:", res.headers.get("x-credits-remaining"),
);
const body = await res.json();
console.log(body);

import os
import requests

response = requests.get(
    "https://developers.sendyx.com/v1/account/usage",
    headers={"Authorization": f"Bearer {os.environ['SENDYX_API_KEY']}"},
)
response.raise_for_status()

print(
    "custo:", response.headers.get("x-credits-cost"),
    "saldo:", response.headers.get("x-credits-remaining"),
)
print(response.json())