บทนำ

Railway Consignment Note (RCN) API สกัดข้อมูลที่มีโครงสร้างจากใบตราส่งสินค้าทางรถไฟแบบ CIM และ SMGS โดยใช้เทคโนโลยี OCR ขั้นสูงและ Machine Learning พัฒนาขึ้นโดยเฉพาะสำหรับระเบียงจีน-ลาว-ไทย (CLT) และการขนส่งสินค้าทางรถไฟข้ามแดนในภูมิภาค ASEAN โดย API สามารถจัดการเอกสารรถไฟที่มีหลายรูปแบบและหลายภาษาได้ด้วยความแม่นยำระดับองค์กร

API รองรับทั้งรูปแบบ CIM (Convention concerning International Carriage by Rail ที่ใช้ทั่วยุโรป) และ SMGS (Agreement on International Goods Transport by Rail ที่ใช้ในรัสเซีย กลุ่มประเทศ CIS และจีน) ความสามารถ OCR หลายภาษาครอบคลุมอักษรจีน (ตัวย่อและตัวเต็ม) ไทย อังกฤษ รัสเซีย และลาวพร้อมกันในเอกสารฉบับเดียว

ความสามารถหลัก ได้แก่ การตรวจจับรูปแบบอัตโนมัติ (CIM หรือ SMGS) การสกัดข้อมูลด่านชายแดนโม่ฮาน/บ่อเต็น การติดตามตู้สินค้าและตู้คอนเทนเนอร์ การแยกวิเคราะห์ใบขนสินค้าศุลกากร การระบุรหัส HS และการตรวจสอบหมายเลขซีล API ส่งคืนฟิลด์ที่มีโครงสร้างมากกว่า 40 รายการพร้อมคะแนนความเชื่อมั่นรายฟิลด์ ช่วยให้เชื่อมต่อกับระบบจัดการขนส่ง ระบบพิธีการศุลกากร และระบบติดตามโลจิสติกส์ได้อย่างราบรื่น

รูปแบบไฟล์ที่รองรับ: PDF, JPEG, PNG, TIFF (สูงสุด 20 MB ต่อไฟล์) เวลาประมวลผลเฉลี่ย: 1.2-2.8 วินาที ขึ้นอยู่กับความซับซ้อนของเอกสารและจำนวนภาษาที่ตรวจพบ

การยืนยันตัวตน

คำขอ API ทุกรายการต้องมี API key ที่ถูกต้องในส่วนหัว Authorization โดยใช้รูปแบบ Bearer token โดย API key จะผูกกับองค์กรของคุณ และสามารถสร้าง หมุนเวียน และเพิกถอนได้จากแดชบอร์ด

Authorization: Bearer YOUR_API_KEY

รับ API key ของคุณได้จาก dashboard.kabytech.com → Settings → API Keys แต่ละ key สามารถกำหนดสิทธิ์แบบละเอียด (read, write, batch) และระดับ rate limit ได้ เราแนะนำให้สร้าง key แยกสำหรับสภาพแวดล้อมการพัฒนาและการใช้งานจริง

แนวทางปฏิบัติด้านความปลอดภัย:

• อย่าเปิดเผย API key ในโค้ดฝั่งไคลเอนต์หรือ repository สาธารณะ
• หมุนเวียน key ทุก 90 วัน หรือทันทีหากถูกเปิดเผย
• ใช้ environment variable หรือ secrets manager ในการเก็บ key
• เปิดใช้งาน IP allowlisting สำหรับ key ที่ใช้ในการใช้งานจริงผ่านแดชบอร์ด

เริ่มต้นอย่างรวดเร็ว

แยกวิเคราะห์ใบตราส่งสินค้าทางรถไฟได้ในไม่กี่วินาที อัปโหลดเอกสาร CIM หรือ SMGS แล้วรับ JSON ที่มีโครงสร้างพร้อมฟิลด์ที่สกัดได้มากกว่า 40 รายการ คะแนนความเชื่อมั่น และข้อมูลเมตาการประมวลผล

curl -X POST https://api.kabytech.com/v1/rcn/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/consignment-note.pdf" \
  -F "language=zh" \
  -F "format_hint=smgs"

API จะตรวจจับโดยอัตโนมัติว่าเอกสารเป็นรูปแบบ CIM หรือ SMGS เพื่อความแม่นยำสูงสุดสำหรับเอกสารหลายภาษา (เช่น จีน-อังกฤษ หรือ รัสเซีย-อังกฤษ) ให้ระบุภาษาหลักเป็นพารามิเตอร์ language เอนจิน OCR จะยังคงตรวจจับและสกัดข้อความในภาษารองด้วย

