Tài liệu về API

Shifton Nhiệm vụ cho phép tự động hóa công việc với nền tảng và kết nối nền tảng với các dịch vụ bên ngoài thông qua API mở. Qua API có thể truy cập tất cả các thực thể chính — nhiệm vụ, khách hàng, nhân viên, danh sách kiểm tra, tồn kho, khu vực dịch vụ, tài liệu Tài liệu tài chính và báo cáo, — vì vậy Shifton có thể được liên kết với các hệ thống HR, tính lương và phân tích của bạn, cũng như với các dịch vụ nội bộ của công ty.

Tài liệu về API

Tài liệu được xuất bản ở hai phiên bản:

• 🚀 Tài liệu mới — phiên bản hiện hành của sách tra cứu với cấu trúc đã cập nhật và các phương thức mới nhất: 👉 https://api2.shifton.com/openapi/
• 📄 Tài liệu cũ — phiên bản trước (vẫn được hỗ trợ cho các tích hợp hiện có): 👉 https://api2.shifton.com/docs/

Bạn có thể mở cả hai phiên bản ngay từ ứng dụng — trong phần Developer, ở tab Tổng quan, bằng các nút “Tài liệu mới” và “Tài liệu cũ”.

Tài liệu có sẵn ở hai ngôn ngữ. Ở góc trên bên phải của trang tài liệu mới có công tắc chuyển EN / RU — ngôn ngữ đã chọn sẽ được ghi nhớ.

Cách nhận khóa API

Khóa API được tạo ngay trong ứng dụng:

• Hãy mở phần Developer.
• Chuyển sang tab Khóa API (“Khóa API”).
• Nhấn “Tạo khóa API”.

Cần điền gì khi tạo khóa

Bảng điều khiển bên Tạo khóa API sẽ mở ra với các trường:

• Tiêu đề — tên của khóa, trường bắt buộc. Hãy đặt tên theo mục đích sử dụng để sau này bạn hiểu được cần tắt cái gì: “Xuất dữ liệu sang 1C”, “Báo cáo cho phân tích”.
• Hết hạn lúc — ngày mà sau đó khóa sẽ ngừng hoạt động. Nếu để trống trường này, thời hạn hiệu lực sẽ không bị giới hạn.
• Truy cập — phạm vi quyền của khóa:
• Full access (act as me) — khóa hoạt động dưới danh nghĩa của bạn và với quyền của bạn.
• Quyền hạn bị giới hạn — một tập hợp quyền hạn chế mà bạn tự chọn.

Nhấn Thêm để tạo khóa, hoặc Hủy để đóng bảng điều khiển.

📷 *Ảnh chụp bảng tạo khóa — cần chụp trên bản prod*

Khóa được tạo cho một công ty cụ thể và chỉ hoạt động với dữ liệu của công ty đó. Bạn có thể thu hồi khóa bất cứ lúc nào — việc thu hồi có hiệu lực ngay lập tức, và tất cả các yêu cầu sau đó với khóa này sẽ trả về lỗi 401.

Quan trọng: khóa đã tạo chỉ được hiển thị một lần duy nhất. Hãy sao chép nó ngay và lưu ở nơi an toàn — không thể lấy lại nó lần nữa. Nếu mất khóa, hãy tạo khóa mới và thu hồi khóa cũ.

Xác thực

Tất cả yêu cầu đến API đều được ký bằng khóa trong tiêu đề:

Authorization: Bearer {your_API_key}

Địa chỉ cơ sở của API:

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

Yêu cầu không có khóa hợp lệ sẽ trả về 401 và phần nội dung {"message":"Unauthenticated."}.

Yêu cầu đầu tiên

Ví dụ, để lấy danh sách nhân viên của công ty (hãy thay ID công ty của bạn vào chỗ {companyId}):

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

Cũng vậy nhưng qua curl:

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

ID công ty có thể thấy trong thanh địa chỉ của ứng dụng: app.shifton.com/c/8397/... — con số sau /c/.

Những gì khả dụng qua API

Sách tra cứu bao gồm hơn 360 phương thức. Các phần chính dành cho dịch vụ hiện trường:

• Nhiệm vụ — /companies/{companyId}/tasks: tạo, thay đổi, trạng thái, tệp của nhiệm vụ.
• Danh sách việc cần làm (To Do) — /companies/{companyId}/todo.
• Khách hàng — /companies/{companyId}/clients, cũng như địa chỉ và các trường tùy chỉnh của khách hàng.
• Danh sách kiểm tra — /companies/{companyId}/checklists.
• Khu vực dịch vụ — /companies/{companyId}/tasks/service-areas.
• Kỹ năng — /companies/{companyId}/skills.
• Nhân viên — /companies/{companyId}/employees: thêm, chỉnh sửa, cho nghỉ việc và khôi phục.
• Tồn kho — vật phẩm, danh mục, bộ và số lượng còn lại trong kho.
• Tài liệu tài chính — ước tính, đơn đặt hàng công việc, hóa đơn, biên nhận, bộ đếm tài liệu và logo.
• Báo cáo — xuất dữ liệu về công việc và điểm danh.

Ngoài ra, còn có lịch làm việc và ca làm, kỳ nghỉ và yêu cầu nghỉ phép, điểm danh, thanh toán và thanh toán SMS, thông báo và các mô-đun.

Webhook

Nếu thay vì gửi yêu cầu định kỳ đến API bạn cần nhận các sự kiện ngay khi chúng xảy ra, hãy dùng webhook — tab Webhooks trong phần Developer. Shifton sẽ tự gửi yêu cầu đến địa chỉ của bạn khi sự kiện cần thiết xảy ra; danh sách các sự kiện được hỗ trợ do một phương thức riêng trả về.

