DocuSign API: Làm thế nào để tìm kiếm phong bì bằng giá trị trường tùy chỉnh?

Quản lý hiệu quả điều hướng phong bì trong DocuSign API

Trong bối cảnh cạnh tranh của các giải pháp chữ ký số, DocuSign API nổi bật như một công cụ mạnh mẽ cho các nhà phát triển và doanh nghiệp để tự động hóa quy trình làm việc. Một thách thức phổ biến là truy xuất các phong bì cụ thể—thuật ngữ của DocuSign cho các gói tài liệu—dựa trên siêu dữ liệu tùy chỉnh. Khả năng này rất quan trọng đối với các doanh nghiệp xử lý số lượng lớn thỏa thuận, cho phép tìm kiếm có mục tiêu mà không cần sàng lọc thủ công. Từ góc độ kinh doanh, việc nắm vững các khả năng API như vậy có thể hợp lý hóa kiểm toán tuân thủ, theo dõi bán hàng và hỗ trợ khách hàng, cuối cùng là giảm chi phí hoạt động.

Đang so sánh các nền tảng chữ ký điện tử với DocuSign hoặc Adobe Sign?

eSignGlobal cung cấp các giải pháp chữ ký điện tử linh hoạt và tiết kiệm chi phí hơn, với tuân thủ toàn cầu, giá cả minh bạch và quy trình tham gia nhanh hơn.

👉 Bắt đầu dùng thử miễn phí

Hiểu về phong bì và trường tùy chỉnh trong DocuSign API

Phong bì DocuSign đại diện cho đơn vị cốt lõi của chữ ký điện tử, đóng gói tài liệu, người nhận và các trường chữ ký. Các trường tùy chỉnh, còn được gọi là trường văn bản hoặc trường nhãn, cho phép người dùng nhúng trực tiếp siêu dữ liệu—chẳng hạn như ID hợp đồng, tên khách hàng hoặc thẻ trạng thái—vào phong bì. Các trường này không chỉ để hiển thị; chúng hỗ trợ các truy vấn theo chương trình, điều này rất có giá trị cho việc tích hợp với hệ thống CRM hoặc bảng điều khiển tùy chỉnh.

Từ góc độ kinh doanh, việc sử dụng các trường tùy chỉnh để tìm kiếm có thể nâng cao quản trị dữ liệu. Các doanh nghiệp trong các ngành được quản lý, chẳng hạn như tài chính hoặc chăm sóc sức khỏe, có thể sử dụng chúng để lọc phong bì dựa trên các dấu tuân thủ, đảm bảo truy cập nhanh chóng trong quá trình kiểm toán. DocuSign API, một phần của nền tảng nhà phát triển của nó, hỗ trợ chức năng này thông qua các điểm cuối RESTful, với các cấp giá như gói Intermediate (3.600 đô la mỗi năm) cung cấp tối đa 100 phong bì mỗi tháng cho các hoạt động như vậy.

Hướng dẫn từng bước: Tìm kiếm phong bì theo giá trị trường tùy chỉnh

Để tìm kiếm phong bì bằng giá trị trường tùy chỉnh thông qua DocuSign API, bạn cần có tài khoản nhà phát triển đang hoạt động và thông tin xác thực API. Quy trình này giả định bạn đang sử dụng eSignature REST API v2.1, tiêu chuẩn hiện tại vào năm 2025. Dưới đây là hướng dẫn trung lập, thực tế dựa trên tài liệu chính thức.

Điều kiện tiên quyết và thiết lập

1. Nhận quyền truy cập API: Đăng ký hộp cát nhà phát triển DocuSign tại developer.docusign.com. Tạo khóa tích hợp (ID ứng dụng khách) và khóa bí mật để xác thực OAuth. Đối với môi trường sản xuất, hãy nâng cấp lên gói trả phí—gói Starter (600 đô la mỗi năm) phù hợp cho tìm kiếm cơ bản.

2. Xác định các trường tùy chỉnh: Khi tạo phong bì, hãy thêm các trường tùy chỉnh thông qua API. Sử dụng đối tượng customFields trong định nghĩa phong bì. Ví dụ:

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

   Điều này nhúng “CLI-12345” làm giá trị có thể tìm kiếm dưới trường “ClientID”.

