Enlaces
Campos de solicitud, resultados por enlace y solicitudes repetidas.
Crear enlaces
POST https://www.ninjabuy.com/api/v1/links requiere un token bearer y Content-Type: application/json.
| Campo | Reglas |
|---|---|
links | Arreglo obligatorio de 1 a 2.000 cadenas. Se recortan los espacios de cada entrada, que debe tener de 1 a 4.096 caracteres. |
campaign | Opcional: de 3 a 64 letras minúsculas, dígitos o guiones, comenzando por una letra o un dígito: ^[a-z0-9][a-z0-9-]{2,63}$. Las visitas lo llevan como utm_campaign. |
label | Nombre opcional en tu lista de enlaces: de 1 a 40 caracteres imprimibles después de recortar espacios, sin caracteres de control. El recorte genera una advertencia. |
async | Booleano opcional. true siempre inicia un trabajo en segundo plano. |
Se pueden convertir enlaces de productos de Taobao, Tmall, Weidian y 1688, enlaces de agentes de compras y enlaces cortos compatibles, tiendas de Weidian y Taobao (también su página en un agente compatible) y páginas públicas compatibles de NinjaBuy. Se acepta una URL de NinjaBuy o una ruta como /search?q=hoodie. Al pegar un enlace de referido existente de NinjaBuy, creas tu propio enlace con atribución al mismo destino.
Respuesta inmediata o por lotes
Hasta 100 entradas sin async: true devuelven 200 con results, warnings y request_id. Más de 100, o async: true, devuelven 202 con un trabajo, Location y Retry-After. Consulta Inicio rápido y Trabajos.
Los resultados conservan el orden de entrada, incluidas las entradas repetidas. Cada fila tiene input y status, con target, url, code y note opcionales.
| Estado | Significado |
|---|---|
ok | Convertido; url es el enlace de NinjaBuy con atribución. |
unsupported | Reconocido, pero no se puede enlazar, por ejemplo un marketplace no compatible o una página privada de NinjaBuy. |
unreadable | No se pudo leer un destino utilizable. |
sheet | URL de Google Sheets; este endpoint no convierte su contenido. |
Si es una hoja, usa la API de hojas de cálculo para convertir su contenido a XLSX, o pégala en NinjaBuy. Una página existente de NinjaBuy /spreadsheets/d/<sheet id> puede recibir su propio enlace con atribución.
Solicitudes repetidas y atribución
Para la misma cuenta, destino normalizado, campaña y etiqueta, la creación devuelve el mismo enlace en REST, MCP y el procesamiento por lotes. Una campaña o etiqueta distinta produce un enlace independiente. Sin Idempotency-Key, reintentar un lote crea un trabajo nuevo; la reutilización de enlaces no elimina envíos de trabajos duplicados.
Los enlaces REST nuevos registran createdVia: "api". Reutilizar un enlace conserva su origen (api, mcp, share o redirect). Este campo está disponible en los resultados de MCP list_links y link, no en la respuesta de creación de REST. Consulta Referidos para la atribución y los informes.
Idempotency-Key
Opcionalmente, envía Idempotency-Key en POST /api/v1/links, POST /api/v1/uploads o POST /api/v1/sheets para reintentar una solicitud sin crear otro trabajo ni consumir otra llamada de creación de enlaces. Usa una clave única por solicitud prevista: de 1 a 255 caracteres ASCII imprimibles.
Idempotency-Key: partner-batch-2026-10-23-001Durante 24 horas, la misma cuenta, clave y solicitud validada reproducen el estado, el cuerpo idéntico byte a byte y los encabezados originales, incluido el request_id original, con Idempotent-Replayed: true. El orden de las claves de los objetos JSON no importa. Después de 24 horas puedes reutilizar la clave.
- Un cuerpo o ruta POST diferente con la misma clave devuelve
422(idempotency-key-reused); usa una clave nueva. - Mientras la primera solicitud está en curso, los reintentos devuelven
409(idempotency-key-in-progress) conRetry-After; espera antes de reintentar. - Una clave no válida devuelve
400(bad-idempotency-key). Los cuerpos no válidos no reservan la clave. - Una vez iniciada la ejecución, se almacena su primera respuesta, incluidos los errores. Un
429no se almacena: reintenta con la misma clave después deRetry-After.
Una solicitud interrumpida puede permanecer en curso hasta que caduque la clave. Esta reproducción de solicitudes es independiente de la reutilización de enlaces coincidentes descrita arriba.