Mã lỗi

API của Shifton dùng các mã trạng thái HTTP tiêu chuẩn:

• 200 — yêu cầu được thực hiện thành công.
• 201 — đối tượng đã được tạo thành công.
• 400 — tham số yêu cầu không đúng.
• 401 — lỗi xác thực: khóa không được truyền, không hợp lệ hoặc đã bị thu hồi.
• 403 — truy cập bị từ chối.
• 404 — không tìm thấy tài nguyên (thường nhất là lỗi chính tả trong địa chỉ phương thức).
• 500 — lỗi máy chủ.

Lời khuyên khi sử dụng

• Với các tích hợp mới, hãy dùng tài liệu mới — tài liệu cũ được giữ lại cho các tích hợp đang hoạt động.
• Để kiểm tra các yêu cầu, Postman hoặc curl rất tiện — chúng cho phép xem phản hồi mà không cần viết một dòng mã nào.
• Đừng lưu khóa ở dạng mở trong mã và đừng chuyển nó cho người thứ ba: khóa cho quyền truy cập vào dữ liệu của công ty.
• Hãy tuân thủ các giới hạn về tần suất yêu cầu (rate limits) — vượt quá chúng có thể dẫn đến việc tạm thời bị chặn truy cập vào API.

Câu hỏi thường gặp

Câu hỏi: Lấy khóa API ở đâu? Trả lời: Trong ứng dụng: phần Developer → tab Khóa API → nút “Tạo khóa API”. Khóa được phát hành cho công ty hiện tại.

Câu hỏi: Tôi đã đóng cửa sổ và không sao chép khóa. Xem nó ở đâu? Trả lời: Không ở đâu cả — khóa chỉ hiển thị một lần và không được phát hành lại. Hãy tạo khóa mới và thu hồi khóa cũ.

Câu hỏi: Làm thế nào để thu hồi khóa nếu nó rơi vào tay người khác? Trả lời: Hãy xóa nó ở tab Khóa API. Việc thu hồi có hiệu lực ngay lập tức: tất cả yêu cầu với khóa này sẽ lập tức bắt đầu trả về 401.

Câu hỏi: “Full access” và “Restricted permissions” khác nhau ở đâu? Trả lời: Full access (act as me) cho khóa những quyền giống như bạn đang có. Quyền hạn bị giới hạn cho phép cấp cho khóa chỉ một tập hợp quyền được chọn — như vậy an toàn hơn cho tích hợp chỉ cần truy cập một phần dữ liệu.

Câu hỏi: Có thể giới hạn thời hạn hiệu lực của khóa không? Trả lời: Có, bằng trường Hết hạn lúc khi tạo. Nếu không điền trường này, khóa sẽ vô thời hạn.

Câu hỏi: Một khóa có hoạt động cho nhiều công ty không? Trả lời: Không. Khóa được gắn với công ty mà nó được tạo trong đó, và chỉ hoạt động với dữ liệu của công ty đó. Với công ty khác, hãy tạo khóa riêng.

Câu hỏi: Địa chỉ cơ sở của API là gì? Trả lời: https://api2.shifton.com/work/1.0.0. Tiếp theo là đường dẫn của phương thức, ví dụ /companies/{companyId}/tasks.

Câu hỏi: Lấy ID công ty cho các yêu cầu ở đâu? Trả lời: Nó có trong thanh địa chỉ của ứng dụng ngay sau /c/ — ví dụ, trong app.shifton.com/c/8397/tasks mã nhận dạng công ty bằng 8397.

Câu hỏi: Nên dùng phiên bản tài liệu nào? Trả lời: Với các tích hợp mới — phiên bản mới (api2.shifton.com/openapi). Phiên bản cũ (api2.shifton.com/docs) được hỗ trợ cho các tích hợp hiện có.

Câu hỏi: Có tài liệu bằng tiếng Nga không? Trả lời: Có. Trên trang tài liệu mới, ở góc trên bên phải có công tắc chuyển EN / RU.

Câu hỏi: Dùng gì để kiểm thử các yêu cầu đến API? Trả lời: Tiện nhất là Postman hoặc curl — chúng cho phép gửi yêu cầu và xem phản hồi mà không cần viết mã.

Câu hỏi: Vì sao vẫn nhận được 401 dù tôi đã sao chép khóa? Trả lời: Hãy kiểm tra rằng khóa được truyền trong tiêu đề Authorization với từ Bearer đứng trước nó, rằng khóa chưa bị thu hồi và chưa hết thời hạn hiệu lực.

Câu hỏi: Vì sao nhận được 404? Trả lời: Thường nhất là địa chỉ bị lẫn: phần cơ sở phải là https://api2.shifton.com/work/1.0.0, còn trong đường dẫn phương thức phải là {companyId} đúng.

Câu hỏi: Có thể tự động hóa gì qua API? Trả lời: Việc tạo và thay đổi nhiệm vụ, làm việc với khách hàng và địa chỉ của họ, danh sách kiểm tra, khu vực dịch vụ, kỹ năng, nhân viên, tồn kho, tài liệu Tài liệu tài chính và xuất báo cáo, cũng như lịch làm việc, ca làm và kỳ nghỉ.

Câu hỏi: Có thể nhận các sự kiện từ Shifton thay vì gọi API liên tục không? Trả lời: Có, để làm việc đó có webhook — tab Webhooks trong phần Developer.

Câu hỏi: Việc đổi mật khẩu có ảnh hưởng đến hoạt động của tích hợp không? Trả lời: Không. Các tích hợp hoạt động theo khóa API, chứ không theo mật khẩu của tài khoản.