เอกสารอ้างอิง API สินค้า (v2)

สรุป

หน้านี้ระบุ endpoints, พารามิเตอร์ และโครงสร้าง response ของ API สินค้า v2 (เวอร์ชันปัจจุบัน แนะนำสำหรับการผสานรวมใหม่): ค้นหาด้วยคำสำคัญ ค้นหาด้วยรูปภาพ ดึงรายละเอียดสินค้า อัปโหลดรูปภาพ และคำนวณค่าจัดส่งบน Taobao และ 1688

หากคุณใช้เวอร์ชัน v1 อยู่ ดู API สินค้า v1 (Legacy) หากต้องการทำตามทีละขั้นตอน ดู คู่มือการค้นหาสินค้า

ทุก endpoint เป็น POST ต้องมี header การยืนยันตัวตน (JWT หรือคีย์ API) และต้องมีพารามิเตอร์ platform ด้วยค่า taobao หรือ alibaba

Endpoint	คำอธิบาย	Platform
`POST /v2/products/search`	ค้นหาสินค้าด้วยคำสำคัญ	✅ Taobao ✅ 1688
`POST /v2/products/search-by-image`	ค้นหาสินค้าด้วยรูปภาพ	✅ Taobao ✅ 1688
`POST /v2/products/find`	ดึงรายละเอียดสินค้า	✅ Taobao ✅ 1688
`POST /v2/products/detail`	ดึงรายละเอียดสินค้าแบบเต็ม	✅ Taobao ✅ 1688
`POST /v2/products/upload-image`	อัปโหลดรูปภาพไปยังเซิร์ฟเวอร์ Alibaba	✅ Taobao ✅ 1688
`POST /v2/products/shipping-fee`	คำนวณค่าจัดส่ง	✅ Taobao ❌ 1688

ค้นหาสินค้าด้วยคำสำคัญ

POST /v2/products/search

ตัวอย่างคำขอ:

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "lang": "vi",
  "sort": "SALE_QTY_DESC",
  "page": 1,
  "size": 20,
  "filter": {
    "priceRange": { "min": 0, "max": 100 }
  }
}

พารามิเตอร์

พารามิเตอร์	ชนิด	บังคับ	คำอธิบาย
`platform`	string	✅	แพลตฟอร์ม: `taobao` หรือ `alibaba`
`q`	string	❌	คำสำคัญค้นหา
`lang`	string	❌	ภาษาแปลชื่อสินค้า: `vi`, `en`, `ru`, `ko`, `ja`. ข้อมูลที่แปลอยู่ใน key `title_en`; key `title` ยังเป็นภาษาจีนต้นฉบับ
`sort`	string	❌	เรียงลำดับผลลัพธ์ (ดูตารางด้านล่าง)
`filter`	object	❌	ตัวกรองผลลัพธ์ (ดูตารางด้านล่าง)
`page`	number	❌	เลขหน้า เริ่มจาก 1
`size`	number	❌	จำนวนผลลัพธ์ต่อหน้า: ตั้งแต่ 20 ถึง 40
`keywordTranslate`	boolean	❌	แปลคำสำคัญค้นหาเป็นภาษาที่ตรงกับ `lang`

เรียงลำดับผลลัพธ์ (`sort`)

ค่า	คำอธิบาย	Platform
`PRICE_ASC`	ราคาจากน้อยไปมาก	✅ Taobao ✅ 1688
`PRICE_DESC`	ราคาจากมากไปน้อย	✅ Taobao ✅ 1688
`SALE_QTY_ASC`	ยอดขายจากน้อยไปมาก	✅ Taobao ✅ 1688
`SALE_QTY_DESC`	ยอดขายจากมากไปน้อย	✅ Taobao ✅ 1688
`RETENTION_ASC`	อัตราซื้อซ้ำจากน้อยไปมาก	❌ Taobao ✅ 1688
`RETENTION_DESC`	อัตราซื้อซ้ำจากมากไปน้อย	❌ Taobao ✅ 1688