3. Xác thực: Sử dụng quy trình JWT hoặc Auth Code Grant. Một yêu cầu JWT mẫu trong Python (sử dụng thư viện requests) như sau:

   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"]
   

   Thay thế các trình giữ chỗ bằng thông tin xác thực của bạn. Mã thông báo này được sử dụng để xác thực các lệnh gọi API tiếp theo.

Thực hiện tìm kiếm

Điểm cuối quan trọng là GET /accounts/{accountId}/envelopes/search, nhưng để lọc trường tùy chỉnh, hãy kết hợp các tham số truy vấn hoặc sử dụng GET /envelopes linh hoạt hơn với tiêu chí tìm kiếm. DocuSign’s Search API cho phép truy vấn theo trường tùy chỉnh thông qua tham số searchText, khớp với siêu dữ liệu phong bì, bao gồm các giá trị tùy chỉnh.

• Điểm cuối tìm kiếm cơ bản: Sử dụng GET /accounts/{accountId}/envelopes?search_text={value}. Điều này quét các chủ đề, tên và trường tùy chỉnh của phong bì.

  Để khớp trường tùy chỉnh chính xác, hãy sử dụng tham số query trong tìm kiếm nâng cao. Tuy nhiên, truy vấn trường tùy chỉnh trực tiếp yêu cầu Envelopes: listStatusChanges hoặc các quyền tương tự.

  Yêu cầu cURL mẫu:

  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"
  

  Đoạn phản hồi:

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

• Lọc nâng cao bằng trường tùy chỉnh: Để tìm kiếm phong bì cụ thể, trước tiên hãy truy xuất phong bì trong phạm vi ngày hoặc trạng thái, sau đó lọc ở phía máy khách. DocuSign khuyên bạn nên kết hợp các tham số fromDate và toDate với search_text để tăng hiệu quả. Nếu khối lượng của bạn vượt quá hạn ngạch (ví dụ: 100 phong bì mỗi tháng trong gói Intermediate), hãy cân nhắc nâng cấp lên Advanced (5.760 đô la mỗi năm) để có các khả năng hàng loạt.

  Trong mã, hãy phân tích cú pháp phản hồi để khớp với các giá trị trường tùy chỉnh chính xác:

  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))
  

Các phương pháp hay nhất và hạn chế

• Hạn ngạch và chi phí: Tìm kiếm được tính vào giới hạn API phong bì. Vượt quá sẽ phát sinh phí vượt mức hoặc yêu cầu tùy chỉnh Enterprise.
• Bảo mật: Luôn sử dụng HTTPS và quyền truy cập dựa trên vai trò để ngăn chặn các truy vấn trái phép.
• Xử lý lỗi: Các vấn đề phổ biến bao gồm 401 (mã thông báo không hợp lệ) hoặc 400 (truy vấn không hợp lệ). Ghi nhật ký phản hồi để gỡ lỗi.
• Khả năng mở rộng: Đối với tìm kiếm khối lượng lớn, hãy tích hợp với webhook Connect của DocuSign để đẩy các bản cập nhật, giảm nhu cầu thăm dò ý kiến.

Khả năng API này định vị DocuSign là người dẫn đầu về tuân thủ tự động, mặc dù các doanh nghiệp nên đánh giá tổng chi phí, bao gồm các tiện ích bổ sung như xác thực danh tính.

DocuSign: Người dẫn đầu thị trường về giải pháp chữ ký điện tử

DocuSign là người tiên phong về chữ ký điện tử kể từ năm 2004, cung cấp các công cụ quản lý tài liệu toàn diện. Nền tảng eSignature của nó bao gồm các gói từ Personal (120 đô la mỗi năm) đến Business Pro (480 đô la mỗi người dùng mỗi năm), với quyền truy cập API thông qua các gói nhà phát triển riêng biệt. Các tính năng chính bao gồm mẫu, gửi hàng loạt và tích hợp với hơn 400 ứng dụng. Đối với các nhu cầu nâng cao, Intelligent Agreement Management (IAM) của DocuSign kết hợp CLM (Quản lý vòng đời hợp đồng) với thông tin chi tiết do AI cung cấp, tự động hóa các sửa đổi và đánh giá rủi ro. IAM phù hợp với các doanh nghiệp, mặc dù giá cả là tùy chỉnh và có thể tăng lên với số lượng chỗ ngồi và phong bì.

Adobe Sign: Tích hợp mạnh mẽ cho quy trình làm việc của doanh nghiệp

