Links
Aanvraagvelden, resultaten per link en herhaalde aanvragen.
Links aanmaken
POST https://www.ninjabuy.com/api/v1/links vereist een bearertoken en Content-Type: application/json.
| Veld | Regels |
|---|---|
links | Vereiste array van 1 tot 2.000 tekenreeksen. Witruimte rond elke invoerwaarde wordt verwijderd; de lengte moet 1 tot 4.096 tekens zijn. |
campaign | Optioneel, 3 tot 64 kleine letters, cijfers of koppeltekens, beginnend met een letter of cijfer: ^[a-z0-9][a-z0-9-]{2,63}$. Bezoeken nemen deze waarde mee als utm_campaign. |
label | Optionele naam in je linklijst: 1 tot 40 afdrukbare tekens na het verwijderen van witruimte, zonder besturingstekens. Verwijderde witruimte levert een waarschuwing op. |
async | Optionele boolean. true start altijd een achtergrondtaak. |
Productlinks van Taobao, Tmall, Weidian en 1688, ondersteunde links en korte links van shoppingagents, Weidian- en Taobao-winkels (ook de pagina van een ondersteunde agent ervoor) en ondersteunde openbare NinjaBuy-pagina's kunnen worden omgezet. Een NinjaBuy-URL of los pad zoals /search?q=hoodie wordt geaccepteerd. Als je een bestaande NinjaBuy-verwijslink plakt, krijg je je eigen toegeschreven link naar hetzelfde doel.
Direct of als batch
Tot 100 invoerwaarden zonder async: true krijg je 200 met results, warnings en request_id. Bij meer dan 100, of async: true, krijg je 202 met een taak, Location en Retry-After. Zie Snelstart en Taken.
Resultaten behouden de invoervolgorde, ook bij herhaalde invoerwaarden. Elke rij heeft input en status, met optioneel target, url, code en note.
| Status | Betekenis |
|---|---|
ok | Omgezet; url is de toegeschreven NinjaBuy-link. |
unsupported | Herkend maar niet te koppelen, bijvoorbeeld een niet-ondersteunde marktplaats of een afgeschermde NinjaBuy-pagina. |
unreadable | Er kon geen bruikbaar doel worden gelezen. |
sheet | Een Google Sheet-URL; dit endpoint zet de inhoud niet om. |
Voor een spreadsheet kun je de Spreadsheets-API gebruiken om de inhoud naar XLSX om te zetten, of deze op NinjaBuy plakken. Een bestaande NinjaBuy-pagina op /spreadsheets/d/<sheet id> kan zelf een toegeschreven link krijgen.
Herhaalde aanvragen en toeschrijving
Voor hetzelfde account, genormaliseerde doel, dezelfde campagne en hetzelfde label levert het aanmaken dezelfde link op via REST, MCP en batchverwerking. Een andere campagne of een ander label krijgt een aparte link. Zonder Idempotency-Key maakt het opnieuw versturen van een batch een nieuwe taak aan; linkhergebruik dedupliceert geen taken.
Nieuwe REST-links slaan createdVia: "api" op. Bij hergebruik behoudt een link de oorspronkelijke bron (api, mcp, share of redirect). Dit veld staat in MCP-resultaten van list_links en link, niet in het REST-antwoord voor aanmaken. Zie Verwijzingen voor toeschrijving en rapportage.
Idempotency-Key
Stuur optioneel Idempotency-Key bij POST /api/v1/links, POST /api/v1/uploads, POST /api/v1/sheets om een verzoek opnieuw te proberen zonder een extra taak aan te maken of nog een aanroep uit het linkquotum te verbruiken. Gebruik een unieke sleutel per bedoeld verzoek: 1 tot 255 afdrukbare ASCII-tekens.
Idempotency-Key: partner-batch-2026-10-23-001Gedurende 24 uur spelen hetzelfde account, dezelfde sleutel en hetzelfde gevalideerde verzoek de oorspronkelijke status, byte-identieke inhoud en headers opnieuw af, inclusief de oorspronkelijke request_id, met Idempotent-Replayed: true. De volgorde van JSON-objectsleutels maakt niet uit. Na 24 uur kun je de sleutel opnieuw gebruiken.
- Een andere inhoud of POST-route met dezelfde sleutel geeft
422(idempotency-key-reused); gebruik een nieuwe sleutel. - Zolang het eerste verzoek loopt, geven herhalingen
409(idempotency-key-in-progress) metRetry-After; wacht voordat je het opnieuw probeert. - Een ongeldige sleutel geeft
400(bad-idempotency-key). Ongeldige inhoud reserveert geen sleutel. - Zodra de uitvoering start, wordt het eerste antwoord opgeslagen, inclusief fouten. Een
429wordt niet opgeslagen: probeer dezelfde sleutel opnieuw naRetry-After.
Een gecrasht verzoek kan in uitvoering blijven staan tot de sleutel verloopt. Dit opnieuw afspelen van verzoeken staat los van het hierboven beschreven hergebruik van overeenkomende links.