เอกสาร API

ทุกอย่างที่ต้องใช้ในการเชื่อมต่อ T&P AITECH OCR กับระบบของคุณ

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

ส่ง API key ใน header Authorization ทุกคำขอ สร้างคีย์ได้ที่หน้า API Keys ในแดชบอร์ด

Authorization: Bearer tnp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

อ่านเอกสาร

POSThttps://api.tnpaitech.com/v1/ocr

ส่งไฟล์แบบ multipart/form-data หรือ JSON ระบบจะคืนผลลัพธ์ในคำขอเดียวกัน

พารามิเตอร์

ชื่อ	ชนิด	คำอธิบาย
`file`	file	ไฟล์เอกสาร (PNG, JPG, WEBP, PDF) — ใช้กับ multipart
`file_base64`	string	ไฟล์แบบ base64 หรือ data URL — ใช้กับ JSON
`file_url`	string (https)	ลิงก์ HTTPS ของไฟล์ — ใช้กับ JSON
`mode`	"text" \| "extract"	text = อ่านทั้งหน้า (Markdown), extract = ดึงข้อมูลเป็น JSON (ค่าเริ่มต้น text)
`template`	"auto" \| "invoice" \| "thai_id" \| "passport" \| "government_doc" \| "custom"	เทมเพลตสำหรับโหมด extract (ค่าเริ่มต้น auto)
`fields`	JSON array	ฟิลด์ที่ต้องการเมื่อ template = custom เช่น [{"name":"contract_no","description":"เลขที่สัญญา"}]

curl -X POST https://api.tnpaitech.com/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.jpg" \
  -F "mode=extract" \
  -F "template=invoice"

เทมเพลต

เอกสารใดๆauto

ดึงข้อมูลสำคัญทั้งหมดอัตโนมัติ

items

ใบกำกับภาษี / ใบเสร็จinvoice

ผู้ขาย ผู้ซื้อ รายการ VAT ยอดรวม

document_titledocument_numberissue_dateseller_nameseller_tax_idseller_branchseller_addressbuyer_namebuyer_tax_idbuyer_addressline_itemssubtotaldiscountvat_ratevat_amountwithholding_taxtotalcurrencypayment_terms

บัตรประชาชนthai_id

เลข 13 หลัก ชื่อ วันเกิด ที่อยู่

id_numberprefix_thfirst_name_thlast_name_thprefix_enfirst_name_enlast_name_endate_of_birthreligionaddressissue_dateexpiry_datelaser_code

หนังสือเดินทางpassport

MRZ เลขพาสปอร์ต สัญชาติ วันหมดอายุ

document_typeissuing_countrypassport_numbersurnamegiven_namesnationalitydate_of_birthsexplace_of_birthissue_dateexpiry_datepersonal_numbermrz_line1mrz_line2

หนังสือราชการgovernment_doc

เลขที่ วันที่ เรื่อง เรียน ผู้ลงนาม

letter_numberissuing_agencydatesubjectrecipientreferencesenclosuressummarysigner_namesigner_positioncontact

กำหนดเองcustom

ระบุฟิลด์ที่ต้องการเอง

ตัวอย่างผลลัพธ์

{
  "id": "ocr_3f9a1c0e2b7d4a5f6e8c9b10",
  "object": "ocr.result",
  "livemode": true,
  "mode": "extract",
  "template": "invoice",
  "pages": 1,
  "document_type": "Thai tax invoice / receipt",
  "fields": {
    "document_number": "INV-2026-0142",
    "issue_date": "2026-10-15",
    "seller_name": "บริษัท ตัวอย่าง จำกัด",
    "seller_tax_id": "0105555000000",
    "line_items": [
      {
        "description": "ค่าบริการ OCR",
        "quantity": 1,
        "unit_price": 1000,
        "amount": 1000
      }
    ],
    "vat_amount": 70,
    "total": 1070,
    "currency": "THB"
  },
  "warnings": [],
  "usage": {
    "credits_used": 1,
    "credits_remaining": 49,
    "latency_ms": 3120
  }
}

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

{ "error": { "code": "insufficient_credits", "message": "This request needs 3 credit(s)" },
  "request_id": "ocr_3f9a1c0e2b7d4a5f6e8c9b10" }

