บทนำ

KabyTech AWB Intelligence API ช่วยให้คุณดึงข้อมูลจากเอกสาร Air Waybill (PDF, รูปภาพ หรือข้อความ Cargo-IMP ดิบ) และรับ JSON ที่มีโครงสร้างพร้อมทั้ง 29 ส่วน FWB ที่ดึงข้อมูลแล้ว API นี้สร้างขึ้นสำหรับการดำเนินงานขนส่งสินค้าทางอากาศของไทย และรองรับรูปแบบ MAWB, HAWB และข้อความ FWB/FHL

คำขอ API ทั้งหมดส่งผ่าน HTTPS การตอบกลับอยู่ในรูปแบบ JSON ตาม API เป็นไปตามหลักการ RESTful และใช้รหัสสถานะ HTTP มาตรฐาน

Base URL

Base https://api.kabytech.co.th/v1

Endpoint ทั้งหมดที่อธิบายในเอกสารนี้สัมพันธ์กับ Base URL นี้ เช่น endpoint สำหรับดึงข้อมูลพร้อมใช้งานที่ https://api.kabytech.co.th/v1/awb/parse

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

คำขอ API ทั้งหมดต้องมีการยืนยันตัวตนด้วย API key ใส่ API key ของคุณใน header X-API-Key ในทุกคำขอ คุณสามารถรับ API key จาก KabyTech Dashboard หลังจากสร้างบัญชีแล้ว

Authentication Header
X-API-Key: kby_live_a1b2c3d4e5f6g7h8i9j0...

API key มีคำนำหน้า kby_live_ สำหรับ production และ kby_test_ สำหรับ sandbox คีย์ทดสอบประมวลผลเอกสารแต่ส่งคืนข้อมูลสังเคราะห์ — ใช้ฟรีระหว่างการพัฒนา

Header	ค่า	จำเป็น
`X-API-Key`	API key ของคุณ (`kby_live_...` หรือ `kby_test_...`)	จำเป็น
`Content-Type`	`application/json` หรือ `multipart/form-data`	จำเป็น
`Accept`	`application/json`	ทางเลือก

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

ดึงข้อมูล AWB แรกของคุณภายใน 5 นาที ตัวอย่างนี้ใช้ Python SDK ในการอัปโหลด PDF และรับข้อมูลที่มีโครงสร้าง

Python — Quick Start
from kabytech import KabyTechClient
 
# Initialize client with your API key
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Parse an AWB document (PDF, PNG, JPG, or raw text)
result = client.awb.parse(
    file="./awb-documents/TG-217-12345678.pdf",
    options={
        "include_confidence": True,
        "validate_iata": True,
        "output_format": "fwb16"
    }
)
 
# Access parsed AWB data
print(f"AWB Number: {result.awb_number}")
print(f"Origin: {result.origin} → Destination: {result.destination}")
print(f"Sections parsed: {result.sections_parsed}/29")
print(f"Confidence: {result.confidence}%")
print(f"Processing time: {result.processing_ms}ms")
 
# Access specific FWB sections
shipper = result.sections.shipper
print(f"Shipper: {shipper.name}, {shipper.address}")
 
consignee = result.sections.consignee
print(f"Consignee: {consignee.name}")
 
# Check for validation errors
if result.validation_errors:
    for err in result.validation_errors:
        print(f"Warning: {err.field} — {err.message}")

POST /awb/parse

ดึงข้อมูลจากเอกสาร AWB เดียวและส่งคืนข้อมูลที่มีโครงสร้าง รับ PDF, PNG, JPG, TIFF หรือข้อความ IATA Cargo-IMP ดิบ ส่งคืนทั้ง 29 ส่วน FWB เป็น JSON ที่มีโครงสร้าง

POST /v1/awb/parse

ดึงข้อมูลจากเอกสาร Air Waybill และแยกส่วน IATA Cargo-IMP FWB ทั้งหมด รองรับการอัปโหลด PDF (base64 หรือ multipart) ไฟล์รูปภาพ และข้อความ FWB ดิบ เวลาประมวลผลเฉลี่ย 1.2–1.8 วินาทีต่อเอกสาร

Request Body (JSON)

