Integrate DocIntel API

0ภาพรวม — API นี้ทำอะไร

DocIntel รับไฟล์เอกสาร (PDF/รูป) → OCR ภาษาไทย → สกัดข้อมูลเป็น JSON (เช่น เลขบัญชี, กำไร/ขาดทุน, วันหมดอายุบัตร) พร้อมตรวจความถูกต้องและปิดบัง PII. ออกแบบสำหรับเอกสารการเงิน/ราชการไทยโดยเฉพาะ.

Flow มาตรฐาน (2 ขั้น แยกกัน)

ประเภทเอกสารที่รองรับ (14)

ไม่รู้ประเภท? ไม่ต้องส่ง — ระบบจับเอง. ถ้าจับไม่ได้จะได้ unknown.

พื้นฐาน

1Authentication

ทุก request (ยกเว้น /api/v1/_meta) ต้องมี header Authorization: Bearer dci_live_xxxxx · key รับจากผู้ดูแลระบบ.

ทดสอบ key ใช้งานได้ไหม

Copy# เมตาดาต้า API (ไม่ต้อง auth)
curl https://docintel-demo.kiatdamrong.shop/api/v1/_meta

# ตรวจว่า key ใช้ได้ (ควรได้ 200)
curl https://docintel-demo.kiatdamrong.shop/api/v1/jobs \
  -H "Authorization: Bearer dci_live_xxxxx"

Copyconst API = 'https://docintel-demo.kiatdamrong.shop';
const KEY = 'dci_live_xxxxx';
const H = { 'Authorization': `Bearer ${KEY}` };

const jobs = await fetch(`${API}/api/v1/jobs`, { headers: H }).then(r => r.json());
console.log(jobs);

Copyimport requests
API = "https://docintel-demo.kiatdamrong.shop"
H = {"Authorization": "Bearer dci_live_xxxxx"}
print(requests.get(f"{API}/api/v1/jobs", headers=H).json())

2Preflight POST /api/v1/preflight

ตรวจ คุณภาพรูป + (ถ้าต้องการ) ยืนยันประเภทเอกสาร โดย ไม่ต้อง OCR — ตอบ sync ~0.2s. ใช้กรองรูปก่อนเก็บ/ก่อนส่ง Extract.

Request (multipart/form-data)

ตัวอย่าง — แนะนำให้ส่ง expected_doc_type

Copycurl -X POST https://docintel-demo.kiatdamrong.shop/api/v1/preflight \
  -H "Authorization: Bearer dci_live_xxxxx" \
  -F "[email protected]" \
  -F "expected_doc_type=boj5"

Copyconst fd = new FormData();
fd.append('file', fileInput.files[0]);
fd.append('expected_doc_type', 'boj5');

const r = await fetch(`${API}/api/v1/preflight`, {
  method: 'POST', headers: H, body: fd
}).then(r => r.json());

if (r.next_action === 'proceed') { /* เก็บรูป */ }
else if (r.next_action === 'review') { /* เตือน: ดูเหมือน r.detected */ }
else { /* retry_with_better_image */ }

Copyr = requests.post(f"{API}/api/v1/preflight", headers=H,
    files={"file": open("slip.jpg", "rb")},
    data={"expected_doc_type": "boj5"}).json()
print(r["next_action"], r["detected"], r["doc_type_match"])

Response

next_action — Preflight รายงาน, ระบบคุณตัดสินใจ

3Extract POST /api/v1/extract

สแกน + สกัดข้อมูลเต็ม (OCR). เป็น async — คืน job_id ทันที (สถานะ 202) แล้วประมวลผลเบื้องหลัง. ดูผลด้วยขั้น 4.

Request (multipart/form-data)

Headers พิเศษ

Copycurl -X POST https://docintel-demo.kiatdamrong.shop/api/v1/extract \
  -H "Authorization: Bearer dci_live_xxxxx" \
  -F "[email protected]" \
  -F "external_id=loan-2024-00123" \
  -F "applicant_id=usr_8f3a1c" \
  -F 'tags=["loan","urgent"]'
# → { "job_id": "...", "status": "queued", "poll_url": "/api/v1/jobs/..." }

Copyconst fd = new FormData();
fd.append('file', fileInput.files[0]);
fd.append('external_id', 'loan-2024-00123');
fd.append('applicant_id', 'usr_8f3a1c');

