Ссылки
Поля запроса, результаты отдельных ссылок и повторные запросы.
Создание ссылок
POST https://www.ninjabuy.com/api/v1/links требует Bearer-токен и Content-Type: application/json.
| Поле | Правила |
|---|---|
links | Обязательный массив от 1 до 2 000 строк. У каждого значения удаляются пробельные символы по краям; длина должна быть от 1 до 4 096 символов. |
campaign | Необязательно: от 3 до 64 строчных букв, цифр или дефисов, начиная с буквы или цифры: ^[a-z0-9][a-z0-9-]{2,63}$. При посещениях значение передаётся как utm_campaign. |
label | Необязательное название в списке ссылок: от 1 до 40 печатных символов после удаления пробелов по краям, без управляющих символов. Удаление пробелов сопровождается предупреждением. |
async | Необязательное логическое значение. true всегда запускает фоновое задание. |
Можно преобразовывать ссылки товаров Taobao, Tmall, Weidian и 1688, поддерживаемые ссылки и короткие ссылки агентов по закупкам, магазины Weidian и Taobao (включая их страницы у поддерживаемых посредников) и поддерживаемые публичные страницы NinjaBuy. Принимается URL NinjaBuy или путь, например /search?q=hoodie. Вставка существующей реферальной ссылки NinjaBuy создаёт вашу собственную привязанную ссылку на ту же цель.
Сразу или пакетом
До 100 значений без async: true возвращают 200 с results, warnings и request_id. Более 100 или async: true возвращают 202 с заданием, Location и Retry-After. См. Быстрый старт и Задания.
Результаты сохраняют порядок ввода, включая повторы. Каждая строка содержит input и status, а также необязательные target, url, code и note.
| Статус | Значение |
|---|---|
ok | Преобразовано; url — ссылка NinjaBuy с привязкой к аккаунту. |
unsupported | Распознано, но ссылку создать нельзя, например для неподдерживаемой площадки или закрытой страницы NinjaBuy. |
unreadable | Не удалось прочитать подходящую цель. |
sheet | URL Google Sheet; этот адрес API не преобразует содержимое таблицы. |
Для таблицы используйте API таблиц, чтобы преобразовать содержимое в XLSX, или вставьте её в NinjaBuy. Существующая страница NinjaBuy /spreadsheets/d/<sheet id> сама может получить привязанную ссылку.
Повторные запросы и атрибуция
Для одного аккаунта, нормализованной цели, кампании и метки создание возвращает одну и ту же ссылку в REST, MCP и пакетной обработке. Другая кампания или метка получает отдельную ссылку. Без Idempotency-Key повторная отправка пакета создаёт новое задание; повторное использование ссылок не устраняет дубли заданий.
Новые REST-ссылки сохраняют createdVia: "api". При повторном использовании сохраняется исходный источник (api, mcp, share или redirect). Поле доступно в результатах MCP list_links и link, но не в REST-ответе на создание. Об атрибуции и отчётах см. Рекомендации.
Idempotency-Key
При необходимости передайте Idempotency-Key в POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets, чтобы повторить запрос без создания ещё одного задания и расхода ещё одного вызова создания ссылок. Для каждого задуманного запроса используйте уникальный ключ: от 1 до 255 печатных символов ASCII.
Idempotency-Key: partner-batch-2026-10-23-001В течение 24 часов одинаковые аккаунт, ключ и проверенный запрос воспроизводят исходный статус, побайтово идентичное тело и заголовки, включая исходный request_id, с Idempotent-Replayed: true. Порядок ключей JSON-объекта не имеет значения. Через 24 часа ключ можно использовать заново.
- Другое тело или маршрут POST с тем же ключом возвращает
422(idempotency-key-reused); используйте новый ключ. - Пока первый запрос выполняется, повторы возвращают
409(idempotency-key-in-progress) сRetry-After; подождите перед повторной попыткой. - Неверный ключ возвращает
400(bad-idempotency-key). Неверное тело не резервирует ключ. - После начала выполнения первый ответ сохраняется, включая ошибки.
429не сохраняется: повторите с тем же ключом послеRetry-After.
Запрос, прерванный сбоем, может оставаться в работе до истечения срока ключа. Это воспроизведение запроса не связано с повторным использованием совпадающих ссылок, описанным выше.