> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Panduan lengkap pemanggilan API
> Panduan bagi developer tentang seluruh alur — dari membuat aplikasi DingTalk, mengonfigurasi izin, memperoleh access_token, hingga memanggil API detail pengguna, lengkap dengan contoh kode dan tips debugging.
Panduan ini menuntun developer melalui seluruh proses pemanggilan API DingTalk Open Platform, mulai dari membuat aplikasi hingga panggilan API yang berhasil. Panduan ini mencakup langkah-langkah utama, contoh kode, hal-hal yang perlu diperhatikan, dan metode debugging untuk membantu developer memulai dengan cepat dan memanggil API dengan sukses.
Contoh ini berbasis aplikasi internal dan menunjukkan cara mengambil detail pengguna dari Kontak dengan memanggil API. Pendekatan yang sama berlaku untuk tipe aplikasi lainnya.
## Prasyarat
1. **Konsep dasar**: Pahami konsep dasar DingTalk Open Platform dan dokumentasi setiap modul produk. Lihat dokumentasi konsep dasar untuk detailnya.
2. **Batas laju API**: Pahami batas laju API. Lihat dokumentasi frekuensi pemanggilan API dan batas laju untuk detailnya.
3. **Izin developer**: Miliki izin Sub Admin dan developer di [Developer Backend](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/). Anda juga dapat masuk ke DingTalk Developer untuk mendaftar dan mengaktifkan pengguna baru.
4. **Peroleh** `UserId` **pengguna**: Masuk ke [DingTalk Admin Console](http://oa.dingtalk.io/) dan lihat `UserId` di bawah **Contacts > User management**. Lihat dokumentasi konsep dasar untuk detailnya.
## Langkah 1: Buat aplikasi DingTalk
1. Buka [Developer Backend](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/) dan klik **App Development** > **DingTalk App** > **Create app**.
2. Masukkan informasi aplikasi dan klik **Save**.
| **Bidang** | **Wajib** | **Deskripsi** |
| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nama aplikasi** | Ya | Masukkan nama aplikasi. Panjang minimum adalah 2 karakter. |
| **Deskripsi aplikasi** | Ya | Jelaskan secara singkat produk atau layanan yang disediakan aplikasi. Panjang minimum adalah 4 karakter. |
| **Ikon aplikasi** | Tidak | Unggah ikon aplikasi. Ikon harus dalam format JPG atau PNG, minimal 240 px \* 240 px, dengan rasio aspek 1:1, tanpa sudut membulat, dan tidak lebih besar dari 2 MB. |
3. Buka halaman detail aplikasi dan lihat kredensial serta informasi dasar aplikasi di bawah **Basic information** > **Credential and basic information**.
4. Simpan **Client ID** dan **Client Secret** aplikasi untuk pemanggilan API berikutnya.
### Catatan
Untuk detail cara memperoleh **Client ID** dan **Client Secret**, lihat dokumentasi konsep dasar. Simpan dengan aman setelah Anda memperolehnya untuk mencegah kebocoran.
## Langkah 2: Konfigurasikan izin
1. **Temukan izin yang diperlukan**: Menurut dokumentasi API, pemanggilan API detail pengguna memerlukan izin `Read user information`.
2. **Tambah izin**: Buka [Developer Backend](https://open-dev.dingtalk.io/?spm=dd_developers.header.unLogin.openDevBtn\&hash=%23%2F#/), temukan aplikasi yang Anda buat, buka halaman detail aplikasi, cari `Read user information` di bawah **Kelola izin**, dan klik **Apply now**.
## Langkah 3: Peroleh Access Token
Sebelum memperoleh **Access Token**, tentukan apakah API memerlukan [izin standar](/id/open/development/add-api-permission) atau [izin sensitif](/id/open/development/use-sensitive-permissions). Keduanya memiliki metode perolehan yang berbeda.
### API izin standar
#### Panggil API untuk memperoleh Token
1. Buka halaman API [Obtain the access token of an internal app](/id/open/development/obtain-the-access-token-of-an-internal-app) dan klik tombol **API Debug** di sebelah kanan untuk membuka [alat debugging sisi server](https://open.dingtalk.com/document/download/api-explorer).
2. Di alat debugging, ganti nilai `appkey (ganti dengan Client ID yang Anda peroleh sebelumnya)` dan `appSecret (ganti dengan Client Secret yang Anda peroleh sebelumnya)`, lalu klik **Debug**.
### Penting
Anda harus masuk untuk menggunakan konsol debugging sisi server dan harus mengikat aplikasi yang sesuai.
Anda juga dapat menyalin kode di bawah ini dan menggunakan perintah cURL. Ganti nilai `appkey (dengan Client ID yang Anda peroleh sebelumnya)` dan `appSecret (dengan Client Secret yang Anda peroleh sebelumnya)`, lalu kirim permintaan secara langsung. Contoh:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
-H 'Content-Type: application/json' \
-d '{
"appKey": "Ganti dengan Client ID yang Anda peroleh sebelumnya",
"appSecret": "Ganti dengan Client Secret yang Anda peroleh sebelumnya"
}'
```
#### Parsing respons
Setelah panggilan berhasil, sebuah nilai access token akan dibuat, seperti ditunjukkan di bawah ini:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # Kredensial inti
"expireIn" : 7200 # Masa berlaku (2 jam)
}
```
#### Cache dan muat ulang
* Simpan `access_token` dalam cache di database atau memori dan siapkan pembaruan terjadwal (10 menit sebelum kedaluwarsa).
* Hindari memanggil API Token terlalu sering, karena dapat memicu batas laju.
### API izin sensitif
Untuk mengaktifkan berbagi data dan pemanggilan fitur lintas organisasi, aplikasi pihak ketiga harus melalui proses otorisasi yang ketat. Aplikasi perlu memperoleh izin penggunaan dan izin akses data pengguna dari organisasi target melalui otorisasi tingkat organisasi maupun tingkat pengguna.
#### Ajukan izin API
Ajukan izin API sesuai dokumentasi [Use sensitive permissions](/id/open/development/use-sensitive-permissions).
#### Integrasikan suite otorisasi
Setelah mengajukan izin sensitif, integrasikan suite otorisasi. Ketika pengguna menerima otorisasi pada prompt, sebuah `authCode` akan dikembalikan. Kemudian panggil API [Obtain user token](/id/open/development/obtain-user-token) untuk menukarnya dengan `access_token` tingkat pengguna.
## Langkah 4: Panggil API detail pengguna
### API izin standar
Untuk mengambil detail pengguna, panggil API [Query user details](/id/open/development/query-user-details). Anda dapat menggunakan DingTalk SDK atau mengirim permintaan HTTP secara langsung. Pilih metode yang sesuai dengan kebutuhan Anda.
#### Opsi 1: Gunakan DingTalk SDK (direkomendasikan)
Sebelum menggunakan DingTalk SDK, pelajari perbedaan dalam Server API, lalu unduh versi SDK yang sesuai. Lihat dokumentasi perbedaan Server API untuk detailnya.
1. Instal SDK (contoh Python)
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install dingtalk-sdk
```
2. Contoh kode
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# -*- coding: utf-8 -*-
import dingtalk.api
req=dingtalk.api.OapiV2UserGetRequest("https://api.dingtalk.io/topapi/v2/user/get")
req.userid="zhangsan" # Ganti dengan ID pengguna yang sebenarnya
req.language="zh_CN"
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
```
#### Opsi 2: Kirim permintaan HTTP secara langsung
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -i 'https://api.dingtalk.io/topapi/v2/user/get' \
-X 'POST' \
-H 'Content-Type: application/json' \
-d '{"userid":"Ganti dengan ID pengguna yang sebenarnya","language":"zh_CN"}'
```
#### Respons berhasil
Jika respons berisi `"errcode":"0"` dan `"errmsg":"ok"`, panggilan berhasil.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"errcode":"0",
"result":{
"extension":"{\"Hobby\":\"Travel\",\"Age\":\"24\"}",
"unionid":"z21HjQliSzpw0YWxxxxx",
"boss":"true",
"role_list":{
"group_name":"Position",
"name":"Director",
"id":"100"
},
"exclusive_account":false,
"manager_userid":"manager240",
"admin":"true",
"remark":"Remark",
"title":"Technical Director",
"hired_date":"1597573616828",
"userid":"zhangsan",
"work_place":"Future Park",
"dept_order_list":{
"dept_id":"2",
"order":"1"
},
"real_authed":"true",
"dept_id_list":"[2,3,4]",
"job_number":"4",
"email":"test@xxx.com",
"leader_in_dept":{
"leader":"true",
"dept_id":"2"
},
"mobile":"13800138000",
"active":"true",
"org_email":"test@xxx.com",
"telephone":"010-86123456-2345",
"avatar":"xxx",
"hide_mobile":"false",
"senior":"true",
"name":"John",
"union_emp_ext":{
"union_emp_map_list":{
"userid":"5000",
"corp_id":"dingxxx"
},
"userid":"500",
"corp_id":"dingxxx"
},
"state_code":"86"
},
"errmsg":"ok"
}
```
#### Penanganan error
* **Izin tidak memadai**: Periksa apakah izin `Read user information` telah diajukan.
* **Pengguna tidak ada**: Pastikan `userid` valid dan bebas dari kesalahan ketik.
* **Token kedaluwarsa**: Muat ulang `access_token` dan coba lagi. Pastikan `access_token` valid dan bebas dari kesalahan ketik.
### API izin sensitif
Setelah menukar `authCode` dengan `access_token` tingkat pengguna, panggil [Retrieve user profile from Contacts](/id/open/development/dingtalk-retrieve-user-information) untuk memperoleh nama, unionId, dan informasi lain pengguna.
Jika API mengembalikan 200, panggilan berhasil. Responsnya adalah sebagai berikut:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"nick" : "zhangsan",
"avatarUrl" : "https://xxx",
"mobile" : "150xxxx9144",
"openId" : "123",
"unionId" : "z21HjQliSzpw0Yxxxx",
"email" : "zhangsan@example.com",
"stateCode" : "86"
}
```