บทนำ
KabyTech Delivery Order (D/O) Intelligence API ช่วยให้คุณแยกวิเคราะห์เอกสารใบสั่งปล่อยสินค้า (PDF, รูปภาพ หรือสำเนาสแกน) และรับข้อมูล JSON ที่มีโครงสร้างพร้อมฟิลด์ที่สกัดได้มากกว่า 25 รายการ API นี้ออกแบบมาสำหรับการดำเนินงานท่าเรือและท่าเทียบเรือในประเทศไทย รองรับการอนุมัติปล่อยสินค้าที่ท่าเรือแหลมฉบัง (THLCH) ท่าเรือกรุงเทพ (THBKK) และมาบตาพุด (THMTP)
ใบสั่งปล่อยสินค้า (Delivery Order) ใช้สำหรับอนุมัติการปล่อยสินค้าจากท่าเทียบเรือไปยังผู้รับสินค้าหรือตัวแทน API จะจับคู่ D/O แต่ละฉบับกับเลขอ้างอิง AWB หรือ B/L ต้นทางโดยอัตโนมัติ ตรวจสอบหมายเลขตู้คอนเทนเนอร์ตามมาตรฐาน ISO 6346 และติดตามสถานะการอนุมัติปล่อยสินค้าแบบเรียลไทม์
คำขอ API ทั้งหมดส่งผ่าน HTTPS การตอบกลับอยู่ในรูปแบบ JSON โดย API เป็นไปตามมาตรฐาน RESTful และใช้รหัสสถานะ HTTP มาตรฐาน
URL พื้นฐาน
endpoint ทั้งหมดที่อธิบายในเอกสารนี้เป็นแบบสัมพัทธ์กับ URL พื้นฐานนี้ ตัวอย่างเช่น endpoint สำหรับแยกวิเคราะห์สามารถเข้าถึงได้ที่ https://api.kabytech.co.th/v1/do/parse.
การยืนยันตัวตน
คำขอ API ทั้งหมดต้องมีการยืนยันตัวตนผ่าน API key โปรดใส่ API key ของคุณในส่วนหัว X-API-Key ทุกครั้งที่ส่งคำขอ คุณสามารถรับ API key ได้จาก KabyTech Dashboard หลังจากสร้างบัญชีแล้ว
API key จะมีคำนำหน้า kby_live_ สำหรับ production และ kby_test_ สำหรับ sandbox คีย์ทดสอบจะประมวลผลเอกสารแต่ส่งคืนข้อมูลจำลอง — สามารถใช้งานได้ฟรีระหว่างการพัฒนา
| ส่วนหัว | ค่า | จำเป็น |
|---|---|---|
X-API-Key | API key ของคุณ (kby_live_... หรือ kby_test_...) | จำเป็น |
Content-Type | application/json หรือ multipart/form-data | จำเป็น |
Accept | application/json | ไม่บังคับ |
เริ่มต้นอย่างรวดเร็ว
เริ่มแยกวิเคราะห์ใบสั่งปล่อยสินค้าฉบับแรกของคุณได้ภายใน 5 นาที ตัวอย่างนี้ใช้ Python SDK เพื่ออัปโหลด D/O ที่สแกนแล้วและรับข้อมูลการอนุมัติปล่อยสินค้าที่มีโครงสร้าง
POST /v1/do/parse
แยกวิเคราะห์เอกสารใบสั่งปล่อยสินค้าฉบับเดียวและส่งคืนข้อมูลที่มีโครงสร้าง รองรับไฟล์ PDF, PNG, JPG, TIFF หรือสำเนาสแกน ส่งคืนฟิลด์มากกว่า 25 รายการ รวมถึงสถานะการอนุมัติปล่อย การตรวจสอบตู้คอนเทนเนอร์ และการจับคู่เลขอ้างอิงกับ AWB หรือ B/L ต้นทาง
แยกวิเคราะห์เอกสารใบสั่งปล่อยสินค้าและสกัดฟิลด์ที่มีโครงสร้างทั้งหมด หมายเลขตู้คอนเทนเนอร์จะถูกตรวจสอบตามมาตรฐาน ISO 6346 (การตรวจสอบเลขตรวจ) D/O จะถูกจับคู่กับเลขอ้างอิง AWB หรือ B/L ต้นทางโดยอัตโนมัติเมื่อมีข้อมูล ระยะเวลาประมวลผลเฉลี่ย 1.0–1.5 วินาทีต่อเอกสาร
เนื้อหาคำขอ (JSON)
| พารามิเตอร์ | ประเภท | คำอธิบาย |
|---|---|---|
document Required | string | เนื้อหาเอกสารที่เข้ารหัส Base64 (PDF, PNG, JPG, TIFF) |
format Required | string | รูปแบบเอกสาร: pdf, png, jpg, tiff |
include_confidence Optional | boolean | รวมคะแนนความเชื่อมั่นรายฟิลด์ (ค่าเริ่มต้น: true) |
validate_iso6346 Optional | boolean | ตรวจสอบหมายเลขตู้คอนเทนเนอร์ตามเลขตรวจ ISO 6346 (ค่าเริ่มต้น: true) |
match_reference Optional | boolean | จับคู่ D/O กับ AWB หรือ B/L ต้นทางในบัญชีของคุณ (ค่าเริ่มต้น: true) |
webhook_url Optional | string | URL สำหรับรับ POST callback เมื่อประมวลผลเสร็จสิ้น |
ตัวอย่างคำขอ (cURL)
การตอบกลับ (200 OK)
GET /v1/do/{id}
ดึงผลลัพธ์ใบสั่งปล่อยสินค้าที่แยกวิเคราะห์ไว้ก่อนหน้าโดยใช้ ID เฉพาะ ผลลัพธ์จะถูกจัดเก็บเป็นเวลา 90 วัน ใช้ endpoint นี้เพื่อดึงผลลัพธ์แบบอะซิงโครนัสเมื่อใช้ webhook หรือเพื่อเข้าถึงเอกสารที่แยกวิเคราะห์ไว้ก่อนหน้า สถานะการอนุมัติปล่อยสินค้าจะถูกรีเฟรชทุกครั้งที่ดึงข้อมูล
ส่งคืนผลลัพธ์การแยกวิเคราะห์แบบเต็มสำหรับใบสั่งปล่อยสินค้าที่ระบุ {id} คือตัวระบุเฉพาะที่ส่งคืนจาก endpoint /do/parse (เช่น do_7k2m9f3n1p4q) ส่งคืนโครงสร้างการตอบกลับเดียวกันกับ endpoint แยกวิเคราะห์พร้อมสถานะการปล่อยที่อัปเดตแล้ว
พารามิเตอร์เส้นทาง
| Parameter | Type | Description |
|---|---|---|
id Required | string | ID ผลลัพธ์ D/O เฉพาะ (เช่น do_7k2m9f3n1p4q) |
พารามิเตอร์คิวรี
| Parameter | Type | Description |
|---|---|---|
include_raw Optional | boolean | รวมข้อความ OCR ดิบในการตอบกลับ (ค่าเริ่มต้น: false) |
refresh_status Optional | boolean | ตรวจสอบสถานะการอนุมัติปล่อยจากท่าเทียบเรืออีกครั้ง (ค่าเริ่มต้น: false) |
POST /v1/do/batch
ส่งเอกสารใบสั่งปล่อยสินค้าหลายฉบับเพื่อประมวลผลแบบแบตช์ API รองรับเอกสารสูงสุด 50 ฉบับต่อคำขอแบตช์และประมวลผลแบบอะซิงโครนัส เหมาะสำหรับการประมวลผลชุดปล่อยสินค้าประจำวันจากท่าเรือหรือการแปลงเอกสาร D/O ย้อนหลังเป็นดิจิทัลจำนวนมาก
ส่งชุดเอกสาร D/O สำหรับการประมวลผลแบบอะซิงโครนัส ส่งคืนทันทีพร้อม batch ID และ ID เอกสารแต่ละฉบับ เอกสารแต่ละฉบับถูกประมวลผลอย่างอิสระ — ความล้มเหลวของฉบับหนึ่งจะไม่กระทบฉบับอื่น การตรวจสอบตู้คอนเทนเนอร์และการจับคู่เลขอ้างอิงจะถูกนำไปใช้กับเอกสารแต่ละฉบับ
เนื้อหาคำขอ
| Parameter | Type | Description |
|---|---|---|
documents Required | array | อาร์เรย์ของออบเจกต์เอกสาร (สูงสุด 50) แต่ละออบเจกต์มีฟิลด์ document และ format |
webhook_url Optional | string | URL สำหรับรับ POST callback เมื่อแบตช์ทั้งหมดเสร็จสมบูรณ์ |
priority Optional | string | normal (ค่าเริ่มต้น) หรือ high (เฉพาะแผน Professional/Enterprise) |
validate_iso6346 Optional | boolean | ตรวจสอบหมายเลขตู้คอนเทนเนอร์ทั้งหมดตามมาตรฐาน ISO 6346 (ค่าเริ่มต้น: true) |
GET /v1/status
ตรวจสอบสถานะ API และการใช้งานบัญชีของคุณ ส่งคืนสถานะ API ปัจจุบัน รายละเอียดแผนของคุณ และโควตาคำขอที่เหลือสำหรับรอบการเรียกเก็บเงินปัจจุบัน
ส่งคืนสถานะการทำงานของ API ข้อมูลแผนบัญชีของคุณ และสถิติการใช้งานปัจจุบัน ใช้สิ่งนี้เพื่อตรวจสอบโควตาของคุณหรือยืนยันการเชื่อมต่อก่อนส่งงานแบตช์
อ้างอิงส่วนต่างๆ ของ D/O
KabyTech API แยกวิเคราะห์ส่วนมาตรฐานทั้งหมดของใบสั่งปล่อยสินค้า ด้านล่างนี้คือส่วนหลักที่ส่งคืนในการตอบกลับสำหรับเอกสาร D/O ทุกฉบับที่แยกวิเคราะห์แล้ว แต่ละส่วนจัดกลุ่มฟิลด์ที่เกี่ยวข้องเพื่อให้ง่ายต่อการเชื่อมต่อกับระบบจัดการท่าเทียบเรือ (TOS) และขั้นตอนศุลกากร
| # | ส่วน | คีย์ | คำอธิบาย |
|---|---|---|---|
| 1 | ส่วนหัว | header | หมายเลข D/O, วันที่ออก, ประเภทเอกสาร (ต้นฉบับ/สำเนา), ท่าเทียบเรือที่ออก |
| 2 | คู่สัญญา | parties | ผู้ออกเอกสาร (สายเรือ/ตัวแทน), ผู้รับสินค้า, ตัวแทนสินค้า, ผู้รับแจ้ง |
| 3 | เลขอ้างอิง | reference | การจับคู่หมายเลข AWB หรือ B/L, เลขอ้างอิงการจอง, เรือ/เที่ยวเรือหรือเที่ยวบิน |
| 4 | ตู้คอนเทนเนอร์ | container | หมายเลขตู้คอนเทนเนอร์ (ตรวจสอบแล้วตาม ISO 6346), ขนาด/ประเภท, หมายเลขซีล, น้ำหนักตู้เปล่า |
| 5 | รายละเอียดสินค้า | cargo | รายละเอียดสินค้า, รหัส HS, จำนวนหีบห่อ, น้ำหนักรวม, ปริมาตร (CBM) |
| 6 | ท่าเทียบเรือและการปล่อย | release | ชื่อ/รหัสท่าเทียบเรือ, ท่าจอด, ประเภทการปล่อย (เต็มจำนวน/บางส่วน), สถานะการอนุมัติและเวลา |
| 7 | ศุลกากร | customs | เลขอ้างอิงใบขนสินค้า, หมายเลขใบอนุญาตนำเข้า, สถานะการชำระภาษี |
| 8 | ค่าใช้จ่าย | charges | วันหมดระยะฟรี, ค่าฝากเก็บ (อัตราต่อวัน, สะสม), ค่าเสียเวลาเรือ, ค่าจัดการ |
แต่ละส่วนจะถูกส่งคืนเป็นออบเจกต์ซ้อนภายในการตอบกลับ ฟิลด์ที่ไม่สามารถสกัดได้จะถูกส่งคืนเป็น null พร้อมคะแนนความเชื่อมั่น 0 ใช้ include_confidence: true เพื่อรับคะแนนรายฟิลด์
อ้างอิงฟิลด์การตอบกลับ
การตอบกลับ API ทุกรายการจะรวมฟิลด์ระดับบนสุดเหล่านี้พร้อมกับออบเจกต์ส่วนต่างๆ ฟิลด์ทั้งหมดมากกว่า 25 รายการจะถูกสกัดพร้อมคะแนนความเชื่อมั่นแต่ละรายการ
name, address และ code
name, address และ tax_id
name และ iata_code
match_reference
full (ปล่อยเต็มจำนวน) หรือ partial (แบ่งส่ง)
currency, daily_rate, accrued
field, message และ severity
รหัสข้อผิดพลาด
API ใช้รหัสสถานะ HTTP มาตรฐาน การตอบกลับข้อผิดพลาดทั้งหมดจะรวมเนื้อหา JSON พร้อมฟิลด์ error, message และ code
| สถานะ | รหัส | คำอธิบาย |
|---|---|---|
| 400 | invalid_document | ไม่สามารถอ่านเอกสารได้ ตรวจสอบพารามิเตอร์การเข้ารหัสและรูปแบบ |
| 400 | unsupported_format | รูปแบบเอกสารไม่รองรับ ใช้ pdf, png, jpg หรือ tiff |
| 400 | invalid_container | หมายเลขตู้คอนเทนเนอร์ไม่ผ่านการตรวจสอบเลขตรวจ ISO 6346 |
| 401 | invalid_api_key | API key หายไป ไม่ถูกต้อง หรือหมดอายุ |
| 403 | plan_limit_exceeded | โควตาคำขอรายเดือนเกินกำหนด อัปเกรดแผนของคุณหรือรอการรีเซ็ต |
| 404 | do_not_found | ไม่พบผลลัพธ์การแยกวิเคราะห์สำหรับ ID ที่ระบุ ผลลัพธ์จะหมดอายุหลัง 90 วัน |
| 422 | parse_failed | อ่านเอกสารได้แต่ไม่สามารถสกัดข้อมูล D/O ได้ ตรวจสอบเนื้อหาเอกสาร |
| 429 | rate_limited | คำขอมากเกินไป โปรดปฏิบัติตามขีดจำกัดอัตราสำหรับระดับแผนของคุณ |
| 500 | internal_error | ข้อผิดพลาดเซิร์ฟเวอร์ที่ไม่คาดคิด ลองส่งคำขอใหม่ หากยังคงเกิดขึ้น โปรดติดต่อฝ่ายสนับสนุน |
| 503 | service_unavailable | API ไม่พร้อมใช้งานชั่วคราวเนื่องจากการบำรุงรักษา โดยปกติไม่เกิน 5 นาที |
ขีดจำกัดอัตรา
ขีดจำกัดอัตราแตกต่างกันตามระดับแผน ขีดจำกัดทั้งหมดใช้ต่อ API key ในรูปแบบต่อนาทีและต่อเดือน ส่วนหัวขีดจำกัดอัตราจะรวมอยู่ในการตอบกลับทุกครั้ง
60
คำขอ/นาที
แผน Starter
300
คำขอ/นาที
แผน Professional
1,000
คำขอ/นาที
แผน Enterprise
| ส่วนหัวการตอบกลับ | คำอธิบาย |
|---|---|
X-RateLimit-Limit | จำนวนคำขอสูงสุดต่อนาทีสำหรับแผนของคุณ |
X-RateLimit-Remaining | คำขอที่เหลือในช่วงนาทีปัจจุบัน |
X-RateLimit-Reset | เวลา Unix เมื่อช่วงขีดจำกัดอัตรารีเซ็ต |
SDK อย่างเป็นทางการ
เรามี SDK อย่างเป็นทางการสำหรับภาษาโปรแกรมยอดนิยมในระบบนิเวศเทคโนโลยีโลจิสติกส์ไทย SDK ทั้งหมดเป็นโอเพนซอร์สและพร้อมใช้งานบน GitHub
Python
Python 3.8+
pip install kabytech
Node.js
Node 16+
npm i @kabytech/sdk
PHP
PHP 8.0+
composer require kabytech/sdk
Java
Java 11+
co.th.kabytech:sdk:1.4.0
ต้องการความช่วยเหลือในการเชื่อมต่อ?
ทีมเชื่อมต่อของเราสามารถช่วยคุณเชื่อมต่อ KabyTech D/O API กับระบบจัดการท่าเทียบเรือ (TOS), CargoWise หรือแพลตฟอร์มจัดการศุลกากรของคุณ