const { job_id, poll_url } = await fetch(`${API}/api/v1/extract`, {
  method: 'POST', headers: H, body: fd
}).then(r => r.json());

Copyr = requests.post(f"{API}/api/v1/extract", headers=H,
    files={"file": open("statement.pdf", "rb")},
    data={"external_id": "loan-2024-00123",
          "applicant_id": "usr_8f3a1c"}).json()
job_id = r["job_id"]

4รับผลลัพธ์ GET /api/v1/jobs/{job_id}

Extract คืน job_id — poll endpoint นี้จนสถานะเป็น done.

สถานะงาน

โครงสร้าง response (เมื่อ done)

Poll จนเสร็จ

Copycurl https://docintel-demo.kiatdamrong.shop/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer dci_live_xxxxx"

Copyasync function waitJob(id) {
  while (true) {
    const j = await fetch(`${API}/api/v1/jobs/${id}`, { headers: H }).then(r => r.json());
    if (j.status === 'done') return j;
    if (j.status === 'failed' || j.status === 'error') throw j;
    await new Promise(res => setTimeout(res, 2000)); // รอ 2s
  }
}

Copyimport time
def wait_job(job_id):
    while True:
        j = requests.get(f"{API}/api/v1/jobs/{job_id}", headers=H).json()
        if j["status"] == "done": return j
        if j["status"] in ("failed", "error"): raise Exception(j)
        time.sleep(2)

ไฟล์เดียวที่มีหลายเอกสาร (composite)

sections = job["classification"].get("composite_sections") or []
for s in sections:
    print(s["doc_type"], s["start_page"], "-", s["end_page"], s["extraction"])

อยากได้เฉพาะฟิลด์ที่สกัด → GET /api/v1/jobs/{id}/extraction · รูปหน้าเอกสาร → /jobs/{id}/pages/{n}/image · ข้อความ OCR → /pages/{n}/text

เมื่อระบบไม่มั่นใจ — สัญญาณที่ต้องอ่านก่อนนำค่าไปใช้

แนวทางตรวจทานฝั่งคุณ: ดึงรูปหน้าเอกสาร GET /api/v1/jobs/{id}/pages/{n}/image มาแสดงคู่กับค่าที่สกัดได้ ให้เจ้าหน้าที่เทียบกับต้นฉบับ แล้วแจ้งผลกลับด้วย endpoint ด้านล่าง — ทั้งสองฝั่งจะได้เห็นภาพตรงกันว่าเอกสารใดผ่านการยืนยันแล้ว

ส่งผลตรวจกลับ POST /api/v1/jobs/{job_id}/review

ปิดลูปการตรวจทาน: เจ้าหน้าที่ของคุณตรวจแล้ว แจ้งผลกลับมาให้ระบบบันทึกไว้ ผลล่าสุดจะแสดงใน GET /jobs/{id} field review (หรือขอเฉพาะส่วนนี้ด้วย ?fields=review)

Copycurl -X POST https://docintel-demo.kiatdamrong.shop/api/v1/jobs/JOB_ID/review   -H "Authorization: Bearer dci_live_xxxxx"   -H "Content-Type: application/json"   -d '{"verified": false, "corrected_doc_type": "bookbank",
       "corrected_fields": {"account_no": "123-4-56789-0"},
       "note": "เจ้าหน้าที่ตรวจกับต้นฉบับแล้ว"}'

Copyawait fetch(`${API}/api/v1/jobs/${jobId}/review`, {
  method: 'POST',
  headers: { ...H, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    verified: false,
    corrected_doc_type: 'bookbank',
    corrected_fields: { account_no: '123-4-56789-0' },
    note: 'เจ้าหน้าที่ตรวจกับต้นฉบับแล้ว',
  }),
});

Copyrequests.post(f"{API}/api/v1/jobs/{job_id}/review", headers=H, json={
    "verified": False,
    "corrected_doc_type": "bookbank",
    "corrected_fields": {"account_no": "123-4-56789-0"},
    "note": "เจ้าหน้าที่ตรวจกับต้นฉบับแล้ว",
})

ส่งซ้ำได้ (ระบบเก็บเป็นประวัติ · แสดงรายการล่าสุด) · ใช้ได้เฉพาะงานสถานะ done (ไม่เช่นนั้นได้ 409) · การส่งผลตรวจถูกบันทึกใน audit log ตามแนวทาง PDPA เช่นเดียวกับการเข้าถึงข้อมูล

5Webhooks — รับผลแบบไม่ต้อง poll