ตัวอย่าง response สำหรับการขนส่งชิ้นส่วนรถยนต์เส้นทางคุนหมิง-เวียงจันทน์-แหลมฉบัง:

{
  "id": "job_rcn_8f3a2b1c9d4e",
  "status": "completed",
  "document_type": "rcn",
  "format_detected": "smgs",
  "data": {
    "consignment_number": "RCNKBT2026005678",
    "format": "smgs",
    "date_of_consignment": "2026-03-15",
    "sender": {
      "name": "Kunming Precision Auto Parts Co., Ltd.",
      "address": "88 Dianchi Road, Xishan District, Kunming, Yunnan 650228",
      "country": "CN",
      "contact_phone": "+86-871-6812-3456"
    },
    "recipient": {
      "name": "Laem Chabang Auto Distribution Co., Ltd.",
      "address": "456 Port Road, Si Racha, Chonburi 20230, Thailand",
      "country": "TH",
      "contact_phone": "+66-38-491-2345"
    },
    "station_from": {
      "name": "Kunming South",
      "code": "KMS",
      "country": "CN"
    },
    "station_to": {
      "name": "Laem Chabang",
      "code": "LCB",
      "country": "TH"
    },
    "route_via": ["Yuxi", "Mohan", "Boten", "Luang Prabang", "Vientiane", "Nong Khai", "Laem Chabang"],
    "wagon_number": "KZ4-5678901",
    "wagon_type": "covered",
    "container_numbers": ["KBTU2234567", "KBTU2234568"],
    "goods_description": "Automotive brake assemblies and suspension components, new, in cartons",
    "hs_code": "8708.30",
    "gross_weight": "24800 kg",
    "net_weight": "23200 kg",
    "number_of_packages": 480,
    "customs_declaration_number": "CD-2026-KM-001234",
    "seal_numbers": ["KBTS-20260315-001", "KBTS-20260315-002", "CN-CUSTOMS-887654"],
    "border_crossing": {
      "primary": { "checkpoint": "Mohan", "country_from": "CN", "country_to": "LA" },
      "secondary": { "checkpoint": "Nong Khai", "country_from": "LA", "country_to": "TH" }
    },
    "estimated_arrival": "2026-03-18T14:00:00+07:00",
    "freight_charges": { "currency": "CNY", "amount": 45600.00, "terms": "prepaid" },
    "special_declarations": "Fragile - Handle with care. Keep dry.",
    "document_language": "zh",
    "ocr_languages_detected": ["zh", "en"]
  },
  "confidence": 0.96,
  "field_confidences": {
    "consignment_number": 0.99,
    "sender.name": 0.97,
    "goods_description": 0.94,
    "hs_code": 0.95,
    "seal_numbers": 0.92
  },
  "processing_time_ms": 2140,
  "pages_processed": 3
}

POST /v1/rcn/parse

อัปโหลดใบตราส่งสินค้าทางรถไฟ (รูปแบบ CIM หรือ SMGS) เพื่อแยกวิเคราะห์ API รับไฟล์ PDF, JPEG, PNG และ TIFF ขนาดสูงสุด 20 MB เอกสารหลายหน้าได้รับการรองรับอย่างเต็มที่ โดยตัวแยกวิเคราะห์จะเชื่อมโยงข้อมูลจากทุกหน้าเพื่อสร้างผลลัพธ์ที่สมบูรณ์

สำหรับเอกสารที่มีหลายภาษา (พบบ่อยในการขนส่งผ่านระเบียง CLT) เอนจิน OCR จะตรวจจับและประมวลผลอักษรทุกชนิดที่มีอยู่โดยอัตโนมัติ การระบุพารามิเตอร์ language เป็นภาษาหลักจะช่วยปรับปรุงความแม่นยำในการสกัดข้อมูลสำหรับอักขระที่กำกวม

พารามิเตอร์คำขอ

ฟิลด์ Response

GET /v1/rcn/{id}

ดึงผลลัพธ์การแยกวิเคราะห์สำหรับใบตราส่งสินค้าทางรถไฟที่ส่งไปก่อนหน้านี้โดยใช้ job ID endpoint นี้มีประโยชน์อย่างยิ่งเมื่อคำขอแยกวิเคราะห์เริ่มต้นส่งคืนสถานะ "processing" ซึ่งบ่งชี้ว่าเอกสารยังอยู่ระหว่างการวิเคราะห์

ผลลัพธ์จะถูกเก็บรักษาไว้เป็นเวลา 30 วันหลังจากการแยกวิเคราะห์ หลังจากช่วงเวลานี้ job ID จะหมดอายุและระบบจะส่งคืนข้อผิดพลาด 404

