DocuSign API: Bagaimana Cara Mencari Amplop Berdasarkan Nilai Bidang Kustom?

Manajemen Efisien Navigasi Amplop di DocuSign API

Dalam lanskap kompetitif solusi tanda tangan digital, API DocuSign menonjol sebagai alat yang ampuh bagi pengembang dan bisnis untuk mengotomatiskan alur kerja. Tantangan umum adalah mengambil amplop tertentu—istilah DocuSign untuk paket dokumen—berdasarkan metadata khusus. Kemampuan ini sangat penting bagi perusahaan yang menangani volume perjanjian yang tinggi, memungkinkan pencarian yang ditargetkan tanpa penyaringan manual. Dari sudut pandang bisnis, penguasaan kemampuan API semacam itu dapat menyederhanakan audit kepatuhan, pelacakan penjualan, dan dukungan pelanggan, yang pada akhirnya mengurangi biaya operasional.

Membandingkan platform tanda tangan elektronik dengan DocuSign atau Adobe Sign?

eSignGlobal menawarkan solusi tanda tangan elektronik yang lebih fleksibel dan hemat biaya dengan kepatuhan global, harga transparan, dan proses orientasi yang lebih cepat.

👉 Mulai Uji Coba Gratis

Memahami Amplop dan Bidang Kustom di DocuSign API

Amplop DocuSign mewakili unit inti tanda tangan elektronik, yang merangkum dokumen, penerima, dan bidang tanda tangan. Bidang kustom, juga dikenal sebagai bidang teks atau label, memungkinkan pengguna untuk menyematkan metadata langsung ke dalam amplop, seperti ID kontrak, nama pelanggan, atau label status. Bidang-bidang ini lebih dari sekadar tampilan; mereka mendukung kueri terprogram, yang sangat berharga untuk integrasi dengan sistem CRM atau dasbor khusus.

Dari sudut pandang bisnis, memanfaatkan bidang kustom untuk pencarian dapat meningkatkan tata kelola data. Perusahaan di industri yang diatur, seperti keuangan atau perawatan kesehatan, dapat menggunakannya untuk memfilter amplop berdasarkan penanda kepatuhan, memastikan akses cepat selama audit. API DocuSign, sebagai bagian dari platform pengembangnya, mendukung fungsionalitas ini melalui titik akhir RESTful, dengan tingkatan harga seperti paket Intermediate (US$3.600 per tahun) yang menyediakan hingga 100 amplop per bulan untuk operasi semacam itu.

Panduan Langkah demi Langkah: Mencari Amplop Berdasarkan Nilai Bidang Kustom

Untuk mencari amplop menggunakan nilai bidang kustom melalui DocuSign API, Anda memerlukan akun pengembang aktif dan kredensial API. Proses ini mengasumsikan Anda menggunakan eSignature REST API v2.1, standar saat ini pada tahun 2025. Berikut adalah panduan netral dan praktis berdasarkan dokumentasi resmi.

Prasyarat dan Pengaturan

1. Dapatkan Akses API: Daftar ke kotak pasir pengembang DocuSign di developer.docusign.com. Hasilkan Kunci Integrasi (ID Klien) dan kunci untuk otentikasi OAuth. Untuk lingkungan produksi, tingkatkan ke paket berbayar—paket Starter (US$600 per tahun) cocok untuk pencarian dasar.

