DocuSign API: Bagaimana Mencari Sampul Surat Menggunakan Nilai Medan Tersuai?

Pengurusan Efisien Navigasi Sampul Surat dalam DocuSign API

Dalam landskap persaingan penyelesaian tandatangan digital, API DocuSign menonjol sebagai alat yang berkuasa untuk pembangun dan perniagaan untuk mengautomasikan aliran kerja. Satu cabaran biasa ialah mendapatkan semula sampul surat tertentu—istilah DocuSign untuk pakej dokumen—berdasarkan metadata tersuai. Keupayaan ini adalah penting untuk perusahaan yang mengendalikan sejumlah besar perjanjian, membolehkan carian yang disasarkan tanpa perlu menapis secara manual. Dari sudut pandangan perniagaan, penguasaan fungsi API sedemikian boleh menyelaraskan audit pematuhan, penjejakan jualan dan sokongan pelanggan, akhirnya mengurangkan kos operasi.

Membandingkan platform e-tandatangan dengan DocuSign atau Adobe Sign?

eSignGlobal menawarkan penyelesaian e-tandatangan yang lebih fleksibel dan kos efektif dengan pematuhan global, harga yang telus dan proses pendaftaran yang lebih pantas.

👉 Mulakan Percubaan Percuma

Memahami Sampul Surat dan Medan Tersuai dalam DocuSign API

Sampul surat DocuSign mewakili unit teras e-tandatangan, merangkumi dokumen, penerima dan medan tandatangan. Medan tersuai, juga dikenali sebagai medan teks atau label, membolehkan pengguna membenamkan metadata—seperti ID kontrak, nama pelanggan atau tag status—terus ke dalam sampul surat. Medan ini bukan sahaja untuk paparan; ia menyokong pertanyaan secara program, yang sangat berharga untuk integrasi dengan sistem CRM atau papan pemuka tersuai.

Dari sudut pandangan perniagaan, memanfaatkan medan tersuai untuk carian boleh meningkatkan tadbir urus data. Perusahaan dalam industri yang dikawal selia, seperti kewangan atau penjagaan kesihatan, boleh menggunakannya untuk menapis sampul surat berdasarkan penanda pematuhan, memastikan akses pantas semasa audit. API DocuSign, sebahagian daripada platform pembangunnya, menyokong fungsi ini melalui titik akhir RESTful, dengan peringkat harga seperti pelan Pertengahan (USD 3,600 setahun) menawarkan sehingga 100 sampul surat sebulan untuk operasi sedemikian.

Panduan Langkah demi Langkah: Mencari Sampul Surat Mengikut Nilai Medan Tersuai

Untuk mencari sampul surat menggunakan nilai medan tersuai melalui DocuSign API, anda memerlukan akaun pembangun yang aktif dan kelayakan API. Proses ini menganggap anda menggunakan eSignature REST API v2.1, standard semasa pada tahun 2025. Berikut ialah panduan neutral dan praktikal berdasarkan dokumentasi rasmi.

Prasyarat dan Persediaan

1. Dapatkan Akses API: Daftar untuk kotak pasir pembangun DocuSign di developer.docusign.com. Jana kunci integrasi (ID pelanggan) dan kunci untuk pengesahan OAuth. Untuk persekitaran pengeluaran, naik taraf ke pelan berbayar—pelan Permulaan (USD 600 setahun) sesuai untuk carian asas.

2. Tentukan Medan Tersuai: Semasa mencipta sampul surat, tambahkan medan tersuai melalui API. Gunakan objek customFields dalam definisi sampul surat. Contohnya:

   {
     "status": "sent",
     "emailSubject": "Perjanjian untuk Semakan",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   Ini membenamkan "CLI-12345" sebagai nilai yang boleh dicari di bawah medan "ClientID".

3. Pengesahan: Gunakan aliran JWT atau Auth Code Grant. Contoh permintaan JWT dalam Python (menggunakan pustaka requests) adalah seperti 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"]
   

   Gantikan ruang letak dengan kelayakan anda. Token ini digunakan untuk mengesahkan panggilan API berikutnya.

Melaksanakan Carian

Titik akhir utama ialah GET /accounts/{accountId}/envelopes/search, tetapi untuk penapisan medan tersuai, gabungkan parameter pertanyaan atau gunakan GET /envelopes yang lebih fleksibel dengan kriteria carian. API carian DocuSign membenarkan pertanyaan mengikut medan tersuai melalui parameter searchText, yang memadankan metadata sampul surat, termasuk nilai tersuai.

• Titik Akhir Carian Asas: Gunakan GET /accounts/{accountId}/envelopes?search_text={value}. Ini mengimbas subjek, nama dan medan tersuai sampul surat.

  Untuk padanan medan tersuai yang tepat, gunakan parameter query dalam carian lanjutan. Walau bagaimanapun, pertanyaan medan tersuai langsung memerlukan Envelopes: listStatusChanges atau keizinan yang 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"
  

  Petikan respons:

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

• Penapisan Lanjutan Menggunakan Medan Tersuai: Untuk carian sampul surat tertentu, dapatkan semula sampul surat dalam julat tarikh atau status terlebih dahulu, kemudian tapis di bahagian klien. DocuSign mengesyorkan menggabungkan parameter fromDate dan toDate dengan search_text untuk kecekapan. Jika volum anda melebihi kuota (cth., 100 sampul surat sebulan untuk pelan Pertengahan), pertimbangkan untuk menaik taraf kepada Lanjutan (USD 5,760 setahun) untuk keupayaan pukal.

  Dalam kod, huraikan respons untuk memadankan nilai medan tersuai 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))
  

Amalan Terbaik dan Had