กรองผลลัพธ์ (`filter`)

พารามิเตอร์	คำอธิบาย	Platform
`filter.priceRange`	ช่วงราคา หน่วย CNY: `{ "min": 0, "max": 100 }`	✅ Taobao ✅ 1688
`filter.shopId`	สินค้าจากผู้ขายเดียวกัน Taobao ใช้ shop id ตัวเลข; 1688 ใช้ shopId ตัวอักษร-ตัวเลข	✅ Taobao ✅ 1688
`filter.sellerLevel`	ระดับผู้ขาย: `L1` – `L4` (ดูตารางด้านล่าง)	❌ Taobao ✅ 1688
`filter.isFactory`	รับเฉพาะสินค้าจากโรงงานซูเปอร์	❌ Taobao ✅ 1688
`filter.ffmOutbound`	เกณฑ์จัดส่งเร็ว: `FFMO1` – `FFMO6` (ดูตารางด้านล่าง)	❌ Taobao ✅ 1688
`filter.ffmDelivery`	เกณฑ์จัดส่งรวดเร็ว: `FFMD0` – `FFMD2` (ดูตารางด้านล่าง)	❌ Taobao ✅ 1688
`filter.allowReturn`	อนุญาตคืนสินค้าโดยไม่ต้องระบุเหตุผลภายใน 7 วัน	❌ Taobao ✅ 1688
`filter.allowDropship`	อนุญาตดรอปชิปปิ้ง	❌ Taobao ✅ 1688
`filter.freeshipForDropship`	อนุญาตดรอปชิปปิ้ง + ค่าจัดส่งฟรี	❌ Taobao ✅ 1688
`filter.newArrival`	สินค้าใหม่อัปเดตบนแพลตฟอร์ม: `7DAY`, `30DAY`	❌ Taobao ✅ 1688
`filter.platformPick`	แหล่งสินค้าที่แพลตฟอร์มคัดเลือกสำหรับตลาดในประเทศ	❌ Taobao ✅ 1688
`filter.globalPick`	แหล่งสินค้าที่แพลตฟอร์มคัดเลือกสำหรับตลาดต่างประเทศ	❌ Taobao ✅ 1688
`filter.dropshipPick`	แหล่งสินค้าที่แพลตฟอร์มคัดเลือกสำหรับดรอปชิปปิ้ง	❌ Taobao ✅ 1688
`filter.categoryId`	กรองตามรหัสหมวดหมู่	❌ Taobao ✅ 1688
`filter.categoryIdList`	กรองตามรายการรหัสหมวดหมู่	❌ Taobao ✅ 1688
`filter.sellerOpenId`	ค้นหาภายในร้านเดียว (เมื่อมีพารามิเตอร์นี้ `q` คือคำสำคัญที่ค้นภายในร้าน)	❌ Taobao ✅ 1688

ค่า `ffmOutbound`

ค่า	คำอธิบาย
`FFMO1`	อัตราการจัดส่งภายใน 24 ชม. < 95%
`FFMO2`	อัตราการจัดส่งภายใน 24 ชม. >= 95%
`FFMO3`	อัตราการจัดส่งภายใน 24 ชม. > 99%
`FFMO4`	อัตราการจัดส่งภายใน 48 ชม. < 95%
`FFMO5`	อัตราการจัดส่งภายใน 48 ชม. >= 95%
`FFMO6`	อัตราการจัดส่งภายใน 48 ชม. > 99%

ค่า `ffmDelivery`

ค่า	คำอธิบาย
`FFMD0`	จัดส่งภายในวันเดียว
`FFMD1`	จัดส่งภายใน 24 ชม.
`FFMD2`	จัดส่งภายใน 48 ชม.

ค่า `newArrival`

ค่า	คำอธิบาย
`7DAY`	สินค้าใหม่อัปเดตภายใน 7 วันล่าสุด
`30DAY`	สินค้าใหม่อัปเดตภายใน 30 วันล่าสุด