2. Tentukan Bidang Kustom: Saat membuat amplop, tambahkan bidang kustom melalui API. Gunakan objek customFields dalam definisi amplop. Contoh:

   {
     "status": "sent",
     "emailSubject": "Agreement for Review",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   Ini menyematkan "CLI-12345" sebagai nilai yang dapat dicari di bawah bidang "ClientID".

3. Otentikasi: Gunakan alur JWT atau Auth Code Grant. Contoh permintaan JWT di Python (menggunakan pustaka requests) adalah sebagai berikut:

   import requests
   import jwt
   import time
   
   def get_jwt_token(integration_key, user_id, rsa_key, account_id):
       claim = {
           "iss": integration_key,
           "sub": user_id,
           "aud": "account-docusigncom",
           "iat": int(time.time()),
           "exp": int(time.time()) + 3600,
           "scope": "signature impersonation"
       }
       token = jwt.encode(claim, rsa_key, algorithm='RS256')
       response = requests.post(
           "https://account-docusign.com/oauth/token",
           headers={"Authorization": f"Bearer {token}"},
           data={
               "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
               "assertion": token
           }
       )
       return response.json()["access_token"]
   

   Ganti placeholder dengan kredensial Anda. Token ini digunakan untuk mengotentikasi panggilan API berikutnya.

Melakukan Pencarian

Titik akhir utama adalah GET /accounts/{accountId}/envelopes/search, tetapi untuk pemfilteran bidang kustom, gabungkan parameter kueri atau gunakan GET /envelopes yang lebih fleksibel dengan kriteria pencarian. API pencarian DocuSign memungkinkan kueri berdasarkan bidang kustom melalui parameter searchText, yang mencocokkan metadata amplop, termasuk nilai kustom.

• Titik Akhir Pencarian Dasar: Gunakan GET /accounts/{accountId}/envelopes?search_text={value}. Ini memindai subjek, nama, dan bidang kustom amplop.

  Untuk pencocokan bidang kustom yang tepat, manfaatkan parameter query dalam pencarian lanjutan. Namun, kueri bidang kustom langsung memerlukan izin Envelopes: listStatusChanges atau serupa.

  Contoh permintaan cURL:

  curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes?search_text=CLI-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
  

  Cuplikan respons:

  {
    "envelopes": [
      {
        "envelopeId": "abc-123-def",
        "status": "completed",
        "customFields": {
          "textCustomFields": [
            {
              "name": "ClientID",
              "value": "CLI-12345"
            }
          ]
        }
      }
    ]
  }
  

• Pemfilteran Tingkat Lanjut dengan Bidang Kustom: Untuk pencarian amplop tertentu, pertama-tama ambil amplop dalam rentang tanggal atau status, lalu filter di sisi klien. DocuSign merekomendasikan untuk menggabungkan parameter fromDate dan toDate dengan search_text untuk meningkatkan efisiensi. Jika volume Anda melebihi kuota (misalnya, 100 amplop per bulan untuk paket Intermediate), pertimbangkan untuk meningkatkan ke Advanced (US$5.760 per tahun) untuk kemampuan batch.

  Dalam kode, uraikan respons untuk mencocokkan nilai bidang kustom yang tepat:

  import json
  
  response = requests.get(
      f"https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json"
      },
      params={"search_text": "CLI-12345", "from_date": "2025-01-01T00:00:00Z"}
  )
  envelopes = response.json()["envelopeSummary"]["envelopes"]
  matching_envelopes = [
      env for env in envelopes
      if any(cf["name"] == "ClientID" and cf["value"] == "CLI-12345" for cf in env.get("customFields", {}).get("textCustomFields", []))
  ]
  print(json.dumps(matching_envelopes, indent=2))
  

Praktik Terbaik dan Batasan

• Kuota dan Biaya: Pencarian dihitung terhadap batasan API amplop. Melebihi akan menimbulkan biaya tambahan atau memerlukan penyesuaian Enterprise.
• Keamanan: Selalu gunakan HTTPS dan kontrol akses berbasis peran untuk mencegah kueri yang tidak sah.
• Penanganan Kesalahan: Masalah umum termasuk 401 (token tidak valid) atau 400 (kueri tidak valid). Catat respons untuk debugging.
• Skalabilitas: Untuk pencarian volume tinggi, integrasikan dengan webhook Connect DocuSign untuk pembaruan push, mengurangi kebutuhan polling.

Kemampuan API ini memposisikan DocuSign sebagai pemimpin dalam otomatisasi kepatuhan, meskipun bisnis harus mengevaluasi total biaya, termasuk add-on seperti otentikasi.

DocuSign: Pemimpin Pasar dalam Solusi Tanda Tangan Elektronik

