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.
Ambiente de teste (sandbox)
Para montar e testar a integração sem gastar crédito, crie no console uma chave de teste e envie Authorization: Bearer sdx_test_.... As mesmas rotas /v1 respondem no mesmo formato, a partir de um conjunto fixo de dados fictícios: os ids e os números são sempre os mesmos, então você pode escrever testes que se repetem.
A chave decide o ambiente. A chave de teste funciona em https://developers.sendyx.com/v1 e em https://sandbox.sendyx.com/v1; o endereço de teste aceita só chave de teste. Uma chave de produção no endereço de teste, ou uma chave de teste fora de /v1, recebe o mesmo 401 invalid_credentials de qualquer chave inválida. Cada conta pode ter até 5 chaves ativas de teste, além das 5 de produção.
Na chave de teste nada é cobrado nem exigido: sem saldo, sem aceite dos termos de uso, sem conta madura. A API não consulta a fonte de dados nem o banco de produção. Toda resposta traz X-Sendyx-Environment: sandbox, x-credits-cost: 0.00 e x-credits-remaining: 1000.00 (saldo fictício). O corpo tem o mesmo envelope da produção.
Dados de teste
O catálogo tem 24 produtos fictícios, com os mesmos filtros, ordenações e paginação de GET /v1/products, e a Brecha e as categorias saem dele. Nomes, lojas, vídeos, lives e criadores são inventados; imagens apontam para exemplo.invalid. Os contatos de criador (GET /v1/creators/{id}/contacts) são fictícios (@exemplo.invalid) e a rota responde no teste mesmo quando está indisponível em produção. As listas de vídeos, criadores, lojas, lives e categorias trazem poucos itens.
Regra dos ids. Todo id que uma lista do teste devolve abre o detalhe, a análise, a série e as listas aninhadas: você pode ir da lista ao detalhe com o id que recebeu. Na prática, qualquer id de 19 dígitos que começa com 999 (os ids fictícios do teste) é aceito e devolve sempre o mesmo corpo, com o id que você pediu. Os da tabela abaixo são exemplos. Categoria também abre o id da taxonomia que o ranking de categorias devolve. Qualquer outro id responde 404 nos detalhes e lista vazia nas listas por entidade, como a rota real.
| Rota | Id de teste |
|---|---|
| GET /v1/products/{id}, /analysis, /videos, /creators | 9990969421641471500 |
| GET /v1/products/{id}/trend | 9990866258189766001 |
| GET /v1/videos/{id} | 9990766912945219402 |
| GET /v1/videos/{id}/products | 9990766912945219402 |
| GET /v1/creators/{id} e /contacts | 9993000000000000001 |
| GET /v1/creators/{id}/products | 9993000000000000001 |
| GET /v1/shops/{id} | 9990820431382416103 |
| GET /v1/shops/{id}/products, /videos, /creators | 9990820431382416103 |
| GET /v1/lives/{id} | 9990114260194168264 |
| GET /v1/lives/{id}/products | 9990114260194168264 |
| GET /v1/categories/{id} | 9990206017089333354 |
Exemplo de um item de GET /v1/products no teste:
{
"id": "9990969421641471500",
"name": "Sérum Facial de Exemplo 01",
"coverUrl": "https://exemplo.invalid/sandbox/produto-01.jpg",
"productUrl": "https://exemplo.invalid/sandbox/produto/9990969421641471500",
"productLinks": {
"web": "https://exemplo.invalid/sandbox/produto/9990969421641471500",
"app": "https://exemplo.invalid/sandbox/app/produto/9990969421641471500"
},
"categoryL1": {
"id": "601450",
"name": "Beleza"
},
"categoryL2": {
"id": "990101",
"name": "Cuidados com a pele (exemplo)"
},
"categoryL3": {
"id": "990111",
"name": "Séruns (exemplo)"
},
"shopName": "Loja Exemplo 01",
"reviewCount": 120,
"minPrice": 3200,
"maxPrice": 4800,
"commission": 0.08,
"revenue": 106375,
"sales": 2659,
"revenue30d": 462500,
"sales30d": 11563,
"sales7d": 2659,
"revenuePerCreator": 13602.94,
"acceleration": 0.89,
"trend": [
308,
578,
463,
347,
617,
501,
385,
270,
540,
424,
308,
578,
463,
347
],
"state": "exploding",
"launchDate": "2026-02-02",
"rank": 1,
"prevRank": 1,
"channel": {
"videoRevenue": 231250,
"liveRevenue": 138750,
"creatorsMeasured": 34
}
}
Limites do teste
Até 1000 chamadas por dia por conta, somando todas as chaves de teste. O dia vira à meia-noite de Brasília (horário de São Paulo). Acima disso a resposta é 429 rate_limited com Retry-After até a virada. Há também um limite de 60 chamadas por minuto por chave. O console mostra o uso do dia e as chamadas recentes.
Simular erros
Envie o cabeçalho x-sandbox-scenario com um dos valores abaixo e a API devolve exatamente o erro real, sem gastar nada. A chave de produção ignora esse cabeçalho. Valor desconhecido é 400.
| Valor | Status | error | Quando |
|---|---|---|---|
insufficient_credits | 402 | insufficient_credits | Saldo insuficiente. O corpo traz required e available. |
rate_limited | 429 | rate_limited | Limite de requisições. Vem com Retry-After. |
not_found | 404 | not_found | Recurso não encontrado. |
upstream_unavailable | 503 | upstream_unavailable | Serviço de dados indisponível. Vem com Retry-After. |
Corpo do 402 forçado por insufficient_credits:
{
"error": "insufficient_credits",
"message": "Créditos insuficientes.",
"required": 0.1,
"available": 0,
"requestId": "3f6c1d2e-8a4b-4c7e-9b1a-5d2e7f9a0c11"
}
Exemplo de chamada de teste (a chave de teste fica em SENDYX_API_KEY):
curl -G 'https://sandbox.sendyx.com/v1/products' \
-H "Authorization: Bearer $SENDYX_API_KEY" \
--data-urlencode 'sortBy=revenue'
const params = new URLSearchParams({
"sortBy": "revenue",
});
const res = await fetch(`https://sandbox.sendyx.com/v1/products?${params}`, {
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://sandbox.sendyx.com/v1/products",
headers={"Authorization": f"Bearer {os.environ['SENDYX_API_KEY']}"},
params={
"sortBy": "revenue",
},
)
response.raise_for_status()
print(
"custo:", response.headers.get("x-credits-cost"),
"saldo:", response.headers.get("x-credits-remaining"),
)
print(response.json())
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 um criador são uma consulta extra: 0,02 crédito quando você já buscou o criador nas últimas 24 horas, ou 0,12 crédito (0,10 do criador mais 0,02 dos contatos) quando ele ainda não foi buscado. Pedir os contatos do mesmo criador de novo custa 0,02 por pedido. É preciso ter aceitado os termos de uso da API no console.
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
| Cabeçalho | Significado |
|---|---|
| x-credits-cost | Créditos cobrados por esta resposta, sempre com duas casas decimais (por exemplo 0.10, 0.02 ou 0.12). Vem nas respostas 200, no 402 (com 0.00) e nos erros que acontecem depois da cobrança e foram estornados, como 404 e 503 (com 0.00). Não vêm no 401, no 429 nem nos 400 de parâmetro, que são recusados antes da cobrança. |
| x-credits-remaining | Saldo restante em créditos, sempre com duas casas decimais (por exemplo 4.90). Nas mesmas respostas do cabeçalho acima; no 402 é o saldo atual. |
| x-request-id | Identificador da requisição. Informe-o ao falar com o suporte. |
| Retry-After | Presente no 429 e no 503: segundos até poder tentar de novo. |
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.
Mercados
O parâmetro region escolhe o mercado e o padrão é BR. Duas rotas existem só para o Brasil: pedir region=US nelas é 400 e nada é cobrado. As demais aceitam BR e US.
| Mercado | Rotas | Moeda |
|---|---|---|
| BR | Só BR: árvore de categorias (GET /v1/categories) e contatos de criador (GET /v1/creators/{id}/contacts). | BRL |
| BR e US | Catálogo (GET /v1/products), detalhe de produto (GET /v1/products/{id}) e Brecha (GET /v1/brecha); ranking geral de produtos (GET /v1/products/ranking) e as demais rotas do gateway: rankings e detalhes de vídeos, criadores, categorias, lojas e lives, produtos de uma entidade, e vídeos, criadores, análise e série de um produto. | BRL no BR, USD nos EUA |
Os dados dos EUA vêm como a fonte entrega: nomes, títulos e categorias em inglês e valores em USD, sem tradução nem conversão de moeda. O campo meta.currency diz a moeda de cada resposta.
Em GET /v1/products, GET /v1/products/{id} e GET /v1/brecha, enquanto o catálogo dos EUA ainda não está visível, a resposta US vem vazia (404 no detalhe) e nada é cobrado (x-credits-cost: 0.00). Na Brecha US, o piso minRevenue30d (padrão 10000) vale em dólar.
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.
| Código | error | Quando |
|---|---|---|
| 401 | missing_credentials | Cabeçalho Authorization ausente. |
| 401 | invalid_credentials | Chave inválida ou revogada. |
| 402 | insufficient_credits | Saldo menor que o custo. Traz required e available, em créditos. |
| 429 | rate_limited | Limite de requisições excedido. Veja o cabeçalho Retry-After. |
| 400 | validation_error | Parâmetro inválido, desconhecido ou fora dos limites. |
| 404 | not_found | Recurso inexistente. |
| 500 | internal_error | Falha nossa. O crédito é devolvido. |
| 503 | upstream_disabled | O serviço de dados está desligado. Nada é cobrado. |
| 503 | upstream_budget_exceeded | O limite de consultas do serviço de dados acabou por agora. Tente mais tarde. Nada é cobrado. |
| 503 | upstream_unavailable | O serviço de dados falhou, está ocupado ou a fila de buscas ao vivo está cheia. Tente de novo depois do tempo de Retry-After. Nada é cobrado. |
| 429 | contacts_daily_limit | Limite diário de consultas de contato da conta atingido (soma de todas as chaves). Veja Retry-After. Nada é cobrado. |
| 429 | miss_quota_exceeded | Cota de buscas novas nos últimos 60 minutos atingida, por chave e por conta (consultas já em cache não contam). A janela é móvel: as vagas voltam aos poucos, veja Retry-After. Nada é cobrado. |
| 429 | daily_spend_limit_exceeded | Limite diário de gasto da conta atingido (soma de todas as chaves; renova à meia-noite UTC). Veja Retry-After. Nada é cobrado. |
| 403 | terms_not_accepted | Os termos de uso da API não foram aceitos pelo dono da chave. Aceite no console. Nada é cobrado. |
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())