ค่า `sellerLevel`

ค่า	คำอธิบาย
`L1`	คะแนนรีวิวรวม 5 ดาว
`L2`	คะแนนรีวิวรวม 4.5 – 5 ดาว
`L3`	คะแนนรีวิวรวม 4 – 4.5 ดาว
`L4`	คะแนนรีวิวรวมต่ำกว่า 4 ดาว

ค้นหาสินค้าด้วยรูปภาพ

หมายเหตุ: ฟังก์ชันนี้ไม่ใช้กับแพ็กเกจ ฟรี

POST /v2/products/search-by-image

มี 2 วิธีค้นหาด้วยรูปภาพ ต้องส่งพารามิเตอร์อย่างน้อย 1 ใน 2:

1. ค้นหาด้วย URL รูปภาพ — ใช้พารามิเตอร์ imgUrl

ใช้ได้เฉพาะลิงก์รูปภาพจาก Alibaba: *.alicdn.com

{
  "platform": "taobao",
  "imgUrl": "https://img.alicdn.com/bao/uploaded/i3/694223667/O1CN01zSjKgp1cxXRQZsDLA_!!694223667.jpg",
  "lang": "vi",
  "page": 1,
  "size": 20
}

2. ค้นหาด้วยรูปภาพที่อัปโหลด — ใช้พารามิเตอร์ imgId

อัปโหลดรูปภาพก่อนผ่าน API POST /v2/products/upload-image เพื่อรับ imageId จากนั้นส่งเข้า imgId:

{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi",
  "page": 1,
  "size": 20
}

พารามิเตอร์

พารามิเตอร์	ชนิด	บังคับ	คำอธิบาย
`platform`	string	✅	แพลตฟอร์ม: `taobao` หรือ `alibaba`
`imgUrl`	string	❌*	ลิงก์รูปภาพ Alibaba (`*.alicdn.com`)
`imgId`	string	❌*	รหัสรูปภาพที่อัปโหลดผ่าน `POST /v2/products/upload-image`
`lang`	string	❌	ภาษาแปลชื่อสินค้า: `vi`, `en`, `ru`, `ko`, `ja`
`sort`	string	❌	เรียงลำดับผลลัพธ์ (ค่าเดียวกับ `sort` ในส่วนค้นหาด้วยคำสำคัญ)
`filter`	object	❌	ตัวกรอง: รองรับ `filter.priceRange` และ `filter.categoryId`
`page`	number	❌	เลขหน้า เริ่มจาก 1
`size`	number	❌	จำนวนผลลัพธ์ต่อหน้า: ตั้งแต่ 1 ถึง 20
`keyword`	string	❌	คำสำคัญเพิ่มเติมเมื่อค้นหาด้วยรูปภาพ
`keywordTranslate`	boolean	❌	แปลคำสำคัญค้นหา

* ต้องส่งอย่างน้อยหนึ่งในสองพารามิเตอร์ imgUrl หรือ imgId

ดึงข้อมูลรายละเอียดสินค้า

POST /v2/products/find
POST /v2/products/detail

ทั้งสอง endpoint ใช้โครงสร้างคำขอเดียวกันและส่งคืนรายละเอียดสินค้า detail ส่งคืนรายละเอียดที่ครบถ้วนกว่า เหมาะเมื่อต้องการข้อมูล 1688

{
  "platform": "taobao",
  "id": "734467086498",
  "lang": "vi"
}

พารามิเตอร์

พารามิเตอร์	ชนิด	บังคับ	คำอธิบาย
`platform`	string	✅	แพลตฟอร์ม: `taobao` หรือ `alibaba`
`id`	string	❌	รหัสสินค้า: Taobao ใช้ `mi_id` หรือ `item_url`; 1688 ใช้ `offerId`
`lang`	string	❌	ภาษาแปลชื่อสินค้า: `vi`, `en`, `ru`, `ko`, `ja`

