Links
Campos de solicitação, resultados por link e solicitações repetidas.
Criar links
POST https://www.ninjabuy.com/api/v1/links exige um token bearer e Content-Type: application/json.
| Campo | Regras |
|---|---|
links | Array obrigatório de 1 a 2.000 strings. Os espaços nas extremidades são removidos de cada entrada, que deve ter de 1 a 4.096 caracteres. |
campaign | Opcional, de 3 a 64 letras minúsculas, dígitos ou hífens, começando com uma letra ou um dígito: ^[a-z0-9][a-z0-9-]{2,63}$. As visitas o carregam como utm_campaign. |
label | Nome opcional na sua lista de links: de 1 a 40 caracteres imprimíveis após remover espaços nas extremidades, sem caracteres de controle. A remoção de espaços gera um aviso. |
async | Booleano opcional. true sempre inicia uma tarefa em segundo plano. |
É possível converter links de produtos do Taobao, Tmall, Weidian e 1688, links de agentes de compras e links curtos compatíveis, lojas do Weidian e do Taobao (incluindo a página delas em um agente compatível) e páginas públicas compatíveis da NinjaBuy. Uma URL da NinjaBuy ou um caminho como /search?q=hoodie é aceito. Colar um link de indicação existente da NinjaBuy cria seu próprio link com atribuição para o mesmo destino.
Resposta imediata ou lote
Até 100 entradas sem async: true retornam 200 com results, warnings e request_id. Mais de 100, ou async: true, retornam 202 com uma tarefa, Location e Retry-After. Veja Início rápido e Tarefas.
Os resultados preservam a ordem de entrada, incluindo entradas repetidas. Cada linha tem input e status, com target, url, code e note opcionais.
| Status | Significado |
|---|---|
ok | Convertido; url é o link da NinjaBuy com atribuição. |
unsupported | Reconhecido, mas não pode receber um link, como um marketplace incompatível ou uma página privada da NinjaBuy. |
unreadable | Não foi possível ler um destino utilizável. |
sheet | URL do Google Sheets; este endpoint não converte seu conteúdo. |
Para uma planilha, use a API de planilhas para converter seu conteúdo em XLSX, ou cole-a na NinjaBuy. Uma página existente da NinjaBuy /spreadsheets/d/<sheet id> pode receber seu próprio link com atribuição.
Solicitações repetidas e atribuição
Para a mesma conta, destino normalizado, campanha e rótulo, a criação retorna o mesmo link em REST, MCP e processamento em lote. Uma campanha ou um rótulo diferente gera um link separado. Sem Idempotency-Key, tentar novamente um lote ainda cria uma nova tarefa; a reutilização de links não elimina envios duplicados de tarefas.
Novos links REST registram createdVia: "api". A reutilização de um link preserva sua origem (api, mcp, share ou redirect). Esse campo está disponível nos resultados MCP list_links e link, não na resposta de criação REST. Veja Indicações para atribuição e relatórios.
Idempotency-Key
Opcionalmente, envie Idempotency-Key em POST /api/v1/links, POST /api/v1/uploads ou POST /api/v1/sheets para repetir uma solicitação sem criar outra tarefa nem consumir outra chamada de criação de links. Use uma chave única para cada solicitação pretendida: de 1 a 255 caracteres ASCII imprimíveis.
Idempotency-Key: partner-batch-2026-10-23-001Por 24 horas, a mesma conta, chave e solicitação validada reproduzem o status, o corpo idêntico byte a byte e os cabeçalhos originais, incluindo o request_id original, com Idempotent-Replayed: true. A ordem das chaves de objetos JSON não importa. Após 24 horas, a chave pode ser reutilizada.
- Um corpo ou rota POST diferente com a mesma chave retorna
422(idempotency-key-reused); use uma nova chave. - Enquanto a primeira solicitação estiver em execução, novas tentativas retornam
409(idempotency-key-in-progress) comRetry-After; espere antes de tentar novamente. - Uma chave inválida retorna
400(bad-idempotency-key). Corpos inválidos não reservam uma chave. - Após o início da execução, a primeira resposta é armazenada, incluindo erros. Um
429não é armazenado: tente novamente com a mesma chave apósRetry-After.
Uma solicitação interrompida pode permanecer em execução até a chave expirar. Essa reprodução de solicitações é independente da reutilização de links correspondentes descrita acima.