พารามิเตอร์	ประเภท	คำอธิบาย
`document` จำเป็น	`string`	เนื้อหาเอกสารที่เข้ารหัส Base64 (PDF, PNG, JPG, TIFF)
`format` จำเป็น	`string`	รูปแบบเอกสาร: `pdf`, `png`, `jpg`, `tiff` หรือ `text`
`include_confidence` ทางเลือก	`boolean`	รวมคะแนนความมั่นใจรายฟิลด์ (ค่าเริ่มต้น: `true`)
`validate_iata` ทางเลือก	`boolean`	ตรวจสอบตามกฎ IATA Cargo-IMP (ค่าเริ่มต้น: `true`)
`output_format` ทางเลือก	`string`	รูปแบบผลลัพธ์: `fwb16` (ค่าเริ่มต้น), `fwb15` หรือ `flat`
`webhook_url` ทางเลือก	`string`	URL สำหรับรับ POST callback เมื่อการประมวลผลเสร็จสิ้น

ตัวอย่าง Request (cURL)

cURL — Parse AWB
curl -X POST https://api.kabytech.co.th/v1/awb/parse \
  -H "X-API-Key: kby_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "document": "JVBERi0xLjQKMS...",
    "format": "pdf",
    "include_confidence": true,
    "validate_iata": true
  }'

Response (200 OK)

JSON Response — 200 OK · 1.43s
{
  "id": "awb_8f3k2j1m9n4p",
  "awb_number": "217-12345678",
  "airline_code": "TG",
  "origin": "BKK",
  "destination": "NRT",
  "sections_parsed": 29,
  "confidence": 97.3,
  "processing_ms": 1430,
  "validation_errors": [],
  "sections": {
    "awb_identification": {
      "prefix": "217",
      "serial_number": "12345678",
      "check_digit": "8",
      "origin": "BKK",
      "destination": "NRT"
    },
    "shipper": {
      "name": "SIAM EXPORT CO LTD",
      "address": "123 SUKHUMVIT RD BANGKOK 10110",
      "account_number": "TG-SHP-0042"
    },
    "consignee": { /* ... */ },
    "routing": { /* ... */ },
    "charges": { /* ... */ },
    // ... ทั้ง 29 ส่วน
  },
  "created_at": "2026-03-26T09:15:32Z"
}

GET /awb/{id}

ดึงผลลัพธ์ AWB ที่เคยดึงข้อมูลแล้วด้วย ID เฉพาะ ผลลัพธ์จัดเก็บเป็นเวลา 90 วัน ใช้ endpoint นี้เพื่อดึงผลลัพธ์แบบ asynchronous เมื่อใช้ webhooks หรือเพื่อเข้าถึงเอกสารที่เคยดึงข้อมูลแล้ว

GET /v1/awb/{id}

ส่งคืนผลลัพธ์การดึงข้อมูลแบบเต็มสำหรับเอกสาร AWB เฉพาะ {id} คือตัวระบุเฉพาะที่ส่งคืนจาก endpoint /awb/parse (เช่น awb_8f3k2j1m9n4p) ส่งคืน response schema เดียวกันกับ endpoint parse

Path Parameters

พารามิเตอร์	ประเภท	คำอธิบาย
`id` จำเป็น	`string`	ID ผลลัพธ์ AWB เฉพาะ (เช่น `awb_8f3k2j1m9n4p`)

cURL — Get AWB by ID
curl https://api.kabytech.co.th/v1/awb/awb_8f3k2j1m9n4p \
  -H "X-API-Key: kby_live_a1b2c3d4..."

POST /awb/batch

ส่งเอกสาร AWB หลายฉบับสำหรับการประมวลผลแบบกลุ่ม API รับได้สูงสุด 50 เอกสารต่อ batch request และประมวลผลแบบ asynchronous ใช้พารามิเตอร์ webhook_url หรือเรียก endpoint GET /awb/{id} เพื่อดูผลลัพธ์

POST /v1/awb/batch

ส่ง batch ของเอกสาร AWB สำหรับการประมวลผลแบบ asynchronous ส่งคืนทันทีพร้อม batch ID และ document ID แต่ละรายการ แต่ละเอกสารประมวลผลอิสระ — หนึ่งเอกสารล้มเหลวจะไม่กระทบเอกสารอื่น เหมาะสำหรับการประมวลผล manifest รายวันหรือการแปลงเอกสารเก่าเป็นดิจิทัลจำนวนมาก

Request Body