หากเจอลิงก์ย่อรูปแบบ https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd ต้องแปลงลิงก์ก่อนเพื่อให้ได้ลิงก์ต้นฉบับ — ใช้ API Unshorten link เพื่อรับลิงก์ต้นฉบับและ ID สินค้า

ประเภทราคาสินค้า

ฟิลด์ราคา	คำอธิบาย	Platform
`price`	ราคาปกติ สำหรับ 1688 คือราคาส่งแบบไม่ฟรีค่าจัดส่ง จำนวนขึ้นอยู่กับการตั้งค่าของผู้ขาย	✅ Taobao ✅ 1688
`promotion_price`	ราคาโปรโมชัน ต่ำกว่าหรือเท่ากับราคาปกติ	✅ Taobao ✅ 1688
`retail_price`	ราคาขายปลีก + ค่าจัดส่งฟรีตั้งแต่ 1 ชิ้น สำหรับดรอปชิปปิ้ง มักปรากฏในสินค้า 1688 ที่คัดเลือก	❌ Taobao ✅ 1688
`dropship_price`	ราคาขายปลีกต่อชิ้น มักเท่ากับราคาปกติ ต่างกันตรงที่ขึ้นอยู่กับว่าผู้ขายเปิดใช้ดรอปชิปหรือไม่	❌ Taobao ✅ 1688

คำเตือน: หากคุณแสดงราคาให้ลูกค้าดูบนส่วนขยาย/เว็บ/แอป โปรดเพิ่มคำเตือนว่าราคาอาจสูงกว่าราคาที่เห็นโดยตรงบน Taobao/1688 หากพบว่าราคาบน API สูงกว่า โปรดติดต่อฝ่ายบริการลูกค้าเพื่อขอปรับราคาเมื่อสร้างคำสั่งซื้อ

Taobao: ให้ความสำคัญกับการแสดงและใช้ราคาโปรโมชัน; หากไม่มีให้ใช้ราคาปกติ

1688: ตรรกะการใช้ราคาขึ้นอยู่กับฟิลด์ quote_type:

ค่า	คำอธิบาย
`direct`	ใช้ราคาส่งตาม `price` และ `promotion_price`
`by_sku`	ใช้ราคาตาม SKU แต่ละรายการ
`by_volume`	ใช้ราคาตาม `price_range` และขึ้นอยู่กับจำนวนซื้อขั้นต่ำ `moq`

ระดับผู้ขายบน 1688

ระดับใช้เพื่อกำหนดความน่าเชื่อถือของผู้ขายบน 1688 ระบุผ่านฟิลด์ seller_type:

ค่า	คำอธิบาย
`seller`	ผู้ขายทั่วไป
`merchant`	ผู้ขายมืออาชีพที่ผ่านการยืนยันตัวตนจาก 1688
`factory`	โรงงานผลิตที่ผ่านการยืนยันตัวตนจาก 1688 และผ่านเกณฑ์การประเมินโดยตรงจาก 1688

คำอธิบายฟิลด์ใน `extra_info`

ค่า	คำอธิบาย
`isOnePsale`	รองรับดรอปชิปปิ้งหรือไม่?
`isSupportMix`	อนุญาตซื้อหลายสินค้าในคำสั่งซื้อเดียวหรือไม่?
`isOnePsaleFreePostage`	รองรับดรอปชิปปิ้ง + ค่าจัดส่งฟรีหรือไม่?
`noReason7DReturn`	อนุญาตคืนสินค้าโดยไม่ต้องระบุเหตุผลภายใน 7 วันหรือไม่?
`1688_yx`	เป็นแหล่งสินค้าที่คัดเลือกหรือไม่?

คำนวณค่าจัดส่ง

ใช้เฉพาะ Taobao

POST /v2/products/shipping-fee

