การวางช่องอัตโนมัติ

การวางช่องด้วยตนเองเหมาะกับเอกสารฉบับเดียว แต่สำหรับสัญญาที่คุณส่งทุกสัปดาห์ หรือเอกสารที่ AutomaDoc สร้าง ให้เขียน แท็ก ลงในเอกสารแทน เช่น [[sign:Client]] ตรงที่ลูกค้าลงนาม และ [[date:Client]] ตรงที่ต้องใส่วันที่ เมื่อจัดเตรียม เอกสาร AutomaDoc จะค้นหาแท็กแต่ละตัวและวางช่องไว้ตรงนั้น ผู้เรียกใช้ API ที่แก้ไขเอกสารไม่ได้สามารถใช้จุดยึด (anchor) ซึ่งเป็นช่องที่วางโดยอ้างอิงตำแหน่งจากข้อความที่มีอยู่ในเอกสารแล้ว

แท็กข้อความ

ตัวอย่างใน Word

พิมพ์แท็กเป็นข้อความธรรมดาในตำแหน่งที่ต้องการวางช่อง

Signed for the client:

[[sign:Client]]

Name: [[name:Client]]          Date: [[date:Client]]
Company: [[company:Client]]
Purchase order: [[text:Client:PO number;optional]]

[[check:Client:Terms]] I have read and accept the terms.

Signed for the supplier:

[[sign:Supplier;w=180;h=50]]
Initials on every page: [[initials:Supplier]]

เมื่อคุณเพิ่มเอกสารนี้ในคำขอ เอกสารจะมีสล็อตสองสล็อต คือ Client และ Supplier มอบแต่ละสล็อตให้ผู้รับหนึ่งคน แล้วทุกช่องของบทบาทนั้นจะเป็นของบุคคลนั้น หากใช้ API ให้ตั้ง autoTags: true และกำหนด slot ให้ผู้รับแต่ละคน

แท็กทำงานเหมือนกันในไฟล์ PDF, Word, Excel หรือ PowerPoint และในเทมเพลต AutomaDoc การสร้างเอกสารจะไม่แตะต้อง วงเล็บเหลี่ยม เอกสารที่สร้างจากเทมเพลตที่มีแท็กจึงเข้ามาในคำขอพร้อมช่องที่พร้อมวาง นี่คือเหตุผลที่แท็กใช้ [[ ]] ไม่ใช่ { } ของตัวแทนค่าในเทมเพลต

ไวยากรณ์

[[ kind : role ]]
[[ kind : role : label ]]
[[ kind : role ; option ; option ]]
[[ kind : role : label ; option ]]

ประเภท (kind ตัวพิมพ์ใหญ่หรือเล็กก็ได้) บอกว่าช่องเป็นช่องอะไร

ประเภท	เขียนแบบอื่นได้	ช่อง
`sign`	`signature`	ลายเซ็น
`initials`	`initial`	อักษรย่อ
`name`		ชื่อ
`date`		วันที่ลงนาม (เติมอัตโนมัติ)
`text`		ข้อความ
`check`	`checkbox`	ช่องทำเครื่องหมาย
`company`		บริษัท
`email`		อีเมล

บทบาท (role) คือสล็อตที่ช่องนั้นสังกัด ประกอบด้วยตัวอักษร ตัวเลข เครื่องหมายกำกับเสียง หรือขีดล่าง 1 ถึง 60 ตัว ในอักษรใดก็ได้ (Client, Witness_1, 客户) ห้ามมีช่องว่าง ตัวพิมพ์ใหญ่เล็กมีผล Client และ client เป็นสองสล็อต ต่างกัน เครื่องหมาย # ตามด้วยตัวเลขหลังบทบาทสงวนไว้สำหรับ AutomaDoc ใช้เอง

ป้ายกำกับ (label) ไม่บังคับ ยาว 1 ถึง 100 ตัวอักษร แสดงให้ผู้ลงนามเห็นเป็นชื่อช่อง เช่น [[text:Client:PO number]] ห้ามมี [, ], ; หรือ :

ตัวเลือก (option) แต่ละตัวอยู่หลัง ; ตัวพิมพ์ใหญ่หรือเล็กก็ได้