พารามิเตอร์	ประเภท	คำอธิบาย
`documents` จำเป็น	`array`	อาร์เรย์ของออบเจ็กต์เอกสาร (สูงสุด 50) แต่ละออบเจ็กต์มีฟิลด์ `document` และ `format`
`webhook_url` ทางเลือก	`string`	URL สำหรับรับ POST callback เมื่อ batch ทั้งหมดเสร็จสมบูรณ์
`priority` ทางเลือก	`string`	`normal` (ค่าเริ่มต้น) หรือ `high` (เฉพาะแผน Professional/Enterprise)

Python — Batch Processing
from kabytech import KabyTechClient
import glob
 
client = KabyTechClient(api_key="kby_live_a1b2c3d4...")
 
# Collect all AWB PDFs from a directory
files = glob.glob("./daily-awbs/*.pdf")
 
# Submit batch (max 50 per request)
batch = client.awb.batch(
    files=files,
    webhook_url="https://your-app.com/webhooks/kabytech",
    priority="high"
)
 
print(f"Batch ID: {batch.batch_id}")
print(f"Documents submitted: {batch.total_documents}")
 
# Or poll for results
results = batch.wait()  # Blocks until complete
for r in results:
    print(f"{r.awb_number}: {r.sections_parsed} sections, {r.confidence}%")

GET /status

ตรวจสอบสถานะ API และการใช้งานบัญชีของคุณ ส่งคืนสถานะ API ปัจจุบัน รายละเอียดแผนของคุณ และโควต้าคำขอที่เหลือสำหรับรอบเรียกเก็บเงินปัจจุบัน

GET /v1/status

ส่งคืนสถานะสุขภาพ API ข้อมูลแผนบัญชีของคุณ และสถิติการใช้งานปัจจุบัน ใช้เพื่อตรวจสอบโควต้าหรือยืนยันการเชื่อมต่อ

JSON Response — GET /status
{
  "status": "operational",
  "version": "v1.8.2",
  "plan": "professional",
  "usage": {
    "period": "2026-03",
    "requests_used": 4283,
    "requests_limit": 10000,
    "batch_remaining": 5717
  }
}

อ้างอิงส่วน FWB

KabyTech API ดึงข้อมูลครบทั้ง 29 ส่วนของข้อความ IATA Cargo-IMP FWB ด้านล่างเป็นส่วนหลักที่ส่งคืนในออบเจ็กต์ sections ของทุก parse response

#	ส่วน	Key	คำอธิบาย
1	การระบุ AWB	`awb_identification`	Prefix, หมายเลขซีเรียล, check digit, ต้นทาง/ปลายทาง
2	การจองเที่ยวบิน	`flight_bookings`	รหัสสายการบิน, หมายเลขเที่ยวบิน, วันที่, รหัสการจัดสรร
3	เส้นทาง	`routing`	รหัสสนามบิน, ตัวกำหนดสายการบินต่อเที่ยว
4	ผู้ส่งสินค้า	`shipper`	ชื่อ, ที่อยู่, หมายเลขบัญชี, ข้อมูลติดต่อ
5	ผู้รับสินค้า	`consignee`	ชื่อ, ที่อยู่, หมายเลขบัญชี, ข้อมูลติดต่อ
6	ตัวแทน	`agent`	รหัส IATA, หมายเลขบัญชี, ชื่อ, สถานที่
7	คำขอบริการพิเศษ	`ssr`	รหัส SSR (เช่น SPH, DGR, PER, AVI)
8	การประกาศค่าใช้จ่าย	`charges`	ค่าใช้จ่ายน้ำหนัก/การประเมินมูลค่า, ตัวบ่งชี้จ่ายล่วงหน้า/เก็บเงินปลายทาง
…	ดึงข้อมูลครบทั้ง 29 ส่วน — ดูข้อกำหนด FWB/16 ฉบับเต็มใน dashboard ของคุณ

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

ทุก API response มีฟิลด์ระดับบนสุดเหล่านี้ร่วมกับออบเจ็กต์ sections

awb_number string หมายเลข AWB แบบเต็มในรูปแบบ prefix-serial (เช่น "217-12345678")

sections_parsed integer จำนวนส่วน FWB ที่ดึงข้อมูลสำเร็จ (สูงสุด 29)

confidence float ความมั่นใจในการดึงข้อมูลโดยรวมเป็นเปอร์เซ็นต์ (0–100) คะแนนเกิน 95% แสดงถึงความน่าเชื่อถือสูง