400	`invalid_request`	คำขอไม่ถูกต้อง
401	`unauthorized`	API key ไม่ถูกต้องหรือถูกยกเลิกแล้ว
402	`insufficient_credits`	เครดิตไม่พอ กรุณาเติมเครดิต
403	`account_suspended`	บัญชีนี้ถูกระงับการใช้งาน กรุณาติดต่อฝ่ายสนับสนุน
409	`idempotency_in_progress`	คำขอที่ใช้ Idempotency-Key นี้ยังประมวลผลอยู่ กรุณารอแล้วลองใหม่
413	`file_too_large`	ไฟล์ใหญ่เกินไป
413	`too_many_pages`	จำนวนหน้าเกินกำหนด
415	`unsupported_file`	รองรับเฉพาะ PNG, JPG, WEBP และ PDF
422	`idempotency_mismatch`	Idempotency-Key นี้ถูกใช้กับคำขออื่นไปแล้ว
429	`rate_limited`	ใช้งานถี่เกินไป กรุณาลองใหม่ภายหลัง
429	`demo_limit`	ครบจำนวนทดลองฟรีของวันนี้แล้ว สมัครฟรีเพื่อใช้งานต่อ
502	`ocr_failed`	อ่านเอกสารไม่สำเร็จ กรุณาลองใหม่
503	`not_configured`	ระบบยังไม่ได้ตั้งค่า (ติดต่อผู้ดูแลระบบ)

โหมดทดสอบ

สร้างคีย์ประเภท Test (tnp_test_…) ในหน้า API Keys เพื่อพัฒนาระบบโดยไม่เสียเครดิต ระบบจะตรวจไฟล์และพารามิเตอร์เหมือนจริง แต่คืนข้อมูลตัวอย่างและ livemode: false

Authorization: Bearer tnp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ส่งคำขอซ้ำอย่างปลอดภัย (Idempotency)

ใส่ header Idempotency-Key (ค่าที่ไม่ซ้ำ เช่น UUID) เมื่อ timeout หรือเน็ตหลุดให้ส่งคำขอเดิมพร้อม key เดิม ระบบจะคืนผลลัพธ์เดิมพร้อม header Idempotent-Replayed: true โดยไม่ตัดเครดิตซ้ำ ผลลัพธ์จะถูกเก็บไว้ 24 ชั่วโมงเฉพาะคำขอที่ส่ง key นี้ ถ้าใช้ key เดิมกับไฟล์อื่นจะได้ 422 และถ้าคำขอแรกยังทำงานอยู่จะได้ 409

curl -X POST https://api.tnpaitech.com/v1/ocr \
  -H "Authorization: Bearer $TNP_API_KEY" \
  -H "Idempotency-Key: 6f1c2a7e-4b8d-4f0a-9c3e-2d5b7a1e9f40" \
  -F "file=@invoice.pdf" -F "mode=extract" -F "template=invoice"

Rate limit และ Request ID

ทุก response มี header X-Request-Id ให้แจ้งค่านี้เมื่อติดต่อฝ่ายสนับสนุน และค้นหาได้ในหน้า Logs ส่วน X-RateLimit-Limit, X-RateLimit-Remaining และ X-RateLimit-Reset (unix seconds) บอกโควตาที่เหลือ เมื่อได้ 429 ให้รอตาม header Retry-After

HTTP/1.1 429 Too Many Requests
X-Request-Id: ocr_3f9a1c0e2b7d4a5f6e8c9b10
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793522940
Retry-After: 17

{ "error": { "code": "rate_limited", "message": "Limit is 60 requests per 60 seconds" },
  "request_id": "ocr_3f9a1c0e2b7d4a5f6e8c9b10" }

ข้อจำกัด

อัปโหลดไฟล์โดยตรงได้สูงสุด 4 MB (ใช้ file_url สำหรับไฟล์ใหญ่สูงสุด 20 MB)
PDF สูงสุด 30 หน้าต่อคำขอ
60 คำขอต่อนาทีต่อ API key (ดูยอดคงเหลือได้จาก header X-RateLimit-*)
1 เครดิตต่อหน้า คืนเครดิตอัตโนมัติเมื่ออ่านไม่สำเร็จ