Link
Campi della richiesta, risultati per link e richieste ripetute.
Creare link
POST https://www.ninjabuy.com/api/v1/links richiede un token bearer e Content-Type: application/json.
| Campo | Regole |
|---|---|
links | Array obbligatorio da 1 a 2.000 stringhe. Gli spazi iniziali e finali di ogni input vengono rimossi; l'input deve contenere da 1 a 4.096 caratteri. |
campaign | Facoltativo, da 3 a 64 lettere minuscole, cifre o trattini, iniziando con una lettera o una cifra: ^[a-z0-9][a-z0-9-]{2,63}$. Le visite lo trasmettono come utm_campaign. |
label | Nome facoltativo nell'elenco dei tuoi link: da 1 a 40 caratteri stampabili dopo la rimozione degli spazi iniziali e finali, senza caratteri di controllo. La rimozione genera un avviso. |
async | Booleano facoltativo. true avvia sempre un'operazione in background. |
È possibile convertire link di prodotti Taobao, Tmall, Weidian e 1688, link di agenti di acquisto e link brevi supportati, negozi Weidian e Taobao (anche la loro pagina su un agente supportato) e pagine pubbliche NinjaBuy supportate. È accettato un URL NinjaBuy o un semplice percorso come /search?q=hoodie. Incollando un link di invito NinjaBuy esistente crei il tuo link con attribuzione verso la stessa destinazione.
Risposta immediata o batch
Fino a 100 input senza async: true restituiscono 200 con results, warnings e request_id. Più di 100, oppure async: true, restituiscono 202 con un'operazione, Location e Retry-After. Consulta Guida rapida e Operazioni.
I risultati mantengono l'ordine degli input, inclusi quelli ripetuti. Ogni riga ha input e status, con target, url, code e note facoltativi.
| Stato | Significato |
|---|---|
ok | Convertito; url è il link NinjaBuy con attribuzione. |
unsupported | Riconosciuto, ma non può ricevere un link, per esempio un marketplace non supportato o una pagina privata NinjaBuy. |
unreadable | Non è stato possibile leggere una destinazione utilizzabile. |
sheet | URL Google Sheets; questo endpoint non ne converte il contenuto. |
Per un foglio, usa l’API dei fogli di calcolo per convertirne il contenuto in XLSX, oppure incollalo su NinjaBuy. Una pagina NinjaBuy esistente /spreadsheets/d/<sheet id> può ricevere un proprio link con attribuzione.
Richieste ripetute e attribuzione
Per lo stesso account, destinazione normalizzata, campagna ed etichetta, la creazione restituisce lo stesso link in REST, MCP ed elaborazione in batch. Una campagna o un'etichetta diversa produce un link separato. Senza Idempotency-Key, ripetere un batch crea comunque una nuova operazione; il riutilizzo dei link non elimina invii duplicati di operazioni.
I nuovi link REST registrano createdVia: "api". Riutilizzare un link ne conserva l'origine (api, mcp, share o redirect). Questo campo è disponibile nei risultati MCP list_links e link, non nella risposta di creazione REST. Consulta Inviti per attribuzione e report.
Idempotency-Key
Puoi inviare Idempotency-Key con POST /api/v1/links, POST /api/v1/uploads o POST /api/v1/sheets per ripetere una richiesta senza creare un’altra operazione né consumare un’altra chiamata di creazione link. Usa una chiave univoca per ogni richiesta prevista: da 1 a 255 caratteri ASCII stampabili.
Idempotency-Key: partner-batch-2026-10-23-001Per 24 ore, lo stesso account, chiave e richiesta validata riproducono lo stato, il corpo identico byte per byte e gli header originali, incluso il request_id originale, con Idempotent-Replayed: true. L’ordine delle chiavi degli oggetti JSON non conta. Dopo 24 ore la chiave può essere riutilizzata.
- Un corpo o percorso POST diverso con la stessa chiave restituisce
422(idempotency-key-reused); usa una nuova chiave. - Mentre la prima richiesta è in corso, i nuovi tentativi restituiscono
409(idempotency-key-in-progress) conRetry-After; attendi prima di riprovare. - Una chiave non valida restituisce
400(bad-idempotency-key). I corpi non validi non riservano una chiave. - Quando l’esecuzione inizia, la prima risposta viene memorizzata, inclusi gli errori. Una risposta
429non viene memorizzata: riprova con la stessa chiave dopoRetry-After.
Una richiesta interrotta può rimanere in corso fino alla scadenza della chiave. Questa riproduzione delle richieste è distinta dal riutilizzo dei link corrispondenti descritto sopra.