API DocuSign: Como Pesquisar Envelopes por Valores de Campos Personalizados?

Gerenciamento Eficaz da Navegação de Envelopes na API do DocuSign

No cenário competitivo de soluções de assinatura digital, a API do DocuSign se destaca como uma ferramenta poderosa para desenvolvedores e empresas automatizarem fluxos de trabalho. Um desafio comum é recuperar envelopes específicos – o termo do DocuSign para pacotes de documentos – com base em metadados personalizados. Essa capacidade é crucial para empresas que lidam com um grande volume de acordos, permitindo pesquisas direcionadas sem a necessidade de triagem manual. De uma perspectiva de negócios, dominar essa funcionalidade da API pode simplificar auditorias de conformidade, rastreamento de vendas e suporte ao cliente, reduzindo, em última análise, os custos operacionais.

Comparando plataformas de assinatura eletrônica com DocuSign ou Adobe Sign?

eSignGlobal oferece uma solução de assinatura eletrônica mais flexível e econômica, com conformidade global, preços transparentes e um processo de integração mais rápido.

👉 Comece um teste gratuito

Entendendo Envelopes e Campos Personalizados na API do DocuSign

Um envelope do DocuSign representa a unidade central de assinatura eletrônica, encapsulando documentos, destinatários e campos de assinatura. Campos personalizados, também conhecidos como campos de texto ou rótulos, permitem que os usuários incorporem metadados diretamente no envelope, como IDs de contrato, nomes de clientes ou rótulos de status. Esses campos não são apenas para exibição; eles permitem consultas programáticas, o que é inestimável para integrações com sistemas CRM ou painéis personalizados.

De uma perspectiva de negócios, utilizar campos personalizados para pesquisa pode aumentar a governança de dados. Empresas em setores regulamentados, como finanças ou saúde, podem usá-los para filtrar envelopes com base em marcadores de conformidade, garantindo acesso rápido durante as auditorias. A API do DocuSign, parte de sua plataforma de desenvolvedores, suporta essa funcionalidade por meio de endpoints RESTful, com planos de preços como o plano Intermediate (US$ 3.600 por ano) oferecendo até 100 envelopes por mês para tais operações.

Guia Passo a Passo: Pesquisando Envelopes por Valores de Campos Personalizados

Para pesquisar envelopes por valores de campos personalizados usando a API do DocuSign, você precisa de uma conta de desenvolvedor ativa e credenciais de API. Este processo assume que você está usando a eSignature REST API v2.1, o padrão atual em 2025. Aqui está um passo a passo neutro e prático baseado na documentação oficial.

Pré-requisitos e Configuração

1. Obtenha Acesso à API: Inscreva-se em uma sandbox de desenvolvedor do DocuSign em developer.docusign.com. Gere uma chave de integração (ID do cliente) e uma chave secreta para autenticação OAuth. Para ambientes de produção, atualize para um plano pago – o plano Starter (US$ 600 por ano) é adequado para pesquisas básicas.

2. Defina Campos Personalizados: Ao criar um envelope, adicione campos personalizados por meio da API. Use o objeto customFields na definição do envelope. Por exemplo:

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

   Isso incorpora “CLI-12345” como um valor pesquisável no campo “ClientID”.

3. Autenticação: Use o fluxo JWT ou Auth Code Grant. Um exemplo de solicitação JWT em Python (usando a biblioteca requests) é o seguinte:

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

   Substitua os espaços reservados por suas credenciais. Este token é usado para autenticar chamadas de API subsequentes.

Executando a Pesquisa

O endpoint chave é GET /accounts/{accountId}/envelopes/search, mas para filtragem de campos personalizados, combine parâmetros de consulta ou use o mais flexível GET /envelopes com critérios de pesquisa. A API de pesquisa do DocuSign permite consultar por campos personalizados por meio do parâmetro searchText, que corresponde aos metadados do envelope, incluindo valores personalizados.

• Endpoint de Pesquisa Básico: Use GET /accounts/{accountId}/envelopes?search_text={value}. Isso examina o assunto, nome e campos personalizados do envelope.

  Para correspondência precisa de campos personalizados, utilize o parâmetro query em pesquisa avançada. No entanto, consultas diretas de campos personalizados exigem Envelopes: listStatusChanges ou permissões semelhantes.

  Exemplo de solicitação 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"
  

  Snippet de resposta:

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

• Filtragem Avançada com Campos Personalizados: Para pesquisas específicas de envelopes, primeiro recupere envelopes dentro de um intervalo de datas ou status e, em seguida, filtre no lado do cliente. O DocuSign recomenda combinar os parâmetros fromDate e toDate com search_text para maior eficiência. Se seus volumes excederem as cotas (por exemplo, 100 envelopes por mês no plano Intermediate), considere atualizar para Advanced (US$ 5.760 por ano) para recursos de lote.

  No código, analise a resposta para corresponder aos valores exatos dos campos personalizados:

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