processing_ms integer เวลาประมวลผลเป็นมิลลิวินาที เฉลี่ย: 1,200–1,800ms สำหรับเอกสารเดี่ยว

validation_errors array อาร์เรย์ของคำเตือนการตรวจสอบ IATA แต่ละออบเจ็กต์มีคุณสมบัติ field, message และ severity

id string ตัวระบุผลลัพธ์เฉพาะสำหรับการดึงข้อมูลผ่าน GET /awb/{id} มีคำนำหน้า "awb_"

created_at string Timestamp ISO 8601 ของเวลาที่ประมวลผลเอกสาร (UTC)

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

API ใช้รหัสสถานะ HTTP มาตรฐาน response ข้อผิดพลาดทั้งหมดมี JSON body พร้อมฟิลด์ error, message และ code

สถานะ	รหัส	คำอธิบาย
400	`invalid_document`	ไม่สามารถอ่านเอกสารได้ ตรวจสอบการเข้ารหัสและพารามิเตอร์ format
400	`unsupported_format`	ไม่รองรับรูปแบบเอกสาร ใช้ pdf, png, jpg, tiff หรือ text
401	`invalid_api_key`	API key หายไป ไม่ถูกต้อง หรือหมดอายุ
403	`plan_limit_exceeded`	โควต้าคำขอรายเดือนเกินแล้ว อัปเกรดแผนหรือรอการรีเซ็ต
404	`awb_not_found`	ไม่พบผลลัพธ์สำหรับ ID ที่ให้มา ผลลัพธ์หมดอายุหลัง 90 วัน
422	`parse_failed`	อ่านเอกสารได้แต่ไม่สามารถดึงข้อมูล AWB ได้ ตรวจสอบเนื้อหาเอกสาร
429	`rate_limited`	คำขอมากเกินไป ปฏิบัติตามขีดจำกัดอัตราสำหรับระดับแผนของคุณ
500	`internal_error`	ข้อผิดพลาดเซิร์ฟเวอร์ที่ไม่คาดคิด ลองส่งคำขอใหม่ หากยังคงเกิดขึ้น ติดต่อฝ่ายสนับสนุน
503	`service_unavailable`	API ไม่พร้อมใช้งานชั่วคราวเพื่อการบำรุงรักษา โดยปกติไม่เกิน 5 นาที

Error Response Example — 401
{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked.",
  "code": 401
}

ขีดจำกัดอัตรา

ขีดจำกัดอัตราแตกต่างตามระดับแผน ขีดจำกัดทั้งหมดใช้ต่อ API key บนพื้นฐานต่อนาทีและต่อเดือน Response header ของขีดจำกัดอัตรารวมอยู่ในทุก response

60

คำขอ/นาที
แผน Starter

300

คำขอ/นาที
แผน Professional

1,000

คำขอ/นาที
แผน Enterprise

Response Header	คำอธิบาย
`X-RateLimit-Limit`	จำนวนคำขอสูงสุดต่อนาทีสำหรับแผนของคุณ
`X-RateLimit-Remaining`	จำนวนคำขอที่เหลือในหน้าต่างนาทีปัจจุบัน
`X-RateLimit-Reset`	Unix timestamp เมื่อหน้าต่างขีดจำกัดอัตรารีเซ็ต

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

เราจัดเตรียม SDK อย่างเป็นทางการสำหรับภาษาโปรแกรมที่ได้รับความนิยมมากที่สุดในระบบนิเวศเทคโนโลยีโลจิสติกส์ไทย SDK ทั้งหมดเป็น open source และพร้อมใช้งานบน 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

Node.js — Quick Example
const { KabyTech } = require('@kabytech/sdk');
 
const client = new KabyTech({ apiKey: 'kby_live_a1b2c3d4...' });
 
const result = await client.awb.parse({
  file: './awb.pdf',
  validateIata: true
});
 
console.log(result.awbNumber); // "217-12345678"
console.log(result.sectionsParsed); // 29
console.log(result.sections.shipper.name); // "SIAM EXPORT CO LTD"

ต้องการความช่วยเหลือในการเชื่อมต่อ?

ทีมเชื่อมต่อของเราช่วยคุณเชื่อมต่อ KabyTech API กับ CargoWise, SAP, Oracle TMS หรือระบบจัดการขนส่งสินค้าแบบกำหนดเองของคุณ

ติดต่อฝ่ายสนับสนุน เกี่ยวกับเรา

KabyTech API Reference