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

หน้านี้พาคุณจากบัญชีเปล่าไปจนถึงเอกสารที่เสร็จสมบูรณ์ซึ่งสร้างด้วยโค้ดของคุณเอง: บัญชี เทมเพลต คีย์ และคำขอ HTTP หนึ่งครั้ง ทุกฟิลด์ คำตอบ และข้อผิดพลาดอธิบายไว้ในข้อมูลอ้างอิง API เอกสาร

API เอกสารใช้ได้กับทุกแผน รวมถึงแผน Free เอกสารแต่ละฉบับที่ API สร้างคือเอกสารอัตโนมัติ: ในแผน Pro ไม่มีขีดจำกัด มิฉะนั้นจะหักจากเอกสารอัตโนมัติของที่นั่ง Business (20,000 ฉบับต่อปีต่อที่นั่ง) จากนั้นจากโควตาฟรีรายเดือน แล้วจึงจากแพ็กเอกสารของคุณ เอกสารจะถูกนับเมื่อเสร็จสมบูรณ์ เอกสารที่ล้มเหลวจึงไม่มีค่าใช้จ่าย ในแผน Free เอกสารจะมีบรรทัดท้ายกระดาษ “Generated with AutomaDoc” เว้นแต่บริษัทของคุณมีแพ็กที่ซื้อไว้ ดูแผน ที่นั่ง และแพ็กเอกสาร

1. บัญชี

ทุกบัญชี AutomaDoc เรียกใช้ API ได้: องค์กร Microsoft 365 โดเมน Google Workspace เวิร์กสเปซ Lark หรือบัญชีอีเมล หากคุณต้องการเพียง API ให้สมัครด้วยที่อยู่อีเมล ดูบัญชีสำหรับ API เท่านั้น

ขั้นตอนที่ 2 และ 3 ทำในพอร์ทัลบริษัทที่ company.automadoc.cc และต้องทำโดยผู้ดูแลระบบของบัญชีคุณ (ในเวิร์กสเปซ Lark คือผู้ดูแลแอปของ Lark)

2. เทมเพลตและ ID ของเทมเพลต

เทมเพลตคือไฟล์ Word, Excel หรือ PowerPoint ที่มีตัวแทนค่าในตำแหน่งที่ข้อมูลของคุณจะไปอยู่ สำหรับหน้านี้ ให้ใช้ใบแจ้งหนี้ Word ที่มี:

{Invoice_No} และ {Customer} ในข้อความ
แถวตารางที่เซลล์แรกขึ้นต้นด้วย {#Items}{Product} ตามด้วย {Qty} และเซลล์สุดท้ายลงท้ายด้วย {Price}{/Items}: แถวนี้จะทำซ้ำหนึ่งครั้งต่อรายการ
{Total | currency:"USD"} ใต้ตาราง

ไวยากรณ์ทั้งหมดอยู่ในไวยากรณ์เทมเพลต

วิธีเพิ่มเทมเพลตในพอร์ทัลบริษัท:

เปิด เทมเพลต แล้วคลิก เทมเพลต API ใหม่
พิมพ์ชื่อแล้วคลิก สร้างเทมเพลต API
เปิดเมนูที่ท้ายแถวของเทมเพลตแล้วเลือก อัปโหลดไฟล์ ไฟล์จะถูกตรวจสอบตอนอัปโหลด หากมีปัญหา หน้าเว็บจะแจ้งให้ทราบ แล้วคุณจึงอัปโหลดไฟล์ที่แก้ไขแล้ว
ในเมนูเดียวกัน เลือก คัดลอก ID เทมเพลต

API เติมข้อมูลลงเทมเพลตใดก็ได้ของบริษัทคุณ ไม่ใช่เฉพาะเทมเพลต API: เทมเพลตที่สร้างในส่วนเสริม Excel จาก Google Sheet หรือในส่วนขยาย Lark Base ก็ทำงานแบบเดียวกัน และแถวของเทมเพลตนั้นในหน้า เทมเพลต ก็มี คัดลอก ID เทมเพลต เช่นกัน เมื่อคุณเข้าสู่ระบบพอร์ทัลด้วย Lark ให้สร้างเทมเพลตในส่วนขยาย Base การ์ด API เอกสาร ในแท็บ เทมเพลต ของส่วนขยายจะแสดงปลายทางพร้อม ID ด้วย

3. คีย์ API ของบริษัท

ในพอร์ทัลบริษัท เปิด บริษัท → คีย์ API แล้วคลิก คีย์ API ใหม่
กรอก ชื่อคีย์ เป็นชื่อระบบที่จะใช้คีย์นี้ เช่น ERP แล้วคลิก สร้างคีย์
คัดลอกคีย์ คีย์ขึ้นต้นด้วย amk_ และแสดงเพียงครั้งเดียว

คีย์ของบริษัทเปิดได้ทุกเทมเพลตของบริษัทคุณ จึงควรเก็บรักษาเหมือนรหัสผ่าน เพิกถอน ในหน้าเดียวกันจะหยุดใช้คีย์ได้ทันที

เทมเพลตของ Lark Base ยังมีคีย์ของตัวเองบนการ์ด API เอกสาร ซึ่งเปิดได้เฉพาะเทมเพลตนั้น

4. ส่งคำขอแรก

ส่งข้อมูลของเทมเพลตเป็น JSON ไปยัง POST /api/v1/templates/{templateId}/documents โดยใส่คีย์ในเฮดเดอร์ X-Webhook-API-Key:

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice_No": "INV-2026-001",
      "Customer": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

data คือระเบียน แต่ละคีย์เติมตัวแทนค่าที่มีชื่อเดียวกัน ช่องว่าง จุด และสัญลักษณ์อื่นในคีย์จะกลายเป็น _ ดังนั้น "Invoice No." จะเติม {Invoice_No_} และตัวพิมพ์เล็กใหญ่มีผล
format ไม่บังคับ: "pdf", "png" (หน้าแรกเป็นรูปภาพ) หรือ "native" (ไฟล์ประเภทเดียวกับเทมเพลต) หากไม่ระบุ จะใช้การตั้งค่าของเทมเพลต
?wait=20 จะรอคำตอบได้นานถึง 20 วินาที (สูงสุด 25) ระหว่างที่สร้างเอกสาร คำขอเดียวจึงมักเพียงพอ

filename, recordId และ mode ก็ไม่บังคับเช่นกัน ดูสร้างเอกสาร

5. อ่านคำตอบและรับไฟล์

เมื่อเอกสารเสร็จภายในเวลาที่รอ คำตอบจะเป็น 200 OK:

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "completed",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000,
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

เมื่อเอกสารยังสร้างไม่เสร็จ คำตอบจะเป็น 202 Accepted พร้อม "status": "processing" และยังไม่มีลิงก์ ให้อ่าน statusUrl ด้วยคีย์เดียวกันทุก ๆ ไม่กี่วินาที (สูงสุด 60 ครั้งต่อนาทีต่อเอกสาร) จนกว่า status จะเป็น completed หรือ failed:

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

completed: downloadUrl เปิดไฟล์ได้โดยไม่ต้องใช้คีย์ ใช้ได้ตราบเท่าที่บริษัทของคุณเก็บเอกสารที่สร้างไว้ และการอ่านสถานะแต่ละครั้งจะให้ลิงก์ใหม่
failed: error บอกเหตุผล เช่น ลูปที่ไม่ได้ปิด
warnings หากมี จะแสดงสิ่งที่ถูกข้ามไป เช่น รูปภาพที่ดึงจาก URL ไม่ได้ หรือตัวแทนค่าที่ข้อมูลของคุณไม่มีค่า

หากต้องการรับตัวไฟล์ด้วยคีย์แทนลิงก์:

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

เมื่อคำขอถูกปฏิเสธ

การปฏิเสธทุกครั้งมี code และ error ภาษาอังกฤษ รายการที่คุณจะพบก่อน:

สถานะ	`code`	สิ่งที่ต้องทำ
401	`API_KEY_MISSING`	เพิ่มเฮดเดอร์ `X-Webhook-API-Key`
403	`API_KEY_INVALID`	ตรวจสอบคีย์และ ID ของเทมเพลต: ID ที่ผิดก็ได้คำตอบนี้เช่นกัน
409	`TEMPLATE_FILE_MISSING`	อัปโหลดไฟล์ของเทมเพลต
400	`TEMPLATE_VALIDATION_ERRORS`	แก้ไขไฟล์เทมเพลต `validationErrors` แสดงรายการปัญหา
403	`QUOTA_EXCEEDED`	ไม่มีเอกสารเหลือในเดือนนี้ ให้ซื้อแพ็กหรือที่นั่ง
429	`RATE_LIMITED`	เกิน 60 คำขอต่อนาทีสำหรับเทมเพลตเดียว หรือ 600 เอกสารต่อนาทีสำหรับบริษัทของคุณ ให้รอแล้วลองอีกครั้ง

รายการทั้งหมดอยู่ในข้อผิดพลาด

ตัวอย่างเดียวกันใน Node.js

Node.js 18 ขึ้นไปมี fetch ในตัว บันทึกโค้ดนี้เป็น quickstart.mjs แล้วรันด้วย AUTOMADOC_KEY=amk_… node quickstart.mjs:

import { writeFile } from 'node:fs/promises'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY
const TEMPLATE_ID = 'TEMPLATE_ID'

async function makeDocument(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers: { 'X-Webhook-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

ขั้นตอนถัดไป

ลูป รายการของอ็อบเจ็กต์จะเติมลูป {#Items}…{/Items} หนึ่งแถวหรือหนึ่งบล็อกต่ออ็อบเจ็กต์ ลูปกรอง เรียงลำดับ และจำกัดจำนวนแถวได้ ดูลูป
รูปภาพ ตั้งข้อความแสดงแทน (Alt Text) ของรูปภาพในเทมเพลตเป็น {Logo} แล้วส่ง "Logo": "https://…" URL ต้องเป็นที่อยู่ http(s) สาธารณะ ส่วนในตำแหน่งอื่นของเทมเพลต URL เป็นเพียงข้อความ ดูรูปภาพแบบไดนามิก และข้อมูลของคุณเติมเทมเพลตอย่างไร
PDF รูปภาพ หรือไฟล์ Office "format" เลือกผลลัพธ์ได้ในแต่ละคำขอ หากไม่ระบุจะใช้การตั้งค่าของเทมเพลต
หลายเอกสารในคำขอเดียว ส่ง data เป็นรายการอ็อบเจ็กต์สูงสุด 50 รายการ เพื่อรับเอกสารหนึ่งฉบับต่อรายการ ดูหลายเอกสารในคำขอเดียว
เอกสารเดียวจากหลายระเบียน เทมเพลตที่ตั้งค่าให้สร้างรายการ หนึ่งหน้าต่อระเบียน หรือฉลาก จะเปลี่ยนรายการสูงสุด 500 รายการให้เป็นเอกสารฉบับเดียว และนับเป็นหนึ่งฉบับ ดูเอกสารเดียวจากหลายระเบียน และเอกสารฉบับเดียวจากทุกรายการ
ลายเซ็นอิเล็กทรอนิกส์ สำหรับเทมเพลตของ Lark Base ที่มีช่องลายเซ็น บล็อก sign จะส่งเอกสารไปให้ลงนามทันทีที่สร้างเสร็จ ดูส่งเอกสารให้ลงนาม
ไม่ต้องเขียนโค้ดเลย ใน Microsoft 365 ตัวเชื่อมต่อ Power Automate ส่งคำขอเดียวกันนี้จากโฟลว์ได้