คำขอแรกของคุณไปยัง Tracking API: คู่มือการใช้งาน REST Client ด้วย Postman และ Curl
ในการส่งคำขอไปยัง Tracking API ครั้งแรก ให้กำหนดค่า endpoint, authentication header และ JSON body ใน REST client จากนั้นส่งคำขอและตรวจสอบทั้ง HTTP status และ response body คู่มือนี้ใช้ Tracking API ของ 17TRACK เพื่อสาธิตเวิร์กโฟลว์เดียวกันใน Postman และ curl ได้แก่ ลงทะเบียนพัสดุ ขอข้อมูลการติดตาม และตรวจสอบว่าผลลัพธ์พร้อมให้แอปพลิเคชันของคุณใช้งานหรือไม่
เป้าหมายคือการทดสอบการผสานรวมขนาดเล็กที่ทำซ้ำได้ ไม่ใช่การนำไปใช้งานจริง คุณจะต้องมีข้อมูลรับรอง API และหมายเลขติดตามที่คุณได้รับอนุญาตให้ประมวลผล คำสั่งด้านล่างใช้รูปแบบ endpoint v2.2 โปรดยืนยันเวอร์ชันของ endpoint และข้อกำหนดเฉพาะบัญชีใน เอกสาร 17TRACK API ก่อนเรียกใช้
ทำความเข้าใจสิ่งที่คำขอแรกควรดำเนินการให้สำเร็จ
การผสานรวมการติดตามพัสดุมีสองส่วนที่แยกจากกัน ได้แก่ การแจ้งบริการว่าต้องการติดตามพัสดุใด และการดึงข้อมูลการติดตามที่เกี่ยวข้องกับพัสดุนั้น ในเวิร์กโฟลว์นี้ ทั้งสองส่วนเป็นคำขอที่แยกกัน การลงทะเบียนไม่ได้หมายความว่าพัสดุได้เคลื่อนที่แล้ว และการลงทะเบียนสำเร็จก็ไม่ได้รับประกันว่าเหตุการณ์จากผู้ให้บริการขนส่งจะพร้อมใช้งานทันที
สำหรับการทดสอบครั้งแรก ให้ใช้พัสดุเพียงหนึ่งรายการแทนการส่งเป็นชุด วิธีนี้ช่วยแยกข้อผิดพลาดด้านการยืนยันตัวตน หมายเลขติดตามที่ไม่ถูกต้อง และการตีความผลลัพธ์ได้ง่ายขึ้น เป้าหมายแรกที่มีประโยชน์ไม่ใช่เพียง “ฉันได้รับ HTTP 200” แต่คือ “API ยอมรับการดำเนินการที่ฉันต้องการ และฉันสามารถอธิบายผลลัพธ์ระดับพัสดุได้”
Postman มีอินเทอร์เฟซแบบภาพสำหรับแก้ไขคำขอและตรวจสอบการตอบกลับ ส่วน curl ทำให้การแลกเปลี่ยน HTTP เดียวกันสามารถทำซ้ำได้จากเทอร์มินัล ทั้งสองอย่างไม่ได้เปลี่ยนกฎการยืนยันตัวตน ข้อมูลพัสดุ หรือพฤติกรรมการประมวลผลของ API ให้ใช้เครื่องมือที่ช่วยตรวจสอบคำขอได้ชัดเจนกว่า จากนั้นทำซ้ำการกำหนดค่าที่ใช้งานได้ในอีกเครื่องมือหนึ่ง
เตรียมข้อมูลรับรอง พัสดุ และรายละเอียดคำขอ
ก่อนเปิด client ใดก็ตาม ให้เตรียมสิ่งต่อไปนี้:
- ข้อมูลรับรอง API ที่ได้รับอนุญาต: ขอรับผ่านการตั้งค่าบัญชี 17TRACK API เซสชันติดตามสำหรับผู้บริโภคไม่สามารถใช้แทนข้อมูลรับรอง API ได้
- หมายเลขติดตามจริง: ใช้พัสดุที่คุณเป็นเจ้าของหรือได้รับอนุญาตให้เข้าถึง พัสดุที่มีการใช้งานล่าสุดมักมีประโยชน์กว่าหมายเลขที่สร้างขึ้นเองเมื่อต้องการทดสอบข้อมูลการติดตามจริง
- ผู้ให้บริการขนส่ง หากทราบ: เตรียมชื่อผู้ให้บริการไว้เพื่อการวินิจฉัย หากกรณีของคุณต้องใช้ตัวระบุผู้ให้บริการ ให้ใช้ค่าและฟิลด์ที่กำหนดไว้ในเอกสาร API แทนการคาดเดา
- สัญญาคำขอปัจจุบัน: ยืนยันเวอร์ชัน API, authentication header, request schema และข้อจำกัดของบัญชี
- พื้นที่ทำงานที่ปลอดภัย: หลีกเลี่ยงการใส่ข้อมูลรับรอง รายละเอียดลูกค้า หรือผลตอบกลับการติดตามฉบับเต็มใน repository สาธารณะ ภาพหน้าจอ หรือข้อความสนับสนุนที่แชร์ต่อ
ตัวอย่างคำขอขั้นต่ำใช้การตั้งค่าดังนี้:
| การตั้งค่า | การกำหนดค่าตัวอย่าง |
|---|---|
| Base URL | https://api.17track.net/track/v2.2 |
| การดำเนินการลงทะเบียน | POST /register |
| การดำเนินการข้อมูลการติดตาม | POST /gettrackinfo |
| Authentication header | 17token: YOUR_API_TOKEN |
| รูปแบบ body | Content-Type: application/json พร้อม JSON array ของออบเจ็กต์พัสดุ |
เก็บหมายเลขติดตามไว้ในรูปแบบสตริง การแปลงเป็นชนิดตัวเลขอาจทำให้เลขศูนย์นำหน้าหายไปหรือทำให้ค่าเปลี่ยนแปลง Placeholder YOUR_TRACKING_NUMBER ด้านล่างต้องแทนที่ด้วยพัสดุทดสอบจริงของคุณ ไม่ใช่หมายเลขตัวอย่างที่ใช้งานได้
ส่งคำขอลงทะเบียนใน Postman
1. สร้างสภาพแวดล้อมทดสอบขนาดเล็ก
ใน Postman ให้สร้าง environment ที่มีตัวแปรสามรายการ: base_url, tracking_token และ tracking_number ตั้งค่า base_url เป็น Base URL ด้านบน และใส่ข้อมูลรับรองกับหมายเลขพัสดุในตัวแปรอื่น เลือก environment นั้นก่อนส่งคำขอ
ใช้การควบคุมการจัดการความลับที่ Postman มีให้สำหรับ token และตรวจสอบว่าสิ่งใดใน workspace ของคุณถูกแชร์หรือซิงโครไนซ์ การซ่อนค่าในอินเทอร์เฟซไม่ใช่สิ่งทดแทนการควบคุมว่าใครเข้าถึงค่าได้ อย่าส่งออกข้อมูลรับรองที่กรอกแล้วพร้อม collection ที่ตั้งใจแชร์กับเพื่อนร่วมงานหรือเผยแพร่เป็นเอกสารสาธารณะ
2. กำหนดค่า method, URL และ headers
สร้าง HTTP request เลือก POST และป้อน {{base_url}}/register เป็น URL ในแท็บ Headers ให้เพิ่ม:
17token: {{tracking_token}}
Content-Type: application/json
สำหรับตัวอย่างนี้ ข้อมูลรับรองต้องอยู่ใน custom header 17token อย่าเปลี่ยนเป็นการกำหนดค่า Bearer token เพียงเพราะ API อื่นใช้รูปแบบนั้น นอกจากนี้ให้ตรวจสอบว่า collection settings ที่สืบทอดมาไม่ได้เพิ่ม Authorization header โดยไม่ตั้งใจ
3. เพิ่ม JSON body
เปิด Body เลือก raw แล้วเลือก JSON ป้อน:
[
{
"number": "{{tracking_number}}"
}
]
วงเล็บเหลี่ยมด้านนอกมีความสำคัญ คำขอนี้ใช้ array แม้จะมีพัสดุเพียงรายการเดียว ใช้เครื่องหมายคำพูดคู่ ลบ comma ท้ายรายการ และอย่าใส่ความคิดเห็นใน JSON หากเอกสารกำหนดข้อมูลเพิ่มเติมสำหรับผู้ให้บริการหรือพัสดุของคุณ ให้เพิ่มฟิลด์ที่ระบุไว้ก่อนส่ง
4. ส่งและตรวจสอบผลลัพธ์
คลิก Send ขั้นแรกตรวจสอบว่าคุณได้รับ HTTP response หรือไม่ DNS failure, TLS error, proxy problem หรือ timeout แตกต่างจาก response ที่อธิบายว่าคำขอไม่ถูกต้อง จากนั้นตรวจสอบ response body เพื่อดูผลการดำเนินการและข้อมูลการยอมรับหรือปฏิเสธในระดับพัสดุ
บันทึกคำขอเป็น “Register test shipment” จดบันทึก HTTP status, ผลลัพธ์ API และข้อความแสดงข้อผิดพลาด โดยไม่คัดลอก token หากการลงทะเบียนล้มเหลว ให้แก้ไขความล้มเหลวนั้นก่อนดำเนินการต่อ การส่งคำขอเดิมซ้ำ ๆ ทำให้วินิจฉัยได้ยากขึ้นและอาจใช้ทรัพยากรของบัญชี
ทำซ้ำคำขอด้วย curl
คำสั่งต่อไปนี้ใช้ POSIX-style shell เช่น Bash หรือ Zsh ส่วน PowerShell และ Windows Command Prompt มีกฎการใส่เครื่องหมายคำพูดและตัวแปรต่างกัน ใน PowerShell ให้ใช้ curl.exe เมื่อจำเป็น เพื่อเรียกใช้ curl executable แทน command alias เฉพาะของ shell
ตั้งค่า Base URL และโหลดข้อมูลรับรองลงใน environment variable ผ่านเวิร์กโฟลว์การจัดการความลับตามปกติ:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# ตั้งค่า TRACKING_API_TOKEN อย่างปลอดภัยก่อนดำเนินการต่อ
Environment variable ช่วยไม่ให้ข้อมูลรับรองอยู่ในตัวอย่างที่นำกลับมาใช้ซ้ำได้ แต่ไม่ใช่ระบบจัดการความลับที่สมบูรณ์ สำหรับการทดสอบในเครื่อง ให้หลีกเลี่ยงการพิมพ์ token จริงในคำสั่งที่ shell history จะเก็บไว้ สำหรับระบบอัตโนมัติ ให้ใช้ secret store ของแพลตฟอร์มและจำกัดข้อมูลใน log
สร้างไฟล์ชื่อ shipment.json และแทนที่ placeholder ด้วยหมายเลขติดตามสำหรับทดสอบ:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
ส่งคำขอลงทะเบียน:
curl --request POST \
--url "$TRACKING_BASE_URL/register" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output register-response.json \
--write-out 'HTTP status: %{http_code}\n'
คำสั่งนี้บันทึก response body ลงใน register-response.json และพิมพ์ HTTP status แยกต่างหาก ค่า timeout ของการเชื่อมต่อและเวลารวมเป็นตัวเลือกสำหรับการทดสอบในเครื่อง ไม่ใช่การรับประกันของบริการ 17TRACK เปิดไฟล์ที่บันทึกไว้เพื่อตรวจสอบผลลัพธ์ API เนื่องจากดูเฉพาะ status line ไม่เพียงพอ
curl สามารถถ่ายโอนข้อมูลเสร็จสมบูรณ์ได้แม้เซิร์ฟเวอร์จะส่ง HTTP error response ในทางกลับกัน transport failure อาจทำให้ไม่มี API response ที่ใช้งานได้ เมื่อเขียนสคริปต์ ให้จัดการ curl exit status, HTTP status และผลลัพธ์ระดับแอปพลิเคชันเป็นสัญญาณที่แยกจากกัน
ขอข้อมูลการติดตามของพัสดุ
หลังยืนยันการลงทะเบียนแล้ว ให้ทำสำเนาคำขอใน Postman และเปลี่ยน URL เป็น {{base_url}}/gettrackinfo คง POST method, authentication header, content type และ shipment body เดิมไว้ บันทึกแยกต่างหากเพื่อไม่ให้ลงทะเบียนพัสดุซ้ำโดยไม่ตั้งใจเมื่อคุณต้องการดึงข้อมูล
คำขอ curl ที่เทียบเท่าคือ:
curl --request POST \
--url "$TRACKING_BASE_URL/gettrackinfo" \
--header "17token: $TRACKING_API_TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @shipment.json \
--connect-timeout 10 \
--max-time 30 \
--silent --show-error \
--output tracking-response.json \
--write-out 'HTTP status: %{http_code}\n'
อย่าสันนิษฐานว่าพัสดุที่เพิ่งลงทะเบียนจะส่งคืนประวัติเหตุการณ์ที่สมบูรณ์ทันที ความพร้อมของข้อมูลขึ้นอยู่กับพัสดุและการประมวลผลของบริการ หากข้อมูลยังไม่พร้อม ให้ทำตามคำแนะนำในการดึงข้อมูลและอัปเดตที่ระบุไว้ แทนการลงทะเบียนหมายเลขเดิมซ้ำ ๆ หรือทำ polling loop ที่ถี่เกินไป
อ่าน response สามระดับ
- Transport: client เชื่อมต่อและได้รับ HTTP response หรือไม่?
- Operation: API ยอมรับคำขอหรือไม่ และพัสดุแต่ละรายการสำเร็จหรือไม่?
- ข้อมูลพัสดุ: ข้อมูลที่ส่งคืนระบุพัสดุที่ต้องการหรือไม่ และ status หรือประวัติเหตุการณ์ยืนยันอะไรได้จริง?
ใช้ response schema อย่างเป็นทางการเพื่อค้นหาฟิลด์ status, carrier และ event แยกความแตกต่างระหว่างสถานะพัสดุที่ทำให้เป็นมาตรฐานแล้วกับคำอธิบายเหตุการณ์ต้นฉบับของผู้ให้บริการ การค้นหาสำเร็จไม่ได้เป็นหลักฐานว่าจัดส่งแล้ว และการไม่มีเหตุการณ์ก็ไม่ได้เป็นหลักฐานว่าพัสดุสูญหาย
เมื่อจัดเก็บ timestamp ให้เก็บข้อมูลเขตเวลาหรือ offset ที่ส่งมาด้วย หลีกเลี่ยงการเรียงลำดับสตริงวันที่ดิบจากรูปแบบต่างกันแล้วสันนิษฐานว่าเป็นลำดับเวลาที่ถูกต้อง นอกจากนี้ให้แยกเวลาที่แอปพลิเคชันดึงข้อมูลออกจากเวลาที่เหตุการณ์ของพัสดุเกิดขึ้น
แก้ไขปัญหาโดยไม่เปลี่ยนทุกอย่างพร้อมกัน
- ไม่มี response: ตรวจสอบ hostname, network access, proxy settings, TLS configuration และ timeout ในเครื่อง อย่าปิดการตรวจสอบใบรับรองเป็นวิธีแก้ปัญหาตามปกติ
- การยืนยันตัวตนล้มเหลว: ยืนยันว่า token ยังใช้งานอยู่ มี header
17tokenและ environment ที่เลือกใน Postman แก้ค่าตัวแปรได้ถูกต้อง ตรวจสอบ whitespace ที่ไม่ตั้งใจ - คำขอไม่ถูกต้อง: ตรวจสอบ API version, operation path, POST method, content type และโครงสร้าง JSON array เทียบกับเอกสาร
- พัสดุถูกปฏิเสธ: อ่านข้อผิดพลาดเฉพาะพัสดุ ตรวจสอบหมายเลขและข้อมูลผู้ให้บริการที่จำเป็น แทนการถือว่าการปฏิเสธทุกกรณีเป็นปัญหาการยืนยันตัวตน
- ไม่มีเหตุการณ์การติดตาม: ยืนยันการลงทะเบียนและตัวตนของพัสดุที่ต้องการ ตรวจสอบว่าจำเป็นต้องมีข้อมูลผู้ให้บริการหรือไม่ และมีการอัปเดตพร้อมใช้งานก่อนลองใหม่หรือไม่
- Postman ใช้งานได้แต่ curl ล้มเหลว: เปรียบเทียบ URL ที่แก้ค่าแล้ว headers จริง และ body bytes การใส่เครื่องหมายคำพูดใน shell และ environment variables ที่ไม่ได้ตั้งค่าเป็นจุดที่คำขอแตกต่างกันได้บ่อย
เปลี่ยนตัวแปรทีละรายการต่อการทดสอบหนึ่งครั้งและจดบันทึกผลสั้น ๆ หากตรวจสอบ Postman console หรือใช้ verbose output ของ curl ให้ถือว่าข้อมูลดังกล่าวเป็นข้อมูลอ่อนไหว เนื่องจาก request headers อาจเปิดเผยข้อมูลรับรอง ให้ลบข้อมูลลับและข้อมูลลูกค้าก่อนแชร์ข้อมูลวินิจฉัย
รู้ว่าเมื่อใดคู่มือนี้เสร็จสมบูรณ์
คุณได้ทำการทดสอบการผสานรวมครั้งแรกที่มีความหมายสำเร็จเมื่อ client ทั้งสองส่งคำขอที่ต้องการ การลงทะเบียนเป็นที่เข้าใจ การดึงข้อมูลส่งคืนผลลัพธ์ที่ตีความได้ และคุณสามารถแยกความแตกต่างระหว่าง API failure กับพัสดุที่ไม่มีข้อมูลใหม่ได้ HTTP status ที่ตรงกันเพียงอย่างเดียวไม่ได้ยืนยันว่า client ทั้งสองทำงานเหมือนกันทุกประการ
ก่อนย้ายเวิร์กโฟลว์ไปไว้ในแอปพลิเคชัน ให้เก็บข้อมูลรับรองไว้บนเซิร์ฟเวอร์ ตรวจสอบอินพุต และใช้การจัดการข้อผิดพลาดแบบมีโครงสร้าง ศึกษา rate limits, batch limits, คำแนะนำการ retry และตัวเลือกการส่งอัปเดตที่ระบุไว้สำหรับบัญชีของคุณ อย่าสันนิษฐานว่าการลงทะเบียนสามารถ retry ได้อย่างปลอดภัยโดยไม่ตรวจสอบหลัง timeout เพราะเซิร์ฟเวอร์อาจประมวลผลคำขอแล้วแม้ client ของคุณจะไม่ได้รับ response
เพิ่มการทดสอบสำหรับข้อมูลรับรองที่ไม่ถูกต้อง JSON ที่มีรูปแบบผิด หมายเลขพัสดุไม่ถูกต้อง พัสดุที่ลงทะเบียนแล้ว ข้อมูลการติดตามที่ไม่พร้อมใช้งาน และ network timeout แต่ละกรณีควรนำไปสู่ผลลัพธ์ที่แอปพลิเคชันกำหนดไว้อย่างชัดเจน แทนที่จะเกิด unhandled exception หรือสถานะที่สื่อสารกับลูกค้าอย่างเข้าใจผิด
คำถามที่พบบ่อย
ฉันสามารถทดสอบโดยไม่มีหมายเลขติดตามจริงได้หรือไม่?
คุณสามารถทดสอบพฤติกรรมการตรวจสอบคำขอบางส่วนด้วยค่าที่ไม่ถูกต้องได้ แต่ไม่สามารถยืนยันการติดตามพัสดุได้ หากต้องการทดสอบเหตุการณ์จริง ให้ใช้พัสดุที่ได้รับอนุญาตหรือ test fixture ที่ระบุไว้ หากบริการมีให้ อย่าสันนิษฐานว่าหมายเลขตัวอย่างทั่วไปเป็นของ sandbox
เหตุใด HTTP 200 จึงยังมีความล้มเหลวอยู่?
HTTP status และผลลัพธ์ระดับแอปพลิเคชันอธิบายคนละชั้น เซิร์ฟเวอร์อาจรับและประมวลผลคำขอสำเร็จ แต่รายงานว่าพัสดุรายการหนึ่งถูกปฏิเสธ ให้อ่าน response body และผลลัพธ์ระดับพัสดุตามเอกสาร ไม่ใช่ดูเฉพาะ HTTP status
เหตุใดจึงใช้ POST เพื่อดึงข้อมูลการติดตาม?
ให้ใช้ method ที่กำหนดไว้ในสัญญาของ endpoint ตัวอย่างการดึงข้อมูลนี้รับตัวระบุพัสดุใน JSON request body ผ่าน POST การเปลี่ยนเป็น GET เพียงเพราะการดำเนินการเป็นการอ่านข้อมูล จะไม่คงรูปแบบคำขอตามเอกสาร
ฉันควรใส่ API token ใน JavaScript ของเบราว์เซอร์หรือไม่?
อย่าฝังข้อมูลรับรอง API ส่วนตัวไว้ใน frontend code ที่ส่งให้สาธารณะ ให้ส่งคำขอผ่าน backend ที่ได้รับอนุญาต ซึ่งปกป้องข้อมูลรับรอง ตรวจสอบอินพุต และควบคุมว่าผู้ใช้แต่ละรายเข้าถึงข้อมูลพัสดุใดได้บ้าง
ฉันจำเป็นต้องใช้ทั้ง Postman และ curl สำหรับ production หรือไม่?
ไม่จำเป็น ทั้งสองอย่างเป็นเครื่องมือทดสอบและวินิจฉัย แอปพลิเคชัน production ของคุณสามารถใช้ HTTP client ที่เหมาะสมได้ เก็บ Postman request หรือ curl command ที่ลบข้อมูลสำคัญแล้วไว้เป็นข้อมูลอ้างอิงที่ทำซ้ำได้ โดยไม่มี live token หรือข้อมูลลูกค้าที่ไม่จำเป็น
แหล่งข้อมูล
- เอกสาร 17TRACK API — ข้อมูลอ้างอิงเกี่ยวกับการยืนยันตัวตน สัญญา endpoint ฟิลด์คำขอ การตีความ response และข้อกำหนดการผสานรวม
- เอกสาร Postman: ส่ง API requests — การกำหนดค่าคำขอและการตรวจสอบ response
- เอกสาร Postman: Variables — การกำหนดค่าคำขอโดยใช้ตัวแปร
- คู่มือ curl — ตัวเลือกคำสั่งสำหรับ headers, request bodies, timeouts, response ที่บันทึกไว้ และการแสดง HTTP status


