Ninjabuy logosuBusiness
Satış ekibiyle iletişime geçin
Katalog API'si2026-11Önizleme

İçe aktarmalar

Bir ilan bağlantısı yapıştırın; varyantlarını ve her birinin satış maliyetini geri alın: ürün bedeli, satıcının bize gelen paketi için CN¥12,00 kabul ücretimiz, %14 sabit vergi, ardından kargo hattı, paket başına CN¥50,00 işlem ücreti ve bunların vergisi, pazaryeri komisyonu ve kâr marjınızı koruyan fiyat.
  • İçe aktarma ücretsizdir ve ürün sınırı yoktur. Yalnızca sipariş ettiğiniz için ödersiniz.
  • Her rakam tek adet içindir; kendi siparişinde satın alınıp kendi paketinde gönderilir: tek bir dropshipping satışı. Tek siparişte ya da tek pakette birden çok adet, burada görünenden daha ucuza gelir.
  • Pazaryeri komisyonları varsayılan olarak her pazaryerinin herkese açık genel oranıdır. Kategoriniz ya da planınız farklıysa kendi oranınızı gönderin.
Uç noktalar

Import nesnesi

Okuduğumuz hâliyle bir ilan ve tek bir satışın alıcınızın kapısına kadar maliyeti: ürün bedeli, satıcının bize gelen paketi için CN¥12,00 kabul ücretimiz, %14 sabit vergi, ardından kargo hattı, paket başına CN¥50,00 işlem ücreti ve bunların vergisi. US$ cinsinden, döviz çevirisi dahil bir US$ kartından çekilen tutardır.
idstring
imp_ ile başlar.
statusstring
running (bir ürün keşifleri tablosu hâlâ okunuyor), ready ya da failed.
urlstring
Gönderdiğiniz bağlantı.
marketplacestring
taobao, tmall, weidian ya da 1688.
title, seller, images[]string
Satıcının yazdığı şekliyle, çoğu zaman Çince.
read_atstring
İlanı pazaryerinden en son ne zaman okuduğumuz.
analysis.ship_to, lane, weight_g
Fiyatlandırıldığı girdiler.
analysis.coveredboolean
O hatta o ülkeye gönderim yapan yayımlanmış bir fiyat yoksa false; o zaman hiçbir varyantın teslim maliyeti olmaz.
analysis.marketplace_feeobject
percent ve fixed: pazaryerinin bir satıştan aldığı pay. Siz bir şey göndermediyseniz ve herkese açık genel oranını kullandıysak default true olur; bu bir tahmindir, asla gerçek faturanız değildir.
analysis.margin_reachableboolean
Komisyon ve kâr marjı birlikte fiyatın tamamını alıyorsa false: hiçbir fiyat buna ulaşamaz.
analysis.brand_hintobject|null
Başlıkta İngilizce ya da Çince marka veya replika kelimeleri bulundu. Bir ipucudur, asla karar değildir: fotoğraftaki logoyu göremez ve temiz bir sonuç hiçbir şey kanıtlamaz.
analysis.variants[].procurementobject
Tek adet satın alan siparişin goods, intake_fee, tax ve total değerleri.
analysis.variants[].seller_shippingobject|null
Satıcının depomuza kargosu. Hiçbir ilan bunu belirtmez, bu yüzden null'dır: ücretsiz değil, bilinmiyor.
analysis.variants[].parcelobject|null
Onu gönderen paketin lane, shipping, handling_fee, tax ve total değerleri.
analysis.variants[].landedobject
Ürün ve koli birlikte: CN¥ ve US$ olarak, dönüşüm ücreti US$ tutarına dahil.
analysis.variants[].minimum_priceobject|null
Pazaryeri komisyonundan sonra kâr marjınızı koruyan en düşük fiyat.
analysis.variants[].suggestedobject|null
Asgari fiyata eşit ya da üstündeki en düşük x.99 fiyat; bıraktığı komisyon, kâr ve kâr marjıyla.
productstring|null
Kaydedildikten sonra dönüştüğü ürün.
import
{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Bağlantıdan içe aktar

POST/v1/imports

Bir Taobao, Tmall, Weidian ya da 1688 ilanını okur (kısa bağlantı ya da başka bir alışveriş acentesinin ona verdiği bağlantı da olur) ve aynı çağrıda analiz edilmiş olarak döndürür. Son beş dakikada okuduğumuz bir ilan yeniden çekilmez.

Bir ürün keşifleri tablosu bağlantısı (https://www.ninjabuy.com/spreadsheets/d/…) içindeki her ürünü içe aktarır: status: running ile 202, ardından içe aktarmayı düzenli olarak sorgulayın.

Kapsamproducts:write

Gövde

urlstringzorunlu
Bir ürün bağlantısı ya da ürün keşifleri tablosu.
ship_tostring
Paketin fiyatlanacağı iki harfli ülke kodu. Belirtilmezse US.
lanestring
saver ya da fast. Belirtilmezse saver.
weight_gintegerzorunlu
Bir adedin paketli ağırlığı, gram cinsinden. İlanlar ağırlık belirtmez, bu yüzden paket sizin değerinizle fiyatlanır.
marketplacestring
Nerede satacağınız: ebay, shopify, amazon ya da tiktok. Belirtilmezse shopify.
marketplace_feeobject
İsteğe bağlı. Kategoriniz ya da planınız için pazaryerinin genel oranı yerine kullanılacak percent ve fixed (US$).
margin_percentstring
Satış fiyatı üzerinden hedeflenen kâr marjı. Belirtilmezse 30.

Hatalar

DurumTürNe zaman
400bad-bodyweight_g eksik ya da bir alan aralık dışında.
422unprocessableOkuyabileceğimiz bir bağlantı değil ya da ilan kaldırılmış.
429rate-limitedPazaryeri çağrı penceresi doldu; bkz. Hız sınırları.
curl -X POST "https://www.ninjabuy.com/api/v1/imports" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://weidian.com/item.html?itemID=7750970856",
    "ship_to": "US",
    "weight_g": 180,
    "marketplace": "ebay",
    "margin_percent": "30"
  }'
Response 201
HTTP/2 201 Created

{
  "id": "imp_2c9d",
  "status": "ready",
  "url": "https://weidian.com/item.html?itemID=7750970856",
  "marketplace": "weidian",
  "title": "Heavyweight washed hoodie",
  "seller": "Ruoyi Studio",
  "images": [
    "https://media.ninjabuy.com/listings/weidian-7750970856/1.webp"
  ],
  "read_at": "2026-11-04T09:12:40Z",
  "analysis": {
    "ship_to": "US",
    "lane": "saver",
    "weight_g": 180,
    "covered": true,
    "marketplace": "ebay",
    "marketplace_fee": {
      "percent": "13.6",
      "fixed": { "amount": "0.40", "currency": "USD" },
      "default": true
    },
    "margin_percent": "30",
    "margin_reachable": true,
    "brand_hint": null,
    "variants": [
      {
        "sku": "5187209554",
        "label": "Black / M",
        "in_stock": true,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      },
      {
        "sku": "5187209555",
        "label": "Black / L",
        "in_stock": false,
        "procurement": {
          "goods": { "amount": "38.00", "currency": "CNY" },
          "intake_fee": { "amount": "12.00", "currency": "CNY" },
          "tax": { "amount": "7.00", "currency": "CNY" },
          "total": { "amount": "57.00", "currency": "CNY" }
        },
        "seller_shipping": null,
        "parcel": {
          "lane": "saver",
          "shipping": { "amount": "68.00", "currency": "CNY" },
          "handling_fee": { "amount": "50.00", "currency": "CNY" },
          "tax": { "amount": "16.52", "currency": "CNY" },
          "total": { "amount": "134.52", "currency": "CNY" }
        },
        "landed": {
          "cny": { "amount": "191.52", "currency": "CNY" },
          "usd": { "amount": "27.71", "currency": "USD" },
          "fx_fee": { "amount": "5.75", "currency": "CNY" }
        },
        "minimum_price": { "amount": "49.84", "currency": "USD" },
        "suggested": {
          "price": { "amount": "49.99", "currency": "USD" },
          "marketplace_fee": { "amount": "7.20", "currency": "USD" },
          "profit": { "amount": "15.08", "currency": "USD" },
          "margin_percent": "30.16"
        }
      }
    ]
  },
  "product": null,
  "created_at": "2026-11-04T09:12:41Z"
}

Yeniden fiyatla

POST/v1/imports/{id}/analysis

Başka bir ülke, hat, ağırlık, pazaryeri ya da kâr marjı için aynı ilan. Zaten okuduklarımızdan fiyatlanır, bu yüzden pazaryeri çağrısı harcamaz. Yeni analizi döndürür ve içe aktarmada saklar.

Kapsamproducts:write

Yol parametreleri

idstringzorunlu
İçe aktarmanın id'si.

Gövde

ship_tostring
Paketin fiyatlanacağı iki harfli ülke kodu. Belirtilmezse US.
lanestring
saver ya da fast. Belirtilmezse saver.
weight_gintegerzorunlu
Bir adedin paketli ağırlığı, gram cinsinden. İlanlar ağırlık belirtmez, bu yüzden paket sizin değerinizle fiyatlanır.
marketplacestring
Nerede satacağınız: ebay, shopify, amazon ya da tiktok. Belirtilmezse shopify.
marketplace_feeobject
İsteğe bağlı. Kategoriniz ya da planınız için pazaryerinin genel oranı yerine kullanılacak percent ve fixed (US$).
margin_percentstring
Satış fiyatı üzerinden hedeflenen kâr marjı. Belirtilmezse 30.

Hatalar

DurumTürNe zaman
404not-foundBu hesapta böyle bir içe aktarma yok.
curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/analysis" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "ship_to": "GB",
    "lane": "fast",
    "weight_g": 180,
    "marketplace": "tiktok",
    "margin_percent": "35"
  }'