ตัวเลือก	ความหมาย
`w=180`	ความกว้างเป็นพอยต์ (1 พอยต์เท่ากับ 1/72 นิ้ว) ตั้งแต่ 8 ถึง 1000 ทศนิยมได้ไม่เกินสองตำแหน่ง
`h=50`	ความสูงเป็นพอยต์ ตั้งแต่ 8 ถึง 1000
`optional`	ผู้ลงนามเว้นช่องว่างไว้ได้
`required`	ผู้ลงนามต้องกรอก (ค่าเริ่มต้น)

เว้นวรรคและขึ้นบรรทัดใหม่รอบแต่ละส่วนได้ [[ sign : Client ]] จึงใช้ได้ และแท็กที่ขึ้นบรรทัดที่สองระหว่างสองส่วนของแท็ก ก็ใช้ได้เช่นกัน แต่การขึ้นบรรทัดใหม่กลางคำ (เช่น กลางคำว่า Client) จะทำให้แท็กใช้ไม่ได้

แท็กยาวได้ไม่เกิน 200 ตัวอักษร นับจาก [[ ถึง ]] หากยาวกว่านั้น หรือไม่มี ]] ปิด จะถือเป็นข้อความธรรมดาและถูกข้ามไป

ตำแหน่งที่ช่องจะไปอยู่

มุมซ้ายบนของช่องคือมุมซ้ายบนของแท็ก ขนาดของช่องคือ w และ h ของแท็ก หรือขนาดเริ่มต้นของช่องในกรณีอื่น (เป็นพอยต์: ลายเซ็น 160 × 48 อักษรย่อ 64 × 40 ช่องทำเครื่องหมาย 14 × 14 อีเมล 180 × 20 วันที่ 110 × 20 ช่องข้อความอื่น ๆ 160 × 20) หากไม่มี h ช่องจะไม่เตี้ยกว่าข้อความของแท็ก ช่องที่จะล้นออกนอกหน้าจะถูกย้ายกลับเข้ามาในหน้า

ดังนั้นให้เว้นที่ว่างไว้ทางขวาและด้านล่างของแต่ละแท็ก ช่องลายเซ็นจะยื่นลงไป 48 พอยต์ (ประมาณ 1.7 ซม.) จากขอบบน ของแท็ก

เมื่อมีข้อผิดพลาด

[[…]] ที่ไม่เป็นไปตามไวยากรณ์จะไม่ถูกเดา แต่จะคงอยู่บนหน้าเป็นข้อความ ไม่มีการสร้างช่อง และผู้ส่งจะได้รับคำเตือน พร้อมแท็กตามที่เขียนไว้ (50 รายการแรกต่อเอกสาร) สาเหตุที่พบบ่อยคือ ไม่มีบทบาท มีช่องว่างในบทบาท ประเภทหรือตัวเลือก ที่ไม่รู้จัก หรือขนาดที่ไม่อยู่ในช่วง 8 ถึง 1000

ขีดจำกัดอื่น ๆ

อ่านแท็กได้ไม่เกิน 500 แท็กต่อหน้า และ 500 แท็กต่อเอกสาร แท็กที่เกินจะถูกข้ามพร้อมคำเตือน
ค้นหาเฉพาะข้อความที่มีอยู่จริงใน PDF หน้าที่สแกนมาเป็นรูปภาพ จึงหาแท็กในนั้นไม่พบ
แท็กที่บทบาทไม่ได้มอบให้ผู้รับคนใดจะไม่สร้างช่อง หากผู้ลงนามคนใดไม่มีช่องเลย จะส่งคำขอไม่ได้

การใช้แท็กอีกครั้งจะแทนที่ช่องที่สร้างจากแท็ก ส่วนช่องที่คุณวางเองจะยังอยู่

จุดยึดจาก API

จุดยึดวางช่องโดยอ้างอิงตำแหน่งจากข้อความที่มีอยู่ในเอกสารแล้ว เช่น “Client signature:” ใช้สำหรับเอกสารที่คุณแก้ไข ไม่ได้ จุดยึดเป็นส่วนหนึ่งของ POST /api/v1/envelopes (ดู API คำขอลงนาม) ในตัวอย่างนี้ คำขอส่งเป็น multipart/form-data โดย JSON นี้อยู่ในส่วนชื่อ envelope และ PDF อยู่ในส่วนชื่อ contract

