เอกสารประกอบ API

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

เอกสารประกอบ API

เอกสารประกอบเผยแพร่ไว้สองเวอร์ชัน:

🚀 เอกสารประกอบใหม่ — คู่มืออ้างอิงเวอร์ชันปัจจุบันที่มีโครงสร้างใหม่และเมธอดล่าสุด: 👉 https://api2.shifton.com/openapi/
📄 เอกสารประกอบเก่า — เวอร์ชันก่อนหน้า (ยังรองรับสำหรับการเชื่อมต่อที่มีอยู่แล้ว): 👉 https://api2.shifton.com/docs/

คุณเปิดทั้งสองเวอร์ชันได้จากแอปพลิเคชันโดยตรง — ในส่วน Developer แท็บ ภาพรวม ด้วยปุ่ม “เอกสารประกอบใหม่” และ “เอกสารประกอบเก่า”

เอกสารประกอบมีสองภาษา ที่มุมขวาบนของหน้าเอกสารประกอบใหม่มีสวิตช์ EN / RU — ภาษาที่เลือกไว้จะถูกจำไว้

วิธีขอคีย์ API

คีย์ API สร้างขึ้นในแอปพลิเคชันเอง:

เปิดส่วน Developer
ไปที่แท็บ คีย์ API (“คีย์ API”)
คลิก “สร้างคีย์ API”

สิ่งที่ต้องกรอกเมื่อสร้างคีย์

แผงด้านข้าง สร้างคีย์ API จะเปิดขึ้นพร้อมช่องข้อมูลต่อไปนี้:

ชื่อเรื่อง — ชื่อของคีย์ เป็นช่องที่จำเป็น ให้ตั้งชื่อตามวัตถุประสงค์ เพื่อให้เข้าใจภายหลังว่าควรปิดคีย์ใด: “ส่งออกไปยัง 1C”, “รายงานสำหรับการวิเคราะห์ข้อมูล”
หมดอายุเวลา — วันที่ที่คีย์จะเลิกใช้งานได้ หากเว้นช่องนี้ว่างไว้ คีย์จะไม่มีวันหมดอายุ
การเข้าถึง — ขอบเขตสิทธิ์ของคีย์:
Full access (act as me) — คีย์ทำงานในนามของคุณและด้วยสิทธิ์ของคุณ
สิทธิ์ที่ถูกจำกัด — ชุดสิทธิ์ที่จำกัดซึ่งคุณเลือกเอง

คลิก เพิ่ม เพื่อสร้างคีย์ หรือ ยกเลิก เพื่อปิดแผง

📷 *ภาพหน้าจอของแผงสร้างคีย์ — ต้องถ่ายจากระบบโปรดักชัน*

คีย์ถูกสร้างขึ้น สำหรับบริษัทหนึ่งบริษัทโดยเฉพาะ และทำงานกับข้อมูลของบริษัทนั้นเท่านั้น คุณเพิกถอนคีย์ได้ทุกเมื่อ — การเพิกถอนมีผลทันที และคำขอทั้งหมดหลังจากนั้นที่ใช้คีย์นี้จะคืนค่าข้อผิดพลาด 401

ข้อสำคัญ: คีย์ที่สร้างขึ้นจะแสดง เพียงครั้งเดียว เท่านั้น ให้คัดลอกทันทีและเก็บไว้ในที่ปลอดภัย — ขอดูอีกครั้งไม่ได้ หากคีย์หายไป ให้สร้างคีย์ใหม่และเพิกถอนคีย์เก่า

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

คำขอทั้งหมดที่ส่งไปยัง API จะลงลายมือชื่อด้วยคีย์ในส่วนหัว:

Authorization: Bearer {your_API_key}

ที่อยู่พื้นฐานของ API:

https://api2.shifton.com/work/1.0.0

คำขอที่ไม่มีคีย์ที่ใช้งานได้จะคืนค่า 401 และเนื้อหา {"message":"Unauthenticated."}

คำขอแรก