พารามิเตอร์เส้นทาง

พารามิเตอร์ Query

curl https://api.kabytech.com/v1/rcn/job_rcn_8f3a2b1c9d4e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G -d "include_raw=false" -d "fields=consignment_number,sender,station_from,station_to,route_via"

{
  "id": "job_rcn_8f3a2b1c9d4e",
  "status": "completed",
  "document_type": "rcn",
  "format_detected": "smgs",
  "data": {
    "consignment_number": "RCNKBT2026005678",
    "sender": {
      "name": "Kunming Precision Auto Parts Co., Ltd.",
      "address": "88 Dianchi Road, Xishan District, Kunming, Yunnan 650228",
      "country": "CN"
    },
    "station_from": { "name": "Kunming South", "code": "KMS", "country": "CN" },
    "station_to": { "name": "Laem Chabang", "code": "LCB", "country": "TH" },
    "route_via": ["Yuxi", "Mohan", "Boten", "Luang Prabang", "Vientiane", "Nong Khai", "Laem Chabang"]
  },
  "confidence": 0.96,
  "processing_time_ms": 2140
}

POST /v1/rcn/batch

ส่งใบตราส่งสินค้าทางรถไฟสูงสุด 50 ฉบับเพื่อประมวลผลแบบกลุ่ม การแยกวิเคราะห์แบบกลุ่มเหมาะสำหรับการประมวลผลบัญชีสินค้าประจำวัน ชุดเอกสารใบขนสินค้าศุลกากร หรือการแปลงเอกสารย้อนหลังเป็นดิจิทัล แต่ละไฟล์จะถูกประมวลผลแยกกันและผลลัพธ์จะถูกรวบรวมเข้าด้วยกัน

งานแบบกลุ่มจะทำงานแบบ asynchronous เสมอ ใช้ batch_id ที่ได้รับเพื่อตรวจสอบผลลัพธ์ หรือระบุ webhook_url เพื่อรับ callback เมื่อเอกสารทั้งหมดประมวลผลเสร็จ

พารามิเตอร์คำขอ

curl -X POST https://api.kabytech.com/v1/rcn/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files[]=@consignment-001.pdf" \
  -F "files[]=@consignment-002.pdf" \
  -F "files[]=@consignment-003.pdf" \
  -F "language=zh" \
  -F "format_hint=smgs" \
  -F "webhook_url=https://your-server.com/webhooks/rcn-batch"

{
  "batch_id": "batch_rcn_7k2m9x4p",
  "status": "processing",
  "total_files": 3,
  "completed": 0,
  "failed": 0,
  "estimated_completion_seconds": 12,
  "results_url": "https://api.kabytech.com/v1/rcn/batch/batch_rcn_7k2m9x4p"
}

GET /v1/status

endpoint ตรวจสอบสถานะระบบสำหรับบริการแยกวิเคราะห์ RCN ส่งคืนสถานะการทำงานปัจจุบัน เวอร์ชัน API และจำนวนคิว endpoint นี้ไม่ต้องการการยืนยันตัวตน และสามารถใช้สำหรับการตรวจสอบและเฝ้าระวังระบบ

curl https://api.kabytech.com/v1/status

{
  "service": "rcn-parser",
  "status": "operational",
  "version": "2.4.1",
  "queue_depth": 7,
  "avg_processing_time_ms": 2050,
  "supported_formats": ["cim", "smgs"],
  "ocr_languages": ["zh", "en", "th", "lo", "ru"],
  "uptime_percent": 99.97,
  "last_incident": "2026-02-10T03:22:00Z"
}

ส่วนต่าง ๆ ของ RCN อ้างอิง

ใบตราส่งสินค้าทางรถไฟ (ทั้งรูปแบบ CIM และ SMGS) จัดเรียงเป็นส่วนมาตรฐาน API จะจับคู่ข้อมูลที่สกัดได้กับส่วนเชิงตรรกะเหล่านี้ ทำให้เข้าถึงส่วนเฉพาะของเอกสารได้ง่าย แต่ละส่วนประกอบด้วยฟิลด์ที่เกี่ยวข้องซึ่งจัดกลุ่มตามหน้าที่ในใบตราส่ง

ส่วนหัวเอกสาร

ฟิลด์ระบุตัวตนหลักที่ด้านบนของใบตราส่งสินค้า

ส่วนผู้ส่ง / ผู้รับ