Adobe Sign, một phần của Adobe Document Cloud, vượt trội trong việc tích hợp liền mạch với các công cụ PDF và bộ sáng tạo. Giá bắt đầu từ khoảng 10 đô la mỗi người dùng mỗi tháng cho cá nhân, mở rộng đến các gói tùy chỉnh cho doanh nghiệp. Nó hỗ trợ các trường tùy chỉnh và tìm kiếm API tương tự như DocuSign, sử dụng các điểm cuối như /agreements để truy vấn siêu dữ liệu. Ưu điểm bao gồm kết nối hệ sinh thái Adobe mạnh mẽ và tuân thủ toàn cầu, nhưng các khả năng API nâng cao có thể yêu cầu cấp phép bổ sung. Các doanh nghiệp coi trọng trọng tâm của nó vào việc tạo tài liệu bên cạnh chữ ký.

eSignGlobal: Giải pháp tùy chỉnh cho APAC và tuân thủ toàn cầu

eSignGlobal nổi bật như một người chơi chuyên biệt, đặc biệt là ở khu vực Châu Á Thái Bình Dương (APAC), nơi các quy định về chữ ký điện tử bị phân mảnh, có tiêu chuẩn cao và được quản lý chặt chẽ. Không giống như các khuôn khổ của Hoa Kỳ ESIGN/UETA hoặc Châu Âu eIDAS—dựa vào xác minh email hoặc tự khai báo—APAC yêu cầu các tiêu chuẩn tích hợp hệ sinh thái. Điều này liên quan đến việc kết nối sâu cấp phần cứng/API với danh tính số của chính phủ với doanh nghiệp (G2B), làm tăng đáng kể các rào cản kỹ thuật cao hơn các mô hình phương Tây. eSignGlobal giải quyết vấn đề này bằng cách bao gồm tuân thủ ở hơn 100 quốc gia và khu vực toàn cầu chính, với lợi thế ở APAC thông qua các trung tâm dữ liệu cục bộ ở Hồng Kông và Singapore. Nó hỗ trợ tích hợp liền mạch với iAM Smart của Hồng Kông và Singpass của Singapore để xác thực mạnh mẽ. Giá cả cạnh tranh, với gói Essential ở mức 299 đô la mỗi năm (tương đương hàng năm khoảng 16,6 đô la mỗi tháng), cho phép tối đa 100 tài liệu đã ký, số lượng chỗ ngồi người dùng không giới hạn và xác minh mã truy cập—tất cả đều dựa trên nền tảng tuân thủ, hiệu quả về chi phí, thấp hơn nhiều đối thủ cạnh tranh trong khi vẫn duy trì hiệu lực pháp lý.

Đang tìm kiếm một giải pháp thay thế thông minh hơn cho DocuSign?

eSignGlobal cung cấp các giải pháp chữ ký điện tử linh hoạt và tiết kiệm chi phí hơn, với tuân thủ toàn cầu, giá cả minh bạch và quy trình tham gia nhanh hơn.

👉 Bắt đầu dùng thử miễn phí

HelloSign (Dropbox Sign): Giải pháp đơn giản cho SMB

HelloSign, hiện là Dropbox Sign, ưu tiên giao diện thân thiện với người dùng cho các doanh nghiệp vừa và nhỏ. Phiên bản miễn phí cho phép tối đa ba tài liệu mỗi tháng, với các gói trả phí bắt đầu từ 15 đô la mỗi tháng. API của nó hỗ trợ tìm kiếm phong bì thông qua các trường tùy chỉnh, sử dụng các điểm cuối như /templates và /signatures, mặc dù không chi tiết như DocuSign. Phù hợp để tích hợp nhanh chóng với Dropbox, trọng tâm là dễ sử dụng hơn là tùy chỉnh cấp doanh nghiệp.

Tổng quan so sánh về các nền tảng chữ ký điện tử

Bảng này làm nổi bật các đánh đổi trung lập; lựa chọn phụ thuộc vào nhu cầu khu vực và quy mô.

Tóm lại, mặc dù API của DocuSign cho phép tìm kiếm phong bì chính xác, nhưng việc khám phá các giải pháp thay thế có thể tối ưu hóa cho các thị trường cụ thể. Đối với tuân thủ khu vực, eSignGlobal cung cấp các tùy chọn cân bằng như một giải pháp thay thế cho DocuSign.