{
  "platform": "taobao",
  "id": "734467086498",
  "addressInfo": {
    "country": "VN",
    "state": "Hà Nội",
    "city": "Hà Nội",
    "district": "Hoàn Kiếm"
  }
}

พารามิเตอร์

พารามิเตอร์	ชนิด	บังคับ	คำอธิบาย
`platform`	string	✅	กำหนดค่าเป็น `taobao`
`id`	string	❌	รหัสสินค้า: `mi_id` หรือ `item_url`
`addressInfo.country`	string	✅	ประเทศผู้รับ
`addressInfo.state`	string	✅	จังหวัด/เมืองใหญ่
`addressInfo.city`	string	✅	เมือง/เขต
`addressInfo.district`	string	❌	อำเภอ/เขต

Response ประกอบด้วย post_fee (ค่าจัดส่ง หน่วย CNY), currency, item_id, mi_id, item_resource

อัปโหลดรูปภาพ

ใช้เพื่อรับ imageId สำหรับค้นหาด้วยรูปภาพ (พารามิเตอร์ imgId)

POST /v2/products/upload-image

คำขอรูปแบบ multipart/form-data:

ฟิลด์	ชนิด	บังคับ	คำอธิบาย
`file`	file	✅	ไฟล์รูปภาพที่ต้องการอัปโหลด
`platform`	string	✅	แพลตฟอร์ม: `taobao` หรือ `alibaba`

Response: { "imageId": "image-123" }

โครงสร้าง response

ชื่อ field ใน response ใช้รูปแบบ snake_case แต่ละแพลตฟอร์มส่งคืนโครงสร้างสินค้าที่ต่างกัน:

find / detail → ออบเจกต์สินค้าหนึ่งรายการ (Product)
search / search-by-image → { "paginate": { "total", "current", "size" }, "items": [...] } (ส่วน paginate อาจไม่มีเมื่อไม่มีข้อมูลแบ่งหน้า)

ฟิลด์ร่วม (มีทั้งสองแพลตฟอร์ม)

Field	คำอธิบาย
`id`	รหัสสินค้า
`title`	ชื่อต้นฉบับ (ภาษาจีน)
`title_en`	ชื่อที่แปลแล้ว (เมื่อเรียกด้วย `lang`)
`description`	คำอธิบายสินค้า
`quote_type`	ประเภทการให้ราคา: `direct` / `by_sku` / `by_volume`
`price`	ราคาปกติ
`promotion_price`	ราคาโปรโมชัน
`quantity`	สต็อก
`unit`	หน่วยนับ
`shop_id`	รหัสผู้ขาย
`shop_name`	ชื่อร้านค้า
`moq`	จำนวนซื้อขั้นต่ำ
`category_id`	รหัสหมวดหมู่
`category_name`	ชื่อหมวดหมู่
`category_path`	เส้นทางหมวดหมู่
`img_urls`	รายการรูปภาพสินค้า
`seller_type`	ประเภทผู้ขาย: `seller` / `merchant` / `factory`
`status`	สถานะสินค้า
`skus`	รายการตัวเลือก (สี, ไซซ์)
`attributes`	คุณสมบัติสินค้า

ฟิลด์เฉพาะของ 1688

นอกเหนือจากฟิลด์ร่วม response ของ 1688 เพิ่มฟิลด์ต่อไปนี้ (จัดกลุ่มตามหัวข้อ):

ราคา: price_range, channel_price, promotion_model, fenxiao_sale_info, is_jxhy
สื่อ: video_urls, white_image, translated_img_urls, translated_white_image
การแปลภาษา: description_en, unit_en
ยอดขาย / รีวิว: sold, review, level
การจัดส่ง: shipping_info
หมวดหมู่: top_category_id, second_category_id, third_category_id
ตัวระบุและลิงก์: mp_id, item_type, batch_number, product_cargo_number, original_product_url, seller_shop_url, promotion_url
Metadata: selling_point, offer_identities, create_date, is_select, certificate_list, seller_mix_setting
อื่นๆ: extra_info, sku_price_ranges