DocuSign telah menjadi pelopor dalam tanda tangan elektronik sejak tahun 2004, menawarkan alat manajemen dokumen yang komprehensif. Platform eSignature-nya mencakup paket mulai dari Personal (US$120 per tahun) hingga Business Pro (US$480 per pengguna per tahun), dengan akses API melalui paket pengembang terpisah. Fitur utama termasuk templat, pengiriman massal, dan integrasi dengan 400+ aplikasi. Untuk kebutuhan tingkat lanjut, Intelligent Agreement Management (IAM) DocuSign menggabungkan CLM (Manajemen Siklus Hidup Kontrak) dengan wawasan berbasis AI, mengotomatiskan revisi dan penilaian risiko. IAM cocok untuk perusahaan, meskipun harganya khusus dan dapat meningkat dengan jumlah kursi dan amplop.

Adobe Sign: Integrasi yang Kuat untuk Alur Kerja Perusahaan

Adobe Sign, bagian dari Adobe Document Cloud, unggul dalam integrasi tanpa batas dengan alat PDF dan suite kreatif. Harga mulai dari sekitar US$10/pengguna per bulan untuk individu, berkembang ke paket khusus perusahaan. Ini mendukung bidang kustom dan pencarian API yang mirip dengan DocuSign, menggunakan titik akhir seperti /agreements untuk mengkueri metadata. Keuntungan termasuk koneksi ekosistem Adobe yang kuat dan kepatuhan global, tetapi kemampuan API tingkat lanjut mungkin memerlukan lisensi tambahan. Perusahaan menghargai fokusnya pada pembuatan dokumen di samping tanda tangan.

eSignGlobal: Solusi yang Disesuaikan untuk APAC dan Kepatuhan Global

eSignGlobal menonjol sebagai pemain khusus, terutama di wilayah Asia-Pasifik (APAC), di mana peraturan tanda tangan elektronik terfragmentasi, berstandar tinggi, dan diatur secara ketat. Tidak seperti kerangka kerja ESIGN/UETA AS atau eIDAS Eropa—yang bergantung pada verifikasi email atau deklarasi sendiri—APAC memerlukan standar integrasi ekosistem. Ini melibatkan koneksi mendalam tingkat perangkat keras/API dengan identitas digital pemerintah-ke-bisnis (G2B), yang secara signifikan meningkatkan hambatan teknologi di atas model Barat. eSignGlobal mengatasi hal ini dengan cakupan kepatuhan di 100 negara dan wilayah global utama, dengan keunggulan APAC melalui pusat data lokal di Hong Kong dan Singapura. Ini mendukung integrasi tanpa batas dengan iAM Smart Hong Kong dan Singpass Singapura untuk otentikasi yang kuat. Harga kompetitif, dengan paket Essential seharga US$299 per tahun (setara dengan sekitar US$16,6 per bulan yang di-annualisasi), memungkinkan hingga 100 dokumen yang ditandatangani, kursi pengguna tak terbatas, dan verifikasi kode akses—semuanya berdasarkan fondasi kepatuhan, hemat biaya, di bawah banyak pesaing sambil mempertahankan kekuatan hukum.

Mencari alternatif yang lebih cerdas daripada DocuSign?

eSignGlobal menawarkan solusi tanda tangan elektronik yang lebih fleksibel dan hemat biaya dengan kepatuhan global, harga transparan, dan proses orientasi yang lebih cepat.

👉 Mulai Uji Coba Gratis

HelloSign (Dropbox Sign): Solusi yang Disederhanakan untuk UKM

HelloSign, sekarang Dropbox Sign, memprioritaskan antarmuka yang ramah pengguna untuk usaha kecil dan menengah (UKM). Versi gratis tersedia hingga tiga dokumen per bulan, dengan paket berbayar mulai dari US$15 per bulan. API-nya mendukung pencarian amplop melalui bidang kustom, menggunakan titik akhir seperti /templates dan /signatures, meskipun tidak sehalus DocuSign. Cocok untuk integrasi cepat dengan Dropbox, dengan fokus pada kemudahan penggunaan daripada penyesuaian tingkat perusahaan.

Ikhtisar Perbandingan Platform Tanda Tangan Elektronik

Tabel ini menyoroti trade-off netral; pilihan bergantung pada kebutuhan dan skala regional.

Singkatnya, sementara API DocuSign memberdayakan pencarian amplop yang tepat, menjelajahi alternatif dapat mengoptimalkan untuk pasar tertentu. Untuk kepatuhan regional, eSignGlobal menawarkan opsi seimbang sebagai alternatif DocuSign.