ตัวอย่างเช่น หากต้องการดึงรายชื่อพนักงานของบริษัท (ให้ใส่ ID บริษัทของคุณแทน {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

สิ่งเดียวกันนี้ผ่าน curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

ID บริษัทเห็นได้ในแถบที่อยู่ของแอปพลิเคชัน: app.shifton.com/c/8397/... — คือตัวเลขที่อยู่หลัง /c/

สิ่งที่ใช้ได้ผ่าน API

คู่มืออ้างอิงครอบคลุมเมธอดมากกว่า 360 รายการ ส่วนหลักสำหรับบริการภาคสนาม:

งาน — /companies/{companyId}/tasks: การสร้าง การแก้ไข สถานะ ไฟล์ของงาน
รายการสิ่งที่ต้องทำ (To Do) — /companies/{companyId}/todo
ลูกค้า — /companies/{companyId}/clients รวมทั้งที่อยู่และช่องข้อมูลที่กำหนดเองของลูกค้า
รายการตรวจสอบ — /companies/{companyId}/checklists
เขตพื้นที่ให้บริการ — /companies/{companyId}/tasks/service-areas
ทักษะ — /companies/{companyId}/skills
พนักงาน — /companies/{companyId}/employees: การเพิ่ม การแก้ไข การเลิกจ้าง และการกู้คืน
สินค้าคงคลัง — รายการสิ่งของ หมวดหมู่ ชุดอุปกรณ์ และยอดคงเหลือในคลังสินค้า
เอกสารทางการเงิน — ประมาณการ ใบสั่งงาน ใบแจ้งหนี้ ใบเสร็จ ตัวนับเอกสาร และโลโก้
รายงาน — การส่งออกข้อมูลการทำงานและการเข้างาน

นอกจากนี้ยังมีตารางเวลาและกะ วันลาและคำขอลา การเข้างาน การเรียกเก็บเงินและการเรียกเก็บเงินผ่าน SMS การแจ้งเตือน และโมดูล

เว็บฮุก

หากคุณต้องการรับเหตุการณ์ในขณะที่เกิดขึ้น แทนการส่งคำขอไปยัง API เป็นระยะ ให้ใช้ เว็บฮุก — แท็บ Webhooks ในส่วน Developer Shifton จะส่งคำขอไปยังที่อยู่ของคุณเองเมื่อเกิดเหตุการณ์ที่ต้องการ รายการเหตุการณ์ที่รองรับดึงได้จากเมธอดแยกต่างหาก

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

API ของ Shifton ใช้ รหัสสถานะ HTTP มาตรฐาน:

200 — คำขอสำเร็จ
201 — สร้างอ็อบเจกต์สำเร็จ
400 — พารามิเตอร์ของคำขอไม่ถูกต้อง
401 — ข้อผิดพลาดในการยืนยันตัวตน: ไม่ได้ส่งคีย์ คีย์ไม่ถูกต้อง หรือถูกเพิกถอน
403 — ไม่อนุญาตให้เข้าถึง
404 — ไม่พบทรัพยากร (ส่วนใหญ่มักเป็นการพิมพ์ที่อยู่ของเมธอดผิด)
500 — ข้อผิดพลาดของเซิร์ฟเวอร์

คำแนะนำการใช้งาน

สำหรับการเชื่อมต่อใหม่ ให้ใช้ เอกสารประกอบใหม่ — เวอร์ชันเก่ายังอยู่เพื่อรองรับการเชื่อมต่อที่ทำงานอยู่แล้ว
สำหรับตรวจสอบคำขอ Postman หรือ curl สะดวกที่สุด — ช่วยให้เห็นคำตอบได้โดยไม่ต้องเขียนโค้ดแม้แต่บรรทัดเดียว
อย่าเก็บคีย์ไว้ในโค้ดแบบเปิดเผย และอย่าส่งต่อให้บุคคลที่สาม: คีย์ให้สิทธิ์เข้าถึงข้อมูลของบริษัท
ปฏิบัติตาม ข้อจำกัดความถี่ของคำขอ (rate limits) — การเกินข้อจำกัดอาจทำให้การเข้าถึง API ถูกบล็อกชั่วคราว

คำถามที่พบบ่อย

คำถาม: ขอคีย์ API ได้ที่ไหน? คำตอบ: ในแอปพลิเคชัน: ส่วน Developer → แท็บ คีย์ API → ปุ่ม “สร้างคีย์ API” คีย์จะออกให้สำหรับบริษัทปัจจุบัน

คำถาม: ฉันปิดหน้าต่างไปแล้วและไม่ได้คัดลอกคีย์ ดูคีย์ได้ที่ไหน? คำตอบ: ไม่มีที่ใดเลย — คีย์แสดงเพียงครั้งเดียวและไม่ออกให้ซ้ำ ให้สร้างคีย์ใหม่และเพิกถอนคีย์เก่า

คำถาม: เพิกถอนคีย์ได้อย่างไรถ้าคีย์ตกไปอยู่ในมือผู้ไม่เกี่ยวข้อง? คำตอบ: ให้ลบคีย์นั้นในแท็บ คีย์ API การเพิกถอนมีผลทันที: คำขอทั้งหมดที่ใช้คีย์นี้จะเริ่มคืนค่า 401 ทันที

คำถาม: “Full access” ต่างจาก “Restricted permissions” อย่างไร? คำตอบ: Full access (act as me) ให้คีย์มีสิทธิ์เดียวกับที่คุณมี ส่วน สิทธิ์ที่ถูกจำกัด ช่วยให้คุณให้คีย์เฉพาะชุดสิทธิ์ที่เลือกไว้เท่านั้น — ปลอดภัยกว่าสำหรับการเชื่อมต่อที่ต้องเข้าถึงข้อมูลเพียงบางส่วน

คำถาม: จำกัดอายุการใช้งานของคีย์ได้ไหม? คำตอบ: ได้ ด้วยช่อง หมดอายุเวลา ตอนสร้าง หากไม่กรอกช่องนี้ คีย์จะไม่มีวันหมดอายุ

คำถาม: คีย์เดียวใช้ได้กับหลายบริษัทหรือไม่? คำตอบ: ไม่ได้ คีย์ผูกกับบริษัทที่สร้างคีย์นั้นขึ้นมา และทำงานกับข้อมูลของบริษัทนั้นเท่านั้น สำหรับบริษัทอื่น ให้สร้างคีย์แยกต่างหาก

คำถาม: ที่อยู่พื้นฐานของ API คืออะไร? คำตอบ: https://api2.shifton.com/work/1.0.0 ถัดจากนั้นคือเส้นทางของเมธอด ตัวอย่างเช่น /companies/{companyId}/tasks

คำถาม: หา ID บริษัทสำหรับใช้ในคำขอได้ที่ไหน? คำตอบ: อยู่ในแถบที่อยู่ของแอปพลิเคชันถัดจาก /c/ ทันที — ตัวอย่างเช่น ใน app.shifton.com/c/8397/tasks ตัวระบุบริษัทคือ 8397

คำถาม: ควรใช้เอกสารประกอบเวอร์ชันใด? คำตอบ: สำหรับการเชื่อมต่อใหม่ — เวอร์ชันใหม่ (api2.shifton.com/openapi) เวอร์ชันเก่า (api2.shifton.com/docs) ยังรองรับสำหรับการเชื่อมต่อที่มีอยู่แล้ว

คำถาม: มีเอกสารประกอบภาษารัสเซียหรือไม่? คำตอบ: มี ในหน้าเอกสารประกอบใหม่ที่มุมขวาบนมีสวิตช์ EN / RU

คำถาม: ใช้อะไรทดสอบคำขอไปยัง API? คำตอบ: สะดวกที่สุดคือ Postman หรือ curl — ช่วยให้ส่งคำขอและดูคำตอบได้โดยไม่ต้องเขียนโค้ด

คำถาม: ทำไมได้ 401 ทั้งที่ฉันคัดลอกคีย์มาแล้ว? คำตอบ: โปรดตรวจสอบว่าคีย์ถูกส่งในส่วนหัว Authorization โดยมีคำว่า Bearer อยู่ข้างหน้า คีย์ไม่ได้ถูกเพิกถอน และยังไม่หมดอายุ

คำถาม: ทำไมได้ 404? คำตอบ: ส่วนใหญ่มักเป็นเพราะที่อยู่สับสน: ส่วนพื้นฐานต้องเป็น https://api2.shifton.com/work/1.0.0 และในเส้นทางของเมธอดต้องมี {companyId} ที่ถูกต้อง

คำถาม: อะไรที่ทำแบบอัตโนมัติผ่าน API ได้? คำตอบ: การสร้างและแก้ไขงาน การจัดการลูกค้าและที่อยู่ของลูกค้า รายการตรวจสอบ เขตพื้นที่ให้บริการ ทักษะ พนักงาน สินค้าคงคลัง เอกสารในเอกสารทางการเงิน และการส่งออกรายงาน รวมทั้งตารางเวลา กะ และวันลา

คำถาม: รับเหตุการณ์จาก Shifton ได้ไหม แทนการเรียกถาม API เป็นระยะ? คำตอบ: ได้ สำหรับกรณีนี้มี เว็บฮุก — แท็บ Webhooks ในส่วน Developer

คำถาม: การเปลี่ยนรหัสผ่านมีผลต่อการทำงานของการเชื่อมต่อหรือไม่? คำตอบ: ไม่มีผล การเชื่อมต่อทำงานด้วยคีย์ API ไม่ใช่ด้วยรหัสผ่านของบัญชี