Σύνδεσμοι
Πεδία αιτήματος, αποτελέσματα ανά σύνδεσμο και επαναλαμβανόμενα αιτήματα.
Δημιουργία συνδέσμων
Το 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· αυτό το endpoint δεν μετατρέπει το περιεχόμενό του. |
Για υπολογιστικό φύλλο, χρησιμοποιήστε το 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 ώρες, ο ίδιος λογαριασμός, το ίδιο κλειδί και το ίδιο επικυρωμένο αίτημα επιστρέφουν ξανά την αρχική κατάσταση, το ίδιο σώμα byte προς byte και τις αρχικές κεφαλίδες, μαζί με το αρχικό 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.
Ένα αίτημα που κατέρρευσε μπορεί να παραμείνει σε εξέλιξη μέχρι να λήξει το κλειδί. Αυτή η επανάληψη αιτήματος είναι ανεξάρτητη από την παραπάνω επαναχρησιμοποίηση συνδέσμων που ταιριάζουν.