Ninjabuy 로고Business
영업팀에 문의
카탈로그 API2026-11프리뷰

가져오기

상품 링크를 붙여넣으면 옵션과 각 옵션을 판매하는 데 드는 비용이 나와요: 상품 대금, 판매자가 저희에게 보내는 택배의 입고 수수료 CN¥12.00, 일괄 14% 세금, 그다음 배송 노선, 택배당 취급 수수료 CN¥50.00, 그리고 이에 대한 세금, 마켓플레이스 수수료, 그리고 마진을 지키는 가격.
  • 가져오기는 무료이며 상품 수 제한도 없어요. 주문한 것에만 비용을 내요.
  • 모든 수치는 1개 기준이에요. 단독 주문으로 구매해 단독 택배로 배송한, 드롭쉬핑 판매 1건이에요. 한 주문이나 한 택배에 여러 개가 있으면 이보다 저렴해요.
  • 마켓플레이스 수수료의 기본값은 각 마켓플레이스의 공개 기본 요율이에요. 카테고리나 요금제가 다르면 내 값을 보내세요.
엔드포인트

Import 객체

저희가 읽은 상품 정보와, 판매 1건이 구매자 문 앞까지 도착하는 데 드는 비용: 상품 대금, 판매자가 저희에게 보내는 택배의 입고 수수료 CN¥12.00, 일괄 14% 세금, 그다음 배송 노선, 택배당 취급 수수료 CN¥50.00, 그리고 이에 대한 세금. US$ 금액은 US$ 카드에 청구되는 금액이며 환전 수수료가 포함돼요.
idstring
imp_로 시작해요.
statusstring
running(추천 상품 시트를 아직 읽는 중), ready 또는 failed.
urlstring
보낸 링크.
marketplacestring
taobao, tmall, weidian 또는 1688.
title, seller, images[]string
판매자가 쓴 그대로, 대부분 중국어로.
read_atstring
마켓플레이스에서 상품을 마지막으로 읽은 시각.
analysis.ship_to, lane, weight_g
가격 계산에 쓴 입력값.
analysis.coveredboolean
해당 노선으로 그 국가에 배송하는 공개 요금이 없으면 false. 이 경우 어떤 옵션에도 총비용이 없어요.
analysis.marketplace_feeobject
percent와 fixed: 마켓플레이스가 판매에서 가져가는 몫. 아무것도 보내지 않아 저희가 공개 기본 요율을 쓴 경우 default가 true이며, 견적일 뿐 실제 청구액은 아니에요.
analysis.margin_reachableboolean
수수료와 마진을 합치면 가격 전체가 되면 false. 어떤 가격으로도 도달할 수 없어요.
analysis.brand_hintobject|null
상품명에서 영어나 중국어로 된 브랜드 또는 레플리카 관련 단어가 발견되었어요. 참고용일 뿐 판정이 아니에요. 사진 속 로고는 볼 수 없고, 깨끗한 결과도 아무것도 보증하지 않아요.
analysis.variants[].procurementobject
1개를 구매하는 주문의 goods, intake_fee, tax, total.
analysis.variants[].seller_shippingobject|null
판매자가 저희 창고로 보내는 배송비. 어떤 상품 페이지에도 없으므로 null이며, 무료가 아니라 알 수 없음이에요.
analysis.variants[].parcelobject|null
그 상품을 배송하는 택배의 lane, shipping, handling_fee, tax, total.
analysis.variants[].landedobject
상품과 소포 합계: CN¥와 US$로 표시하며, US$에는 환전 수수료가 포함됩니다.
analysis.variants[].minimum_priceobject|null
마켓플레이스 수수료를 뺀 뒤에도 마진을 지키는 최저 가격.
analysis.variants[].suggestedobject|null
최저 가격 이상인 가장 낮은 x.99 가격과, 그에 따른 수수료, 이익, 마진.
productstring|null
저장 후 만들어진 상품.
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"
}

링크로 가져오기

POST/v1/imports

Taobao, Tmall, Weidian, 1688 상품(단축 링크나 다른 구매 대행 서비스의 링크도 가능)을 읽고 같은 호출에서 분석 결과를 반환해요. 최근 5분 이내에 읽은 상품은 다시 가져오지 않아요.

추천 상품 시트 링크(https://www.ninjabuy.com/spreadsheets/d/…)는 시트의 모든 상품을 가져와요: 202와 status: running이 반환되면 가져오기를 폴링하세요.

범위products:write

본문

urlstring필수
상품 링크 또는 추천 상품 시트.
ship_tostring
택배 가격을 계산할 두 글자 국가. 생략하면 US.
lanestring
saver 또는 fast. 생략하면 saver.
weight_ginteger필수
1개의 포장 후 무게(그램). 상품 페이지에는 무게가 없으므로 택배는 내 값으로 계산돼요.
marketplacestring
판매처: ebay, shopify, amazon 또는 tiktok. 생략하면 shopify.
marketplace_feeobject
선택 사항. 카테고리나 요금제에 맞춰 마켓플레이스 기본 요율 대신 쓸 percent와 fixed(US$).
margin_percentstring
판매 가격 대비 목표 마진. 생략하면 30.

오류

상태유형시점
400bad-bodyweight_g가 없거나 필드가 범위를 벗어났어요.
422unprocessable읽을 수 없는 링크이거나 상품이 삭제되었어요.
429rate-limited마켓플레이스 한도를 다 썼어요. 요청 한도를 참고하세요.
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"
}

다시 계산

POST/v1/imports/{id}/analysis

같은 상품을 다른 국가, 노선, 무게, 마켓플레이스, 마진으로. 이미 읽은 정보로 계산하므로 마켓플레이스 호출을 쓰지 않아요. 새 분석을 반환하고 가져오기에 저장해요.

범위products:write

경로 매개변수

idstring필수
가져오기 ID.

본문

ship_tostring
택배 가격을 계산할 두 글자 국가. 생략하면 US.
lanestring
saver 또는 fast. 생략하면 saver.
weight_ginteger필수
1개의 포장 후 무게(그램). 상품 페이지에는 무게가 없으므로 택배는 내 값으로 계산돼요.
marketplacestring
판매처: ebay, shopify, amazon 또는 tiktok. 생략하면 shopify.
marketplace_feeobject
선택 사항. 카테고리나 요금제에 맞춰 마켓플레이스 기본 요율 대신 쓸 percent와 fixed(US$).
margin_percentstring
판매 가격 대비 목표 마진. 생략하면 30.

오류

상태유형시점
404not-found이 계정에 해당 가져오기가 없어요.
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"
      }
    }
  ]
}

가져오기 조회

GET/v1/imports/{id}

가져오기를 다시 읽거나, 실행 중인 추천 상품 시트를 폴링해요.

범위products:read

경로 매개변수

idstring필수
가져오기 ID.

오류

상태유형시점
404not-found이 계정에 해당 가져오기가 없어요.
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
}

가져오기 목록

GET/v1/imports

최신순. 저장하지 않은 가져오기도 나중에 다시 볼 수 있게 여기 남아요.

범위products:read

쿼리 매개변수

statusstring
선택 사항. running, ready 또는 failed.
savedboolean
선택 사항. 상품이 된 것은 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"
}

상품으로 저장

POST/v1/imports/{id}/save

고른 옵션을 내가 정한 가격이나 추천 가격으로 상품으로 저장해요. push_to: shopify를 추가하면 같은 호출로 스토어에 등록돼요(Shopify로 보내기).

범위products:write

경로 매개변수

idstring필수
가져오기 ID.

본문

variants[]array
선택 사항. 남길 각 옵션의 sku와 price. 생략하면 재고 있는 모든 옵션을 추천 가격으로.
titlestring
선택 사항. 내 상품명. 판매자 상품명은 대부분 중국어예요.
push_tostring
선택 사항. shopify.

오류

상태유형시점
409invalid-state이미 저장됨. product가 해당 상품을 가리켜요.
422unprocessable남겨 둔 모든 옵션이 품절이에요.
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" }]
}