ลงทะเบียน URL (HTTPS) เพื่อให้ระบบยิงกลับเมื่องานเสร็จ — แทนการ poll.

สร้าง POST /api/v1/webhooks

Copycurl -X POST https://docintel-demo.kiatdamrong.shop/api/v1/webhooks \
  -H "Authorization: Bearer dci_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourapp.com/hook","events":["extract.done","extract.failed"]}'

Events ที่รองรับ

Headers ที่ระบบส่งมา

Payload (body ที่ส่งมา)

Copy{
  "event_type": "extract.done",
  "job_id": "da78be19-b693-...",
  "tenant": "your-tenant",
  "status": "done",
  "filename": "statement.pdf",
  "applicant_id": "usr_8f3a1c",
  "duration_s": 12.34,
  "completed_at": 1720000000,
  "doc_type": "boj5",          // เฉพาะ extract.done
  "classify_confidence": 0.94,
  "needs_review": false,        // true = มีสัญญาณไม่มั่นใจ → ส่งเข้าคิวคนตรวจ
  "review_reasons": []           // เหตุผล (ว่าง = ไม่มีสัญญาณ)
  // extract.failed จะมี "error": "..." แทน
}

review_reasons ที่เป็นไปได้: doc_type_unknown · low_classify_confidence · suspected_hallucination · extraction_warnings · validation_failed · fields_withheld (เพิ่ม 26/8 — ระบบกักค่าที่อ่านไม่ได้จริงไว้ใน extraction._rejected แทนที่จะเดา · เปิดดูรายชื่อ field และเหตุผลได้ในนั้น) — ความหมายแต่ละตัวตรงกับหัวข้อ "เมื่อระบบไม่มั่นใจ" ในข้อ 4 ระบบคุณใช้ needs_review ตัดสินใจได้ทันทีจาก webhook โดยไม่ต้องดึงผลเต็มก่อน

Verify signature

Copyimport hmac, hashlib

def verify(secret, sig_header, raw_body):
    p = dict(x.split("=", 1) for x in sig_header.split(","))
    signed = f'{p["t"]}.{raw_body}'.encode()
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p["v1"])
# raw_body = ตัว body ดิบ (ห้าม re-serialize ก่อน verify)

Copyconst crypto = require('crypto');
function verify(secret, sigHeader, rawBody) {
  const p = Object.fromEntries(sigHeader.split(',').map(x => x.split('=')));
  const signed = `${p.t}.${rawBody}`;
  const exp = crypto.createHmac('sha256', secret).update(signed).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(exp), Buffer.from(p.v1));
}

หมุน secret: /webhooks/{id}/rotate-secret · จัดการ: GET /webhooks · /webhooks/{id}/disable · /delete

6เพิ่มเติม — Compare · Writer · Delete

เปรียบเทียบงบ (YoY) POST /api/v1/compare · scope: jobs

ส่งหลาย job_id ของงบต่างปี → ได้ผลต่างทีละฟิลด์ + เทียบ trend/อัตราส่วน. หรือเทียบเอกสารของ applicant คนเดียวผ่าน /applicants/{id}/compare.

AI Writer POST /api/v1/improve-objective · scope: writer

ตัวช่วย เจน/เรียบเรียงข้อความภาษาไทย ให้เป็นทางการขึ้น ตามอินพุตที่ frontend กำหนด. ไม่เกี่ยวกับเอกสารที่สแกน — ไม่ได้ดึงข้อมูลจาก extract. ระบบจะไม่แต่งข้อเท็จจริงใหม่ (ปรับภาษา/โครงสร้างเท่านั้น).

Request (JSON body):

Copycurl -X POST https://docintel-demo.kiatdamrong.shop/api/v1/improve-objective \
  -H "Authorization: Bearer dci_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": "โครงการนี้จะช่วยเกษตรกรในชุมชนให้ดีขึ้น",
    "keywords": ["ความยั่งยืน","รายได้","เทคโนโลยี"],
    "project_context": "ทุนพัฒนาชุมชนเกษตร"
  }'
# → { "improved": "...", "original_length": .., "improved_length": .., "_model": ".." }

Copyr = requests.post(f"{API}/api/v1/improve-objective", headers=H, json={
    "draft": "โครงการนี้จะช่วยเกษตรกรในชุมชนให้ดีขึ้น",
    "keywords": ["ความยั่งยืน", "รายได้", "เทคโนโลยี"],
}).json()
print(r["improved"])

