Liens
Champs des requêtes, résultats par lien et requêtes répétées.
Créer des liens
POST https://www.ninjabuy.com/api/v1/links nécessite un jeton bearer et Content-Type: application/json.
| Champ | Règles |
|---|---|
links | Tableau obligatoire de 1 à 2 000 chaînes. Les espaces en début et fin de chaque entrée sont supprimés ; elle doit contenir de 1 à 4 096 caractères. |
campaign | Facultatif, de 3 à 64 lettres minuscules, chiffres ou tirets, en commençant par une lettre ou un chiffre : ^[a-z0-9][a-z0-9-]{2,63}$. Les visites le transmettent comme utm_campaign. |
label | Nom facultatif dans votre liste de liens : de 1 à 40 caractères imprimables après suppression des espaces aux extrémités, sans caractères de contrôle. Cette suppression produit un avertissement. |
async | Booléen facultatif. true lance toujours une tâche en arrière-plan. |
Il est possible de convertir les liens de produits Taobao, Tmall, Weidian et 1688, les liens d'agents d'achat et liens courts pris en charge, les boutiques Weidian et Taobao (y compris leur page chez un agent pris en charge) et les pages publiques NinjaBuy prises en charge. Une URL NinjaBuy ou un simple chemin tel que /search?q=hoodie est accepté. Coller un lien de parrainage NinjaBuy existant crée votre propre lien avec attribution vers sa cible.
Réponse immédiate ou traitement par lot
Jusqu'à 100 entrées sans async: true renvoient 200 avec results, warnings et request_id. Au-delà de 100, ou avec async: true, la réponse est 202 avec une tâche, Location et Retry-After. Consultez Démarrage rapide et Tâches.
Les résultats préservent l'ordre des entrées, y compris les doublons. Chaque ligne comporte input et status, avec éventuellement target, url, code et note.
| Statut | Signification |
|---|---|
ok | Converti ; url est le lien NinjaBuy avec attribution. |
unsupported | Reconnu, mais ne peut pas recevoir de lien, par exemple une marketplace non prise en charge ou une page privée NinjaBuy. |
unreadable | Aucune cible exploitable n'a pu être lue. |
sheet | URL Google Sheets ; cet endpoint ne convertit pas son contenu. |
Pour une feuille, utilisez l’API de feuilles de calcul pour convertir son contenu en XLSX, ou collez-la sur NinjaBuy. Une page NinjaBuy existante /spreadsheets/d/<sheet id> peut elle-même recevoir un lien avec attribution.
Requêtes répétées et attribution
Pour un même compte, une même cible normalisée, une même campagne et un même libellé, la création renvoie le même lien dans REST, MCP et le traitement par lots. Une campagne ou un libellé différent produit un lien distinct. Sans Idempotency-Key, relancer un lot crée toujours une nouvelle tâche ; la réutilisation des liens ne déduplique pas les soumissions de tâches.
Les nouveaux liens REST enregistrent createdVia: "api". Réutiliser un lien conserve sa source d'origine (api, mcp, share ou redirect). Ce champ est disponible dans les résultats MCP list_links et link, pas dans la réponse de création REST. Consultez Parrainage pour l'attribution et les rapports.
Idempotency-Key
Vous pouvez envoyer Idempotency-Key avec POST /api/v1/links, POST /api/v1/uploads ou POST /api/v1/sheets pour répéter une requête sans créer une autre tâche ni consommer un autre appel de création de liens. Utilisez une clé unique pour chaque requête souhaitée : de 1 à 255 caractères ASCII imprimables.
Idempotency-Key: partner-batch-2026-10-23-001Pendant 24 heures, le même compte, la même clé et la même requête validée reproduisent le statut, le corps identique octet par octet et les en-têtes d’origine, y compris le request_id d’origine, avec Idempotent-Replayed: true. L’ordre des clés des objets JSON est sans importance. Après 24 heures, la clé peut être réutilisée.
- Un corps ou une route POST différente avec la même clé renvoie
422(idempotency-key-reused) ; utilisez une nouvelle clé. - Tant que la première requête est en cours, les nouvelles tentatives renvoient
409(idempotency-key-in-progress) avecRetry-After; attendez avant de réessayer. - Une clé invalide renvoie
400(bad-idempotency-key). Les corps invalides ne réservent pas de clé. - Une fois l’exécution commencée, sa première réponse est enregistrée, y compris les erreurs. Une réponse
429n’est pas enregistrée : réessayez avec la même clé aprèsRetry-After.
Une requête interrompue peut rester en cours jusqu’à l’expiration de la clé. Cette reproduction de requêtes est distincte de la réutilisation des liens correspondants décrite ci-dessus.