Deskripsi panggilan API
API ini mendukung pembuatan pengguna biasa maupun pengguna Akun Perusahaan. Karena penggunaan parameter sangat berbeda antara kedua skenario tersebut, dokumentasi dipisah berdasarkan tipe akun agar lebih jelas:- Untuk membuat pengguna biasa, lihat artikel ini.
- Untuk membuat pengguna Akun Perusahaan (hanya tersedia bagi organisasi yang telah membeli dan mengaktifkan fitur ini), lihat artikel berikut:
Permintaan
| Informasi dasar | |
|---|---|
| URL HTTP | https://api.dingtalk.io/topapi/v2/user/create |
| Metode HTTP | POST |
| Tipe aplikasi yang didukung | appType-Internal app |
| Izin yang diperlukan | permission-qyapi_manage_addresslist-Izin pengelolaan data Kontak |
Parameter query
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| access_token | String | Ya | BE3xxxx | Kredensial aplikasi untuk memanggil API ini. Dapatkan dengan memanggil API yang mengambil access_token dari aplikasi internal. |
Isi permintaan
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| userid | String | Tidak | zhangsan | Identifikasi unik karyawan (tidak dapat diubah). Harus unik dalam organisasi Anda. Panjangnya harus 1 hingga 64 karakter. Jika tidak ditentukan, userid akan dibuat secara otomatis. |
| name | String | Ya | Budi | Nama karyawan. Maksimum 80 karakter. |
| mobile | String | Ya | 185xxxx | Nomor ponsel. Harus unik dalam organisasi Anda dan tidak boleh diduplikasi. - Untuk nomor internasional atau nomor dari Hong Kong (Tiongkok), Makau (Tiongkok), atau Taiwan (Tiongkok), gunakan format +xx-xxxxxx. - Jika perusahaan terdaftar di luar Tiongkok daratan, gunakan format +86-xxxxxx saat menambahkan pengguna. Catatan Masuk ke DingTalk Admin Console untuk melihat alamat pendaftaran organisasi. |
| hide_mobile | Boolean | Tidak | false | Apakah menyembunyikan nomor ponsel: - true: Sembunyikan. Setelah nomor ponsel disembunyikan, nomor tidak ditampilkan di halaman Profil, tetapi pengguna lain masih dapat mengirim DING dan memulai panggilan bisnis DingTalk gratis. - false: Jangan sembunyikan. |
| telephone | String | Tidak | 010-86123456-2345 | Nomor ekstensi. Maksimum 50 karakter. Catatan Nomor ekstensi harus unik dalam organisasi Anda. |
| job_number | String | Tidak | 4 | ID Karyawan. Maksimum 50 karakter. |
| title | String | Tidak | Direktur Teknis | Jabatan. Maksimum 200 karakter. |
| String | Tidak | test@xxx.com | Email pribadi karyawan. Maksimum 50 karakter. Catatan Alamat email karyawan harus unik dalam organisasi Anda. | |
| org_email | String | Tidak | test@xxx.com | Email Perusahaan karyawan. Maksimum 100 karakter. Catatan Bidang ini hanya berlaku jika Email Perusahaan telah diaktifkan untuk karyawan tersebut. |
| org_email_type | String | Tidak | profession | Tipe Email Perusahaan karyawan. - profession: Standar - base: Dasar |
| work_place | String | Tidak | Future Park | Lokasi Kerja. Maksimum 100 karakter. |
| remark | String | Tidak | Alias | Alias. Maksimum 2000 karakter. |
| dept_id_list | String | Ya | ”2,3,4” | Daftar ID departemen tempat karyawan bernaung. Hingga 100 ID departemen dapat dikirim per panggilan. |
| dept_order_list | Object[] | Tidak | Urutan pengurutan karyawan dalam departemen terkait. | |
| dept_id | Number | Tidak | 2 | ID departemen. |
| order | Number | Tidak | 1 | Urutan pengurutan karyawan dalam departemen. |
| dept_title_list | Object[] | Tidak | Jabatan karyawan dalam departemen terkait. | |
| dept_id | Number | Tidak | 2 | ID departemen. |
| title | String | Tidak | Manajer Produk Senior | Jabatan karyawan dalam departemen. |
| extension | Object | Tidak | {"Hobby":"Travel","Age":"24"} | Atribut ekstensi. Beberapa atribut dapat dikonfigurasi. Maksimum 2000 karakter. Catatan - Hingga 10 atribut ekstensi dapat ditampilkan di perangkat seluler. - Sebelum menggunakan parameter ini, tambahkan atribut di DingTalk Admin Console > Pengaturan Kontak Internal > Kelola Bidang Anggota, lalu panggil API untuk menetapkan nilainya. Untuk detailnya, lihat Tentang parameter ekstensi di bawah. - Nilai bidang ini mendukung tipe tautan, dan tautan mendukung penggantian otomatis wildcard variabel. Wildcard yang saat ini didukung meliputi: userid dan corpid. Contoh: {"Hobby":"[Hobby](http://www.dingtalk.io?userid=#userid#&corpid=#corpid#)"} - Penting: Menambahkan atribut baru secara langsung akan menimpa nilai atribut yang ada. Ambil terlebih dahulu atribut yang ada, tambahkan atribut baru ke dalamnya, lalu lakukan pembaruan penuh. |
| senior_mode | Boolean | Tidak | false | Apakah mengaktifkan mode eksekutif. Default: false. - true: Aktifkan. Catatan - Ketika diaktifkan, nomor ponsel disembunyikan dari semua karyawan. - Karyawan biasa tidak dapat mengirim DING atau memulai panggilan bisnis DingTalk kepada pengguna tersebut. - Para eksekutif dapat saling mengirim DING dan memulai panggilan bisnis DingTalk. - false: Jangan aktifkan. |
| hired_date | Number | Tidak | 1597573616828 | Tanggal masuk kerja, sebagai Unix timestamp dalam milidetik. |
| manager_userid | String | Tidak | 001 | userId dari manajer langsung. |
| login_email | String | Tidak | test@xxx.com | Alamat email untuk masuk. Catatan Bidang ini hanya berlaku untuk akun email. Menetapkan bidang ini untuk akun non-email tidak berpengaruh. |
| dept_position_list | DeptPosition[] | Tidak | Informasi posisi dalam departemen. | |
| extension_i18n | Json | Tidak | {"Hobby": {"zh_CN": "Travel", "en_US": "Travel", "aJP": "Trip"}} | Nilai atribut ekstensi yang diinternasionalisasi. |
Contoh permintaan
curl -X POST "https://api.dingtalk.io/topapi/v2/user/create" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=1c016742-9383-4276-beb1-ebb375acc454' \
-d 'name=John' \
-d 'mobile=13800138000' \
-d 'dept_id_list=%5C%222%2C3%2C4%5C%22'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.setUserid("002");
req.setName("Test");
req.setSeniorMode(false);
req.setMobile("184806*****");
req.setTitle("Faculty");
req.setEmail("test@xx.com");
req.setOrgEmail("test@xxx.com");
req.setOrgEmailType("profession");
req.setDeptIdList("1");
ArrayList<OapiV2UserCreateRequest.DeptTitle> deptTitles = new ArrayList<>();
OapiV2UserCreateRequest.DeptTitle deptTitle = new OapiV2UserCreateRequest.DeptTitle();
deptTitle.setDeptId(1L);
deptTitle.setTitle("Test");
OapiV2UserCreateRequest.DeptTitle deptTitle1 = new OapiV2UserCreateRequest.DeptTitle();
deptTitle1.setDeptId(1L);
deptTitle1.setTitle("Specialist");
deptTitles.add(deptTitle);
deptTitles.add(deptTitle1);
req.setDeptTitleList(deptTitles);
req.setHideMobile(false);
req.setTelephone("010-8xxxxx6-2345");
req.setJobNumber("100828");
req.setHiredDate(1615219200000L);
req.setWorkPlace("Future Park");
req.setRemark("Remarks");
List<OapiV2UserCreateRequest.DeptOrder> deptOrderList = new ArrayList<OapiV2UserCreateRequest.DeptOrder>();
OapiV2UserCreateRequest.DeptOrder deptOrder = new OapiV2UserCreateRequest.DeptOrder();
deptOrder.setDeptId(1L);
deptOrder.setOrder(1L);
OapiV2UserCreateRequest.DeptOrder deptOrder1 = new OapiV2UserCreateRequest.DeptOrder();
deptOrder1.setDeptId(1L);
deptOrder1.setOrder(1L);
deptOrderList.add(deptOrder);
deptOrderList.add(deptOrder1);
req.setDeptOrderList(deptOrderList);
req.setExtension("{\"Hobby\":\"[Hobby](http://test.com?userid=#userid#&corpid=#corpid#)\"}");
req.setManagerUserid("001");
req.setLoginEmail("test@xxx.com");
OapiV2UserCreateResponse rsp = client.execute(req, "");
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiV2UserCreateRequest("https://api.dingtalk.io/topapi/v2/user/create")
req.userid="zhangsan"
req.name="John"
req.mobile="13800138000"
req.job_number="4"
req.title="Technical Director"
req.email="test@xxx.com"
req.org_email="test@xxx.com"
req.work_place="Future Park"
req.remark="Remarks"
req.dept_id_list="2,3,4"
req.check_user_protect=true
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiV2UserCreateRequest;
$req->setUserid("zhangsan");
$req->setName("John");
$req->setMobile("13800138000");
$req->setTelephone("010-86123456-2345");
$req->setTitle("Technical Director");
$req->setEmail("test@xxx.com");
$req->setWorkPlace("Future Park");
$req->setRemark("Remarks");
$req->setDeptIdList("\"2,3,4\"");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/v2/user/create");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/v2/user/create");
OapiV2UserCreateRequest req = new OapiV2UserCreateRequest();
req.Userid = "zhangsan";
req.Name = "John";
req.Mobile = "13800138000";
req.Title = "Technical Director";
req.Email = "test@xxx.com";
req.OrgEmail = "test@xxx.com";
req.WorkPlace = "Future Park";
req.Remark = "Remarks";
req.DeptIdList = "\"2,3,4\"";
OapiV2UserCreateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Respons
Isi respons
| Nama | Tipe | Contoh | Deskripsi |
|---|---|---|---|
| errcode | Number | 0 | Kode error. 0 menunjukkan berhasil. |
| errmsg | String | ok | Pesan error. |
| result | Object | Hasil yang dikembalikan. | |
| userid | String | zhangsan | ID Karyawan. |
| unionId | String | xxxx | ID unik karyawan. |
Contoh isi respons
{
"errcode":"0",
"result":{
"unionId":"xxxx",
"userid":"zhangsan"
},
"errmsg":"ok"
}
Kode error
Jika terjadi error saat memanggil API ini, lihat dokumen Kode error global untuk solusi berdasarkan pesan error.Tentang parameter ekstensi
Untuk menampilkan atribut pengguna yang dikonfigurasi di bidang extension, selesaikan langkah-langkah berikut.- Masuk ke DingTalk Admin Console.
- Klik Pengaturan Kontak Internal, lalu klik Kelola Bidang Anggota > Tambahkan Bidang Kustom.