• Kuota dan Kos: Carian dikira dalam had API sampul surat. Melebihi akan menimbulkan caj lebihan atau memerlukan penyesuaian Perusahaan.
• Keselamatan: Sentiasa gunakan HTTPS dan kawalan akses berasaskan peranan untuk mengelakkan pertanyaan yang tidak dibenarkan.
• Pengendalian Ralat: Isu biasa termasuk 401 (token tidak sah) atau 400 (pertanyaan tidak sah). Log respons untuk penyahpepijatan.
• Kebolehskalaan: Untuk carian volum tinggi, berintegrasi dengan webhook Connect DocuSign untuk menolak kemas kini, mengurangkan keperluan pengundian.

Fungsi API ini meletakkan DocuSign sebagai peneraju dalam pematuhan automasi, walaupun perusahaan harus menilai jumlah kos, termasuk tambahan seperti pengesahan identiti.

DocuSign: Peneraju Pasaran dalam Penyelesaian E-Tandatangan

DocuSign telah menjadi perintis dalam e-tandatangan sejak 2004, menawarkan alat pengurusan dokumen yang komprehensif. Platform e-tandatangannya termasuk pelan daripada Peribadi (USD 120 setahun) hingga Business Pro (USD 480/pengguna setahun), dengan akses API melalui pelan pembangun yang berasingan. Ciri utama termasuk templat, penghantaran pukal dan integrasi dengan lebih 400 aplikasi. Untuk keperluan lanjutan, Pengurusan Perjanjian Pintar (IAM) DocuSign menggabungkan CLM (Pengurusan Kitaran Hayat Kontrak) dengan cerapan dipacu AI, mengautomasikan semakan dan penilaian risiko. IAM sesuai untuk perusahaan, walaupun harga adalah tersuai dan mungkin meningkat dengan bilangan tempat duduk dan sampul surat.

Adobe Sign: Integrasi Berkuasa untuk Aliran Kerja Perusahaan

Adobe Sign, sebahagian daripada Adobe Document Cloud, cemerlang dalam integrasi yang lancar dengan alat PDF dan suite kreatif. Harga bermula pada sekitar USD 10/pengguna sebulan untuk individu, berkembang kepada pelan tersuai perusahaan. Ia menyokong medan tersuai dan carian API yang serupa dengan DocuSign, menggunakan titik akhir seperti /agreements untuk menanyakan metadata. Kelebihan termasuk hubungan ekosistem Adobe yang kukuh dan pematuhan global, tetapi fungsi API lanjutan mungkin memerlukan pelesenan tambahan. Perusahaan menghargai tumpuannya pada penciptaan dokumen di samping tandatangan.

eSignGlobal: Penyelesaian Tersuai untuk APAC dan Pematuhan Global

eSignGlobal menonjol sebagai pemain khusus, terutamanya di rantau Asia Pasifik (APAC), di mana peraturan e-tandatangan berpecah-belah, berstandard tinggi dan dikawal ketat. Tidak seperti rangka kerja ESIGN/UETA AS atau eIDAS Eropah—yang bergantung pada pengesahan e-mel atau pengisytiharan kendiri—APAC memerlukan standard integrasi ekosistem. Ini melibatkan gandingan perkakasan/tahap API yang mendalam dengan identiti digital kerajaan kepada perniagaan (G2B), meningkatkan halangan teknologi dengan ketara lebih tinggi daripada model Barat. eSignGlobal menangani ini dengan meliputi pematuhan di 100 negara dan wilayah global arus perdana, dengan kelebihan APAC melalui pusat data tempatan di Hong Kong dan Singapura. Ia menyokong integrasi lancar dengan iAM Smart Hong Kong dan Singpass Singapura untuk pengesahan identiti yang teguh. Harga adalah kompetitif, dengan pelan Essential pada USD 299 setahun (bersamaan dengan kira-kira USD 16.6 sebulan secara tahunan), membenarkan sehingga 100 dokumen yang ditandatangani, tempat duduk pengguna tanpa had dan pengesahan kod akses—semuanya berdasarkan asas pematuhan, kos efektif yang lebih rendah daripada banyak pesaing sambil mengekalkan kesahan undang-undang.

Mencari alternatif yang lebih pintar daripada DocuSign?

eSignGlobal menawarkan penyelesaian e-tandatangan yang lebih fleksibel dan kos efektif dengan pematuhan global, harga yang telus dan proses pendaftaran yang lebih pantas.

👉 Mulakan Percubaan Percuma

HelloSign (Dropbox Sign): Penyelesaian Mudah untuk SMB

HelloSign, kini Dropbox Sign, mengutamakan antara muka mesra pengguna untuk perniagaan kecil dan sederhana (SMB). Versi percuma membenarkan sehingga tiga dokumen sebulan, dengan pelan berbayar bermula pada USD 15 sebulan. APInya menyokong carian sampul surat melalui medan tersuai, menggunakan titik akhir seperti /templates dan /signatures, walaupun tidak sehalus DocuSign. Sesuai untuk integrasi pantas dengan Dropbox, tumpuannya adalah pada kemudahan penggunaan dan bukannya penyesuaian peringkat perusahaan.

Gambaran Keseluruhan Perbandingan Platform E-Tandatangan

Jadual ini menyerlahkan pertukaran neutral; pilihan bergantung pada keperluan serantau dan skala.

Ringkasnya, walaupun API DocuSign memperkasakan carian sampul surat yang tepat, meneroka alternatif boleh mengoptimumkan untuk pasaran tertentu. Untuk pematuhan serantau, eSignGlobal menawarkan pilihan yang seimbang sebagai alternatif DocuSign.