Melhores Práticas e Limitações

• Cotas e Custos: As pesquisas contam para os limites da API de envelope. Exceder incorrerá em taxas de uso excedente ou exigirá personalização Enterprise.
• Segurança: Sempre use HTTPS e controle de acesso baseado em função para evitar consultas não autorizadas.
• Tratamento de Erros: Problemas comuns incluem 401 (token inválido) ou 400 (consulta inválida). Registre as respostas para depuração.
• Escalabilidade: Para pesquisas de alto volume, integre-se com o webhook Connect do DocuSign para atualizações push, reduzindo as necessidades de polling.

Essa funcionalidade de API posiciona o DocuSign como líder em automação de conformidade, embora as empresas devam avaliar os custos totais, incluindo complementos como autenticação.

DocuSign: Líder de Mercado em Soluções de Assinatura Eletrônica

O DocuSign tem sido pioneiro em assinaturas eletrônicas desde 2004, oferecendo um conjunto abrangente de ferramentas de gerenciamento de documentos. Sua plataforma de assinatura eletrônica inclui planos que variam de Personal (US$ 120 por ano) a Business Pro (US$ 480 por usuário por ano), com acesso à API por meio de um plano de desenvolvedor separado. Os principais recursos incluem modelos, envio em massa e integrações com mais de 400 aplicativos. Para necessidades avançadas, o Intelligent Agreement Management (IAM) do DocuSign combina CLM (gerenciamento do ciclo de vida do contrato) com insights baseados em IA, automatizando revisões e avaliações de risco. O IAM é adequado para empresas, embora os preços sejam personalizados e possam aumentar com o número de assentos e envelopes.

Adobe Sign: Integração Robusta para Fluxos de Trabalho Empresariais

O Adobe Sign, parte do Adobe Document Cloud, se destaca na integração perfeita com ferramentas de PDF e suítes criativas. Os preços começam em cerca de US$ 10/usuário por mês para indivíduos, escalando para planos personalizados para empresas. Ele suporta campos personalizados e pesquisa de API semelhantes ao DocuSign, usando endpoints como /agreements para consultar metadados. Os pontos fortes incluem fortes conexões com o ecossistema Adobe e conformidade global, mas a funcionalidade avançada da API pode exigir licenciamento adicional. As empresas valorizam seu foco na criação de documentos ao lado das assinaturas.

eSignGlobal: Soluções Personalizadas para APAC e Conformidade Global

eSignGlobal se destaca como um player especializado, particularmente na região da Ásia-Pacífico (APAC), onde os regulamentos de assinatura eletrônica são fragmentados, de alto padrão e fortemente regulamentados. Ao contrário das estruturas dos EUA ESIGN/UETA ou da Europa eIDAS – que dependem da verificação de e-mail ou autodeclaração – a APAC exige padrões de integração de ecossistema. Isso envolve acoplamentos profundos de hardware/nível de API com identidades digitais governo para empresa (G2B), elevando significativamente as barreiras técnicas acima dos modelos ocidentais. eSignGlobal aborda isso cobrindo a conformidade em mais de 100 países e regiões globais convencionais, com uma vantagem na APAC por meio de data centers locais em Hong Kong e Cingapura. Ele suporta integração perfeita com iAM Smart de Hong Kong e Singpass de Cingapura para autenticação robusta. Os preços são competitivos, com o plano Essential a US$ 299 por ano (equivalente anualizado a cerca de US$ 16,6 por mês), permitindo até 100 documentos assinados, assentos de usuário ilimitados e verificação de código de acesso – tudo em uma base compatível e econômica, abaixo de muitos concorrentes, mantendo a validade legal.

Procurando uma alternativa mais inteligente ao DocuSign?

eSignGlobal oferece uma solução de assinatura eletrônica mais flexível e econômica, com conformidade global, preços transparentes e um processo de integração mais rápido.

👉 Comece um teste gratuito

HelloSign (Dropbox Sign): Solução Simplificada para SMBs

HelloSign, agora Dropbox Sign, prioriza uma interface amigável para pequenas e médias empresas (SMBs). Uma versão gratuita permite até três documentos por mês, com planos pagos a partir de US$ 15 por mês. Sua API suporta pesquisa de envelope por meio de campos personalizados, usando endpoints como /templates e /signatures, embora não seja tão granular quanto o DocuSign. Adequado para integração rápida com o Dropbox, o foco está na facilidade de uso em vez da personalização de nível empresarial.

Visão Geral Comparativa das Plataformas de Assinatura Eletrônica

Esta tabela destaca compensações neutras; a escolha depende das necessidades regionais e da escala.

Em conclusão, embora a API do DocuSign permita pesquisas precisas de envelopes, explorar alternativas pode otimizar para mercados específicos. Para conformidade regional, eSignGlobal oferece uma opção equilibrada como uma alternativa ao DocuSign.