Linki
Pola żądania, wyniki dla poszczególnych linków i powtarzane żądania.
Tworzenie linków
POST https://www.ninjabuy.com/api/v1/links wymaga tokenu Bearer i Content-Type: application/json.
| Pole | Reguły |
|---|---|
links | Wymagana tablica od 1 do 2 000 ciągów znaków. Usuwane są otaczające białe znaki; każda wartość musi mieć od 1 do 4 096 znaków. |
campaign | Opcjonalnie, od 3 do 64 małych liter, cyfr lub łączników, zaczynając od litery lub cyfry: ^[a-z0-9][a-z0-9-]{2,63}$. Wizyty przekazują tę wartość jako utm_campaign. |
label | Opcjonalna nazwa na liście linków: od 1 do 40 drukowalnych znaków po usunięciu otaczających białych znaków, bez znaków sterujących. Usunięcie białych znaków powoduje ostrzeżenie. |
async | Opcjonalna wartość logiczna. true zawsze uruchamia zadanie w tle. |
Można przekształcać linki produktów z Taobao, Tmall, Weidian i 1688, obsługiwane linki i krótkie linki agentów zakupowych, sklepy Weidian i Taobao (także ich strony u obsługiwanego pośrednika) oraz obsługiwane publiczne strony NinjaBuy. Przyjmowany jest URL NinjaBuy lub sama ścieżka, np. /search?q=hoodie. Wklejenie istniejącego linku polecającego NinjaBuy tworzy twój własny przypisany link do tego samego celu.
Bezpośrednio lub wsadowo
Do 100 danych wejściowych bez async: true zwraca 200 z results, warnings i request_id. Ponad 100 lub async: true zwraca 202 z zadaniem, Location i Retry-After. Zobacz Szybki start i Zadania.
Wyniki zachowują kolejność danych wejściowych, także powtórzeń. Każdy wiersz zawiera input i status, a opcjonalnie target, url, code i note.
| Status | Znaczenie |
|---|---|
ok | Przekształcono; url to przypisany link NinjaBuy. |
unsupported | Rozpoznano, ale nie można utworzyć linku, np. do nieobsługiwanej platformy lub prywatnej strony NinjaBuy. |
unreadable | Nie udało się odczytać użytecznego celu. |
sheet | URL Google Sheet; ten punkt końcowy nie przekształca zawartości arkusza. |
W przypadku arkusza użyj API Arkuszy, aby przekonwertować zawartość na XLSX, lub wklej go w NinjaBuy. Istniejąca strona NinjaBuy /spreadsheets/d/<sheet id> może sama otrzymać przypisany link.
Powtarzane żądania i przypisanie
Dla tego samego konta, znormalizowanego celu, kampanii i etykiety tworzenie zwraca ten sam link w REST, MCP i przetwarzaniu wsadowym. Inna kampania lub etykieta daje osobny link. Bez Idempotency-Key ponowne wysłanie partii tworzy nowe zadanie; ponowne użycie linków nie deduplikuje zadań.
Nowe linki REST zapisują createdVia: "api". Ponowne użycie linku zachowuje pierwotne źródło (api, mcp, share lub redirect). To pole jest dostępne w wynikach MCP list_links i link, a nie w odpowiedzi REST na tworzenie. Zobacz Polecenia, aby poznać przypisanie i raporty.
Idempotency-Key
Opcjonalnie wyślij Idempotency-Key z POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets, aby ponowić żądanie bez utworzenia kolejnego zadania ani zużycia kolejnego wywołania tworzenia linków. Dla każdego zamierzonego żądania użyj unikalnego klucza: od 1 do 255 drukowalnych znaków ASCII.
Idempotency-Key: partner-batch-2026-10-23-001Przez 24 godziny to samo konto, klucz i zweryfikowane żądanie odtwarzają pierwotny status, identyczną bajtowo treść i nagłówki, w tym pierwotny request_id, z Idempotent-Replayed: true. Kolejność kluczy obiektu JSON nie ma znaczenia. Po 24 godzinach klucz można wykorzystać ponownie.
- Inna treść lub trasa POST z tym samym kluczem zwraca
422(idempotency-key-reused); użyj nowego klucza. - Gdy pierwsze żądanie nadal działa, ponowienia zwracają
409(idempotency-key-in-progress) zRetry-After; poczekaj przed kolejną próbą. - Nieprawidłowy klucz zwraca
400(bad-idempotency-key). Nieprawidłowa treść nie rezerwuje klucza. - Po rozpoczęciu wykonania pierwsza odpowiedź jest zapisywana, również w przypadku błędów.
429nie jest zapisywane: ponów z tym samym kluczem poRetry-After.
Przerwane przez awarię żądanie może pozostawać w toku aż do wygaśnięcia klucza. Odtwarzanie żądania jest niezależne od ponownego użycia pasujących linków opisanego wyżej.