{
  "title": "Service agreement",
  "documents": [{ "file": "contract" }],
  "recipients": [
    { "key": "client", "role": "signer", "name": "Ana Lim", "email": "ana@example.com" }
  ],
  "anchors": [
    { "anchor": "Client signature:", "recipient": "client", "type": "signature", "offsetY": 14 },
    { "anchor": "Date:", "occurrence": 2, "recipient": "client", "type": "date_signed", "offsetX": 30, "offsetY": -2 }
  ],
  "send": true
}

คุณสมบัติ
`anchor`	ข้อความที่จะค้นหา 1 ถึง 200 ตัวอักษร จำเป็น
`recipient`	`key` ของผู้รับในคำขอเดียวกัน จำเป็น
`type`	`signature`, `initials`, `name`, `date_signed`, `text`, `checkbox`, `company` หรือ `email` จำเป็น
`occurrence`	`"all"` (ค่าเริ่มต้น) หรือตัวเลข คือรายการที่ตรงกันลำดับที่ 1, 2… ทั่วทั้งคำขอ
`offsetX`, `offsetY`	ระยะเป็นพอยต์จากมุมซ้ายบนของข้อความที่ตรงกัน ตั้งแต่ -2000 ถึง 2000 ค่าบวกไปทางขวาและลงล่าง ค่าเริ่มต้น 0
`w`, `h`	ขนาดเป็นพอยต์ ตั้งแต่ 8 ถึง 1000 ค่าเริ่มต้นคือขนาดของประเภทช่องนั้น
`required`	ค่าเริ่มต้น `true`
`label`	แสดงให้ผู้ลงนามเห็นเป็นชื่อช่อง

คำขอหนึ่งรายการมีจุดยึดได้สูงสุด 50 รายการ

วิธีจับคู่ข้อความ

ตรงทุกตัวอักษรและแยกตัวพิมพ์ใหญ่เล็ก: Signature: ไม่ตรงกับ signature: หรือ Signature
ช่องว่าง แท็บ หรือการขึ้นบรรทัดใหม่ที่ต่อกันกี่ตัวก็ได้ในจุดยึด จะตรงกับช่องว่างต่อเนื่องในเอกสารกี่ตัวก็ได้ เพราะข้อความใน PDF ไม่ได้เก็บการเว้นวรรคไว้อย่างแม่นยำ ช่องว่างที่ต้นหรือท้ายจุดยึดจะถูกละเว้น
รายการที่ตรงกันจะไม่ซ้อนทับกัน
นับลำดับรายการที่ตรงกันทั่วทั้งคำขอตามลำดับการอ่าน: เอกสารตามลำดับ แล้วทีละหน้า จากบนลงล่าง จากซ้ายไปขวา "occurrence": 2 คือรายการที่ตรงกันลำดับที่สองไม่ว่าจะอยู่ที่ใดในคำขอ ไม่ใช่ลำดับที่สองของแต่ละหน้า
ตรงกันได้ไม่เกิน 200 รายการต่อจุดยึด หากมากกว่านั้นจะถือว่าผิดพลาด ให้เขียนจุดยึดให้ยาวขึ้น

จุดยึดที่ไม่ตรงกับข้อความใดจะไม่สร้างช่อง และเอกสารจะบันทึกคำเตือน anchor_not_found เช่นเดียวกับแท็ก ช่องจาก จุดยึดที่จะล้นออกนอกหน้าจะถูกย้ายกลับเข้ามาในหน้า และผู้ลงนามที่ไม่มีช่องเลยจะทำให้ส่งคำขอไม่ได้ ซึ่ง GET /api/v1/envelopes/:id จะรายงานเหตุผลไว้ใน sendError

คุณใช้ช่องแบบพิกัด แท็ก (autoTags) และจุดยึดร่วมกันในคำขอเดียวได้ รวมกันไม่เกิน 500 ช่อง