Response 200
HTTP/2 200 OK

{
  "ship_to": "GB",
  "lane": "fast",
  "weight_g": 180,
  "covered": true,
  "marketplace": "tiktok",
  "marketplace_fee": {
    "percent": "6",
    "fixed": { "amount": "0.00", "currency": "USD" },
    "default": true
  },
  "margin_percent": "35",
  "margin_reachable": true,
  "brand_hint": null,
  "variants": [
    {
      "sku": "5187209554",
      "label": "Black / M",
      "in_stock": true,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    },
    {
      "sku": "5187209555",
      "label": "Black / L",
      "in_stock": false,
      "procurement": {
        "goods": { "amount": "38.00", "currency": "CNY" },
        "intake_fee": { "amount": "12.00", "currency": "CNY" },
        "tax": { "amount": "7.00", "currency": "CNY" },
        "total": { "amount": "57.00", "currency": "CNY" }
      },
      "seller_shipping": null,
      "parcel": {
        "lane": "saver",
        "shipping": { "amount": "68.00", "currency": "CNY" },
        "handling_fee": { "amount": "50.00", "currency": "CNY" },
        "tax": { "amount": "16.52", "currency": "CNY" },
        "total": { "amount": "134.52", "currency": "CNY" }
      },
      "landed": {
        "cny": { "amount": "191.52", "currency": "CNY" },
        "usd": { "amount": "27.71", "currency": "USD" },
        "fx_fee": { "amount": "5.75", "currency": "CNY" }
      },
      "minimum_price": { "amount": "49.84", "currency": "USD" },
      "suggested": {
        "price": { "amount": "49.99", "currency": "USD" },
        "marketplace_fee": { "amount": "7.20", "currency": "USD" },
        "profit": { "amount": "15.08", "currency": "USD" },
        "margin_percent": "30.16"
      }
    }
  ]
}