Response: improved · original_length · improved_length · _model · _tokens · _duration_ms

เพิ่มใหม่ 25/8 — Writer อีก 2 หัวข้อ · request body / response / error เหมือน improve-objective ทุกฟิลด์ (คีย์ scope writer เดิมใช้ได้เลย) ต่างแค่ URL ตามช่องในฟอร์ม:

response ของ 2 เส้นใหม่เพิ่มฟิลด์ field_type (expected_results / problem_background) บอกว่าหัวข้อไหนตอบ · ตัวอย่างผลจริง + รายละเอียดเต็มอยู่ในคู่มือ AI Writer หัวข้อ 8

PDPA · ลบข้อมูล DELETE /api/v1/jobs/{job_id}

ลบงานและข้อมูลที่เกี่ยวข้องถาวร (ตามสิทธิ PDPA ของเจ้าของข้อมูล).

ค้นหา / ไทม์ไลน์ applicant

/applicants/search · /applicants/{id}/timeline · /applicants/{id}/documents · ค่าใช้จ่าย /cost-summary

Δอัปเดต 6/9/2569 — สิ่งที่เปลี่ยนในคำตอบ

1 · เลขที่ต้องเป็น 13 หลัก จะส่งตามที่พิมพ์ในเอกสาร พร้อมคำเตือน (นโยบายใหม่)

ใช้กับ trade_reg.registration_number · full_fs.company.tax_id · pnd50.tax_id · boj5.company_tid — ระบบไม่ตัดสินแทนว่าเลขถูกหรือผิด แต่บอกว่าอ่านได้กี่หลัก ขาดหรือเกิน แล้วให้ผู้ใช้ตรวจกับต้นทาง

2 · key ใหม่ในคำตอบ

needs_review / review_reasons ใน GET (เดิมเฉพาะ webhook) · extraction._fill · pages[].ocr_retry · pages[].ocr_engine_fallback · pages[].text_source = "ocr_structure_retry" · เหตุผล review ใหม่ ocr_runaway ocr_sparse ocr_engine_fallback ocr_cloud_fallback extraction_warnings fields_withheld — รายละเอียดในหัวข้อ 4 "สัญญาณที่ต้องอ่าน"

3 · ชื่อเอนจิน

model_used · pages[].ocr_model · extraction._model เป็นชื่อกลาง (เช่น "AI Gateway OCR") — อย่าผูกโค้ดกับค่าเหล่านี้

4 · พฤติกรรมที่เปลี่ยน

• ฟิลด์ที่เคยเป็น null จะมีค่ามากขึ้น (จาก _fill และจากข้อ 1) — ทุกกรณีมี _fill หรือ _warnings กำกับ
• OCR อ่านเอกสารเดิมได้ข้อความเดิมทุกครั้ง (ถอดรหัสแบบไม่สุ่ม) — การส่งซ้ำไม่ทำให้ผลเปลี่ยน
• ไฟล์เดิม (hash เดิม) ใน tenant เดิมยังได้ 200 พร้อมผลเก่าแทน 202 เหมือนเดิม
• trade_reg.issuing_office ตอบชื่อสำนักงานจริง (เช่น เทศบาลตำบลปะโค) ไม่ใช่ป้าย "สำนักงานทะเบียนพาณิชย์"

7Error handling

{
  "error": {
    "code":       "external_id_conflict",   // token คงที่ snake_case — ใช้ switch/case
    "message":    "external_id 'x' already used within 90-day window",
    "status":     409,                      // = HTTP status
    "details":    { "existing_job_id": "...", "hint": "..." },   // หรือ null
    "request_id": "cid_4df968c8d21e"        // ส่งให้เราเวลาแจ้งปัญหา
  },
  "detail": ...                             // legacy · จะเลิกใช้ในอนาคต
}

422 validation จะมี details.fields[] บอกชื่อ field ที่ผิดทีละตัว: {"field": "applicant_id", "message": "Field required", "type": "missing"}

แคตตาล็อก error.code

กติกา: code ที่เป็น token เฉพาะจะคงที่ตลอด (ผูก logic ได้) · ถ้าไม่มี token เฉพาะจะได้ code กลางตาม status (bad_request / unauthorized / not_found / conflict / validation_error / rate_limited / internal_error ฯลฯ) และ message อธิบายเป็นข้อความเสมอ

ตาราง HTTP status

8Tools