ฝ่ายที่เกี่ยวข้องในการตราส่ง ทั้งรูปแบบ CIM และ SMGS บันทึกรายละเอียดของผู้ส่ง (ผู้ส่งสินค้า) และผู้รับ (ผู้รับสินค้า) แม้ว่าตำแหน่งฟิลด์จะแตกต่างกันระหว่างสองรูปแบบ

ส่วนเส้นทาง

สถานีต้นทางและปลายทาง เส้นทางผ่าน และจุดข้ามชายแดน ระเบียง CLT โดยทั่วไปจะผ่านด่านชายแดนโม่ฮาน (จีน) / บ่อเต็น (ลาว) และหนองคาย (ไทย) / ท่านาแล้ง (ลาว)

ส่วนรายละเอียดตู้สินค้า

ข้อมูลเกี่ยวกับตู้สินค้ารถไฟและตู้คอนเทนเนอร์ที่ใช้ในการขนส่ง

ส่วนสินค้าและน้ำหนัก

รายละเอียดสินค้า จำนวน และการวัดน้ำหนัก

ส่วนศุลกากร

ข้อมูลศุลกากรและการผ่านด่านชายแดนที่สกัดจากใบตราส่งสินค้า

ส่วนซีล

หมายเลขซีลที่ติดไว้กับตู้สินค้าและตู้คอนเทนเนอร์เพื่อการตรวจสอบความปลอดภัย API สกัดหมายเลขซีลจากทั้งข้อความที่พิมพ์และภาพถ่ายซีล

อ้างอิงฟิลด์ Response

อ้างอิงฉบับสมบูรณ์ของฟิลด์ทั้งหมดมากกว่า 40 รายการที่สกัดจากใบตราส่งสินค้าทางรถไฟ แต่ละฟิลด์มีคะแนนความเชื่อมั่น (0.0 ถึง 1.0) อยู่ในอ็อบเจกต์ field_confidences ฟิลด์ที่ไม่มีในเอกสารต้นฉบับจะส่งคืนเป็น null

รหัสข้อผิดพลาด

API ส่งคืนรหัสสถานะ HTTP มาตรฐานพร้อมกับเนื้อหา JSON ที่มี code สำหรับการจัดการแบบโปรแกรม และ message ที่อ่านเข้าใจง่าย ใช้ฟิลด์ code สำหรับการจัดการข้อผิดพลาดแบบโปรแกรม

ขีดจำกัดอัตราการเรียกใช้

ขีดจำกัดอัตราการเรียกใช้ถูกบังคับใช้ต่อ API key และแตกต่างกันตามระดับแผน ขีดจำกัดถูกบังคับใช้โดยอัลกอริทึม sliding window API ส่งคืนส่วนหัว rate limit พร้อมกับทุก response:

• X-RateLimit-Limit — จำนวนคำขอสูงสุดที่อนุญาตต่อนาที
• X-RateLimit-Remaining — จำนวนคำขอที่เหลือในหน้าต่างปัจจุบัน
• X-RateLimit-Reset — Unix timestamp เมื่อหน้าต่างรีเซ็ต
• Retry-After — จำนวนวินาทีที่ต้องรอก่อนลองใหม่ (เฉพาะ response 429)

SDK อย่างเป็นทางการ

KabyTech จัดเตรียม SDK อย่างเป็นทางการสำหรับภาษาโปรแกรมยอดนิยมเพื่อลดความซับซ้อนในการเชื่อมต่อกับ RCN API SDK ทุกตัวจัดการการยืนยันตัวตน การลองใหม่ การอัปโหลดไฟล์ และการแยกวิเคราะห์ response โดยอัตโนมัติ

# Python
pip install kabytech
from kabytech import KabyTech
client = KabyTech(api_key="YOUR_API_KEY")
result = client.rcn.parse("consignment-note.pdf", language="zh", format_hint="smgs")
print(result.data.consignment_number)
print(result.data.sender.name)
print(result.data.route_via)

// Node.js
npm install @kabytech/sdk
const { KabyTech } = require("@kabytech/sdk");
const client = new KabyTech({ apiKey: "YOUR_API_KEY" });
const result = await client.rcn.parse("consignment-note.pdf", {
  language: "zh",
  formatHint: "smgs",
  validateRoute: true
});
console.log(result.data.consignmentNumber);
console.log(result.data.sender.name);
console.log(result.data.borderCrossing.primary.checkpoint);

SDK เพิ่มเติมที่มีให้บริการ: Go (go get github.com/kabytech/kabytech-go), Java (Maven Central: com.kabytech:kabytech-sdk), PHP (composer require kabytech/sdk) เอกสาร SDK ฉบับสมบูรณ์มีให้บริการที่ docs.kabytech.com/sdks