İçe aktarmayı getir

GET/v1/imports/{id}

Bir içe aktarmayı yeniden okuyun ya da çalışırken bir ürün keşifleri tablosunu sorgulayın.

Kapsamproducts:read

Yol parametreleri

idstringzorunlu
İçe aktarmanın id'si.

Hatalar

DurumTürNe zaman
404not-foundBu hesapta böyle bir içe aktarma yok.
curl "https://www.ninjabuy.com/api/v1/imports/imp_6t1b" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "imp_6t1b",
  "status": "running",
  "url": "https://www.ninjabuy.com/spreadsheets/d/1aBcD3fGh",
  "progress": { "done": 41, "total": 120 },
  "poll_after_seconds": 10
}

İçe aktarmaları listele

GET/v1/imports

En yenisi önce. Hiç kaydetmediğiniz içe aktarmalar geri dönebilmeniz için burada kalır.

Kapsamproducts:read

Sorgu parametreleri

statusstring
İsteğe bağlı. running, ready ya da failed.
savedboolean
İsteğe bağlı. Ürüne dönüşenler için true.
limit, cursor
Pagination
curl "https://www.ninjabuy.com/api/v1/imports?saved=false&limit=2" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "imp_2c9d",
      "status": "ready",
      "title": "Heavyweight washed hoodie",
      "product": null
    },
    {
      "id": "imp_2c7a",
      "status": "ready",
      "title": "Canvas tote, 3 colours",
      "product": null
    }
  ],
  "has_more": true,
  "cursor": "c_2c7a"
}

Ürün olarak kaydet

POST/v1/imports/{id}/save

Seçtiğiniz varyantları, belirlediğiniz ya da önerilen fiyatlarla bir ürün olarak tutar. Aynı çağrıda mağazanızda listelemek için push_to: shopify ekleyin (Shopify'a gönder).

Kapsamproducts:write

Yol parametreleri

idstringzorunlu
İçe aktarmanın id'si.

Gövde

variants[]array
İsteğe bağlı. Tutulacak her varyantın sku ve price değerleri. Belirtilmezse stokta olan her varyant önerilen fiyatıyla.
titlestring
İsteğe bağlı. Kendi başlığınız; satıcınınki çoğu zaman Çincedir.
push_tostring
İsteğe bağlı. shopify.

Hatalar

DurumTürNe zaman
409invalid-stateZaten kaydedilmiş; product onu belirtir.
422unprocessableTuttuğunuz tüm varyantlar tükenmiş.
curl -X POST "https://www.ninjabuy.com/api/v1/imports/imp_2c9d/save" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heavyweight Washed Hoodie",
    "variants": [
      {
        "sku": "5187209554",
        "price": { "amount": "49.99", "currency": "USD" }
      }
    ],
    "push_to": "shopify"
  }'
Response 201
HTTP/2 201 Created

{
  "import": "imp_2c9d",
  "product": "prd_8f2k",
  "status": "draft",
  "channels": [{ "channel": "shopify", "status": "draft" }]
}