Langsung ke konten utama
Dokumen ini adalah panduan konsep dasar untuk pengembangan di DingTalk Open Platform. Dokumen ini ditujukan bagi developer yang baru mengenal pengembangan DingTalk, dan membantu Anda memahami istilah inti, identifier identitas, serta sistem izin.

​
Console admin utama

Dokumen ini mencakup tiga console utama. Gunakan yang sesuai dengan peran Anda:

​
Developer Console

DingTalk Developer Console adalah platform untuk mengelola pengembangan aplikasi. Developer dapat mengonfigurasi informasi aplikasi dan memantau status runtime aplikasi.
Hanya Admin Organisasi dan Sub Admin yang diberi izin Developer sekaligus izin Workbench Management yang dapat mengakses Developer Console. Konfigurasikan izin Sub Admin di DingTalk Admin Console.

​
Admin Console

DingTalk Admin Console adalah platform inti tempat Admin Organisasi mengelola struktur organisasi, izin pengguna, dan konfigurasi workbench. Dari console ini, admin dapat mengimpor kontak, menyiapkan proses persetujuan, memberikan otorisasi Sub Admin, dan lainnya.

​
Identifier identitas inti (sistem ID)

Dalam pengembangan DingTalk, membedakan “siapa” dari “aplikasi mana” sangatlah penting. Beberapa ID utama berikut didefinisikan:

​
CorpId

Identifier unik untuk sebuah organisasi di DingTalk. Sebagian besar panggilan API tingkat organisasi memerlukan ID ini untuk autentikasi. Tempat menemukannya: Masuk ke DingTalk Developer Console dan lihat CorpId organisasi di halaman Home.

​
UserId

Identifier unik dari seorang karyawan tertentu dalam sebuah organisasi. ID ini digunakan pada API seperti mengirim pesan, membuat kueri profil, dan persetujuan. ID ini tidak dapat diubah. Tempat menemukannya: Masuk ke DingTalk Admin Console, buka Contacts > User Management, lalu klik nama karyawan untuk melihat UserId.

​
UnionId

Identifier pengguna yang terpadu di berbagai aplikasi. Pengguna yang sama memiliki UnionId yang sama di seluruh aplikasi dalam akun Open Platform yang sama. ID ini digunakan untuk mengintegrasikan data antaraplikasi. Tempat menemukannya: Panggil API Query user details dengan userId pengguna untuk mengambil nilai parameter unionid.

​
Unified App ID

ID yang unik secara global yang diberikan oleh DingTalk kepada semua jenis aplikasi. ID ini menyederhanakan integrasi lintas sistem dan secara bertahap menggantikan sistem AgentId/AppId lama. Tempat menemukannya: Masuk ke DingTalk Developer Console, buka halaman detail aplikasi, dan lihat di bawah Credentials and Basic Information.

​
AgentId

Identifier kapabilitas untuk aplikasi internal (seperti aplikasi H5 dan mini program). ID ini terutama digunakan untuk API pengelolaan workbench (misalnya, mengonfigurasi halaman beranda). Tempat menemukannya:
  • AgentId untuk aplikasi H5 internal
  • AgentId untuk mini program internal

​
Kredensial keamanan dan izin (sistem Auth)

Bagian ini membahas bagian pengembangan yang paling rawan error, termasuk autentikasi panggilan API dan logika login senyap.

​
Client ID / Client Secret

  • Definisi: Pasangan kredensial identitas sebuah aplikasi (mirip username dan password).
  • Tujuan: Digunakan untuk memperoleh access_token. Baik aplikasi internal maupun aplikasi pihak ketiga menggunakan mekanisme ini.
  • Catatan: Client Secret adalah kunci privat. Simpan dengan aman dan jangan pernah membocorkannya.
  • Cara memperoleh: Setelah Anda membuat aplikasi internal atau aplikasi perusahaan pihak ketiga di DingTalk Developer Console, pasangan Client ID dan Client Secret akan dibuat secara otomatis.

​
Catatan

Jika aplikasi internal diberi otorisasi untuk dikembangkan oleh penyedia layanan, penyedia layanan harus memperoleh otorisasi menggunakan CustomKey dan CustomSecret.

​
access_token

  • Definisi: “Tiket” untuk memanggil OpenAPI.
  • Tujuan: Kredensial ini harus disertakan pada setiap panggilan ke API yang terproteksi untuk memverifikasi permintaan.
  • Catatan: Token umumnya berlaku selama 7.200 detik (2 jam). Meminta ulang token dalam masa berlaku akan otomatis memperbaruinya.
  • Cara memperoleh:
    • Untuk aplikasi internal, panggil API Obtain the access token of an internal app untuk memperoleh access_token.
    • Untuk aplikasi perusahaan pihak ketiga, panggil API untuk memperoleh access token dari organisasi yang diberi otorisasi oleh aplikasi pihak ketiga guna memperoleh access_token.
  • Perbedaan:
    • access_token aplikasi internal memiliki semua izin yang diminta oleh aplikasi tersebut.
    • access_token aplikasi pihak ketiga dibatasi pada cakupan yang diotorisasi oleh organisasi.

​
authCode

Definisi: Kredensial utama yang digunakan untuk autentikasi identitas pengguna. Tujuan: Digunakan untuk ditukar menjadi informasi identitas pengguna (seperti userid). Catatan: Masa berlaku hanya 5 menit. Kredensial menjadi tidak valid setelah sekali digunakan dan tidak dapat dipakai ulang. Cara memperoleh: Peroleh dengan memanggil API seperti getAuthCode dan requestAuthCode. Untuk detailnya, lihat Autentikasi identitas (login senyap).

​
jsapi_ticket

Definisi: Digunakan untuk menghasilkan tanda tangan bagi JS API frontend. Tujuan: Aplikasi mikro H5 memerlukannya untuk memanggil berbagai kapabilitas JSAPI yang disediakan DingTalk secara aman (seperti mengambil informasi pengguna, memulai obrolan, dan memanggil komponen native). Catatan: Masa berlaku adalah 2 jam. Jika kedaluwarsa atau parameternya tidak konsisten, akan muncul error seperti “Failed to read jsapi ticket” atau “Signature verification failed”. Cara memperoleh: Gunakan access_token untuk memanggil API Create a JSAPI ticket guna memperolehnya.

​
Panduan cepat

Pseudo-code berikut menunjukkan cara menggunakan CorpId dan access_token untuk melakukan panggilan API yang paling sederhana, sekaligus memverifikasi bahwa lingkungan Anda sudah dikonfigurasi dengan benar:
Langkah-langkah:
  1. Peroleh kredensial: Gunakan Client ID dan Client Secret untuk memanggil API dan memperoleh access_token.
  2. Siapkan parameter: Cari UserId pengguna mana pun di Admin Console.
  3. Ganti parameter: Susun permintaan di atas dengan mengganti ACCESS_TOKEN dan USERID.
  4. Kirim permintaan uji: Jika respons mengembalikan "errcode": 0, "errmsg": "ok", berarti konfigurasi berhasil dan Anda dapat melanjutkan pengembangan lebih lanjut.
Tip: Di produksi, gunakan HTTPS serta terapkan penanganan error dan mekanisme coba-lagi yang tepat.