Dokumentasi API

Shifton Tugas memungkinkan Anda mengotomatiskan pekerjaan dengan platform dan menghubungkannya ke layanan eksternal melalui API terbuka. Melalui API tersedia semua entitas utama — tugas, klien, karyawan, daftar periksa, inventaris, zona layanan, dokumen Dokumen keuangan, dan laporan — sehingga Shifton dapat dihubungkan dengan sistem HR, penggajian, dan analitik Anda, serta dengan layanan internal perusahaan.

Dokumentasi diterbitkan dalam dua versi:

🚀 Dokumentasi baru — versi acuan terkini dengan struktur yang diperbarui dan metode terbaru: 👉 https://api2.shifton.com/openapi/
📄 Dokumentasi lama — versi sebelumnya (masih didukung untuk integrasi yang sudah ada): 👉 https://api2.shifton.com/docs/

Kedua versi dapat dibuka langsung dari aplikasi — di bagian Developer, pada tab Ikhtisar, dengan tombol “Dokumentasi baru” dan “Dokumentasi lama”.

Dokumentasi tersedia dalam dua bahasa. Di sudut kanan atas halaman dokumentasi baru ada pengalih EN / RU — bahasa yang dipilih akan diingat.

Cara memperoleh kunci API

Kunci API dibuat di dalam aplikasi itu sendiri:

Buka bagian Developer.
Beralihlah ke tab Kunci API (“Kunci API”).
Klik “Buat kunci API”.

Apa yang diisi saat membuat kunci

Panel samping Buat kunci API akan terbuka dengan kolom-kolom:

Judul — nama kunci, kolom wajib. Berilah nama sesuai peruntukannya agar nanti jelas mana yang harus dimatikan: “Ekspor ke 1C”, “Laporan untuk analitik”.
Kedaluwarsa pada — tanggal setelah itu kunci berhenti berlaku. Jika kolom ini dibiarkan kosong, masa berlakunya tidak dibatasi.
Akses — cakupan hak kunci:
Full access (act as me) — kunci bekerja atas nama Anda dan dengan hak Anda.
Izin terbatas — kumpulan izin terbatas yang Anda pilih sendiri.

Klik Tambahkan untuk membuat kunci, atau Batalkan untuk menutup panel.

📷 *Tangkapan layar panel pembuatan kunci — diambil di prod*

Kunci dibuat untuk perusahaan tertentu dan hanya bekerja dengan datanya. Kunci dapat dicabut kapan saja — pencabutan berlaku seketika, dan semua permintaan berikutnya dengan kunci itu akan mengembalikan galat 401.

Penting: kunci yang sudah dibuat ditampilkan hanya sekali. Salinlah segera dan simpan di tempat yang aman — kunci itu tidak dapat diperoleh lagi. Jika kunci hilang, buat kunci baru lalu cabut yang lama.

Otorisasi

Semua permintaan ke API ditandatangani dengan kunci di dalam header:

Authorization: Bearer {your_API_key}

Alamat dasar API:

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

Permintaan tanpa kunci yang berlaku mengembalikan 401 dan badan {"message":"Unauthenticated."}.

Permintaan pertama

Misalnya, untuk memperoleh daftar karyawan perusahaan (masukkan ID perusahaan Anda sebagai ganti {companyId}):

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

Hal yang sama melalui curl:

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

ID perusahaan terlihat di bilah alamat aplikasi: app.shifton.com/c/8397/... — angka setelah /c/.

Apa saja yang tersedia melalui API

Acuan ini mencakup lebih dari 360 metode. Bagian utama untuk layanan lapangan:

Tugas — /companies/{companyId}/tasks: pembuatan, perubahan, status, file tugas.
Daftar kerja (To Do) — /companies/{companyId}/todo.
Klien — /companies/{companyId}/clients, serta alamat dan kolom khusus klien.
Daftar periksa — /companies/{companyId}/checklists.
Zona layanan — /companies/{companyId}/tasks/service-areas.
Keahlian — /companies/{companyId}/skills.
Karyawan — /companies/{companyId}/employees: penambahan, penyuntingan, pemberhentian, dan pemulihan.
Inventaris — barang, kategori, set, dan sisa stok di gudang.
Dokumen keuangan — estimasi, pesanan kerja, faktur, kwitansi, penghitung dokumen, dan logo.
Laporan — ekspor data tentang pekerjaan dan kehadiran.

Selain itu, tersedia jadwal dan sif, cuti dan permintaan izin, kehadiran, penagihan dan penagihan SMS, notifikasi, serta modul.

Webhook

Jika alih-alih permintaan berkala ke API Anda perlu menerima peristiwa pada saat peristiwa itu terjadi, gunakan webhook — tab Webhooks di bagian Developer. Shifton sendiri yang akan mengirim permintaan ke alamat Anda ketika peristiwa yang dibutuhkan terjadi; daftar peristiwa yang didukung dikembalikan oleh metode tersendiri.

Kode kesalahan

API Shifton menggunakan kode status HTTP standar:

200 — permintaan berhasil dijalankan.
201 — objek berhasil dibuat.
400 — parameter permintaan tidak benar.
401 — galat otorisasi: kunci tidak dikirim, tidak berlaku, atau sudah dicabut.
403 — akses dilarang.
404 — sumber daya tidak ditemukan (paling sering salah ketik pada alamat metode).
500 — galat server.

Tips penggunaan

Untuk integrasi baru, gunakan dokumentasi baru — yang lama disediakan untuk integrasi yang sudah berjalan.
Untuk menguji permintaan, praktis memakai Postman atau curl — keduanya memungkinkan Anda melihat jawaban tanpa menulis satu baris kode pun.
Jangan menyimpan kunci dalam bentuk terbuka di dalam kode dan jangan menyerahkannya kepada pihak ketiga: kunci itu memberi akses ke data perusahaan.
Patuhi pembatasan frekuensi permintaan (rate limits) — melampauinya dapat menyebabkan pemblokiran sementara atas akses ke API.

Pertanyaan yang Sering Diajukan

Pertanyaan: Di mana kunci API diperoleh? Jawaban: Di aplikasi: bagian Developer → tab Kunci API → tombol “Buat kunci API”. Kunci diterbitkan untuk perusahaan saat ini.

Pertanyaan: Saya menutup jendela dan belum menyalin kunci. Bagaimana? Jawaban: Tidak ada tempat untuk melihatnya — kunci ditampilkan hanya sekali dan tidak diterbitkan ulang. Buat kunci baru, lalu cabut yang lama.

Pertanyaan: Bagaimana mencabut kunci jika jatuh ke tangan yang salah? Jawaban: Hapus kunci itu di tab Kunci API. Pencabutan berlaku seketika: semua permintaan dengan kunci itu langsung mengembalikan 401.

Pertanyaan: Apa beda “Full access” dan “Restricted permissions”? Jawaban: Full access (act as me) memberi kunci hak yang sama seperti yang Anda miliki. Izin terbatas memungkinkan Anda memberi kunci hanya sekumpulan izin yang dipilih — cara ini lebih aman untuk integrasi yang hanya perlu akses ke sebagian data.

Pertanyaan: Bisakah masa berlaku kunci dibatasi? Jawaban: Ya, dengan kolom Kedaluwarsa pada saat pembuatan. Jika kolom itu tidak diisi, kunci berlaku tanpa batas waktu.

Pertanyaan: Apakah satu kunci berlaku untuk beberapa perusahaan? Jawaban: Tidak. Kunci terikat pada perusahaan tempat ia dibuat dan hanya bekerja dengan datanya. Untuk perusahaan lain, buatlah kunci tersendiri.

Pertanyaan: Apa alamat dasar API? Jawaban: https://api2.shifton.com/work/1.0.0. Selanjutnya menyusul jalur metode, misalnya /companies/{companyId}/tasks.

Pertanyaan: Di mana ID perusahaan untuk permintaan diperoleh? Jawaban: ID itu ada di bilah alamat aplikasi tepat setelah /c/ — misalnya, pada app.shifton.com/c/8397/tasks pengenal perusahaannya adalah 8397.

Pertanyaan: Versi dokumentasi mana yang sebaiknya dipakai? Jawaban: Untuk integrasi baru — yang baru (api2.shifton.com/openapi). Yang lama (api2.shifton.com/docs) didukung untuk integrasi yang sudah ada.

Pertanyaan: Apakah ada dokumentasi dalam bahasa Rusia? Jawaban: Ya. Di halaman dokumentasi baru, di sudut kanan atas, ada pengalih EN / RU.

Pertanyaan: Dengan apa permintaan ke API diuji? Jawaban: Paling praktis dengan Postman atau curl — keduanya memungkinkan Anda mengirim permintaan dan melihat jawaban tanpa menulis kode.

Pertanyaan: Mengapa muncul 401 padahal kunci sudah saya salin? Jawaban: Periksa bahwa kunci dikirim di header Authorization dengan kata Bearer di depannya, bahwa kunci belum dicabut, dan masa berlakunya belum habis.

Pertanyaan: Mengapa muncul 404? Jawaban: Paling sering alamatnya tertukar: bagian dasarnya harus https://api2.shifton.com/work/1.0.0, dan pada jalur metode harus ada {companyId} yang benar.

Pertanyaan: Apa saja yang dapat diotomatiskan melalui API? Jawaban: Pembuatan dan perubahan tugas, pekerjaan dengan klien dan alamatnya, daftar periksa, zona layanan, keahlian, karyawan, inventaris, dokumen Dokumen keuangan dan ekspor laporan, serta jadwal, sif, dan cuti.

Pertanyaan: Bisakah peristiwa diterima dari Shifton tanpa memanggil API? Jawaban: Ya, untuk itu ada webhook — tab Webhooks di bagian Developer.

Pertanyaan: Apakah penggantian kata sandi memengaruhi integrasi? Jawaban: Tidak. Integrasi bekerja dengan kunci API, bukan dengan kata sandi akun.