หมายเหตุ: ฟิลด์ที่หายไปโดยสิ้นเชิงใน response หมายถึงฟิลด์นั้นไม่ใช่ของแพลตฟอร์มที่คุณกำลังเรียก ฟิลด์ที่มีค่า null หมายถึงไม่มีข้อมูลสำหรับฟิลด์นั้นในคำขอนี้

รายการฟิลด์ทั้งหมดและคำอธิบายโดยละเอียด: Swagger API

คำถามที่พบบ่อย (FAQ)

ทำไมราคาสินค้าที่ได้จาก API ต่างจากราคาที่เห็นบนเว็บไซต์ Taobao/1688?

API ที่เราใช้เป็นของระบบโลจิสติกส์ข้ามพรมแดนของ Alibaba ราคาถูกกำหนดอย่างอิสระ — แยกต่างหากจากราคาที่แสดงบนเว็บไซต์
ต่างจาก API เว็บไซต์สามารถแยกแยะลูกค้าใหม่และลูกค้าเก่าได้ จึงสามารถใช้โปรโมชันหรือคูปองตามกลุ่มผู้ใช้ — ความสามารถที่ API ไม่รองรับ

มีสภาพแวดล้อมทดสอบหรือไม่?

ไม่มี บัญชีค่าเริ่มต้นถูกเพิ่ม คำขอฟรี 200 ครั้ง เพื่อการผสานรวมทดสอบ

ข้อมูลเป็นแบบเรียลไทม์หรือไม่?

ใช่ ข้อมูลถูกดึงโดยตรงจาก Taobao และ 1688

รองรับการค้นหาด้วยรูปภาพหรือไม่?

ใช่ รองรับการค้นหาด้วย ลิงก์รูปภาพ และ รูปภาพที่อัปโหลด

ลิงก์ที่เกี่ยวข้อง

ปฏิบัติตาม: คู่มือการค้นหาสินค้า
Legacy: API สินค้า v1 (Legacy)
เครื่องมือ: Elim CLI — ค้นหาสินค้าจากเทอร์มินัล
เอกสารอ้างอิง API ฉบับเต็ม: openapi.elim.asia/api

เอกสารอ้างอิง API สินค้า (v2)

สรุป

ค้นหาสินค้าด้วยคำสำคัญ

พารามิเตอร์

เรียงลำดับผลลัพธ์ (sort)

กรองผลลัพธ์ (filter)

ค่า ffmOutbound

ค่า ffmDelivery

ค่า newArrival

ค่า sellerLevel

ค้นหาสินค้าด้วยรูปภาพ

พารามิเตอร์

ดึงข้อมูลรายละเอียดสินค้า

พารามิเตอร์

ประเภทราคาสินค้า

ระดับผู้ขายบน 1688

คำอธิบายฟิลด์ใน extra_info

คำนวณค่าจัดส่ง

พารามิเตอร์

อัปโหลดรูปภาพ

โครงสร้าง response

ฟิลด์ร่วม (มีทั้งสองแพลตฟอร์ม)

ฟิลด์เฉพาะของ 1688

คำถามที่พบบ่อย (FAQ)

ทำไมราคาสินค้าที่ได้จาก API ต่างจากราคาที่เห็นบนเว็บไซต์ Taobao/1688?

มีสภาพแวดล้อมทดสอบหรือไม่?

ข้อมูลเป็นแบบเรียลไทม์หรือไม่?

รองรับการค้นหาด้วยรูปภาพหรือไม่?

ลิงก์ที่เกี่ยวข้อง

เรียงลำดับผลลัพธ์ (`sort`)

กรองผลลัพธ์ (`filter`)

ค่า `ffmOutbound`

ค่า `ffmDelivery`

ค่า `newArrival`

ค่า `sellerLevel`

คำอธิบายฟิลด์ใน `extra_info`