API DocuSign: Listar todos os destinatários de envelopes não assinados

Navegando na API DocuSign para Gerenciar Envelopes

No mundo em rápida evolução dos acordos digitais, as empresas dependem de plataformas de assinatura eletrônica para otimizar os fluxos de trabalho. A DocuSign, líder nesse espaço, oferece recursos robustos de API que permitem aos desenvolvedores automatizar e monitorar processos de documentos. Um desafio comum é rastrear o status dos destinatários em um envelope – especificamente, identificar aqueles que ainda não assinaram. Essa capacidade é crucial para conformidade, acompanhamento e eficiência operacional, especialmente em ambientes de alto volume, como equipes de vendas ou departamentos jurídicos.

Entendendo a API DocuSign e os Destinatários do Envelope

A API eSignature da DocuSign fornece endpoints para gerenciar envelopes, que são essencialmente contêineres para documentos que exigem assinaturas. Um envelope pode ter vários destinatários, cada um com funções como signatário, aprovador ou copiador. A API usa uma arquitetura RESTful, suporta cargas JSON e requer autenticação por meio de OAuth 2.0 ou autorização JWT.

Para listar todos os destinatários que ainda não assinaram um envelope, os desenvolvedores normalmente consultam o status do envelope e os detalhes do destinatário. O endpoint chave é GET /accounts/{accountId}/envelopes/{envelopeId}/recipients na API Envelopes. Isso retorna uma lista abrangente de destinatários, incluindo seus status (por exemplo, "sent", "declined", "signed" ou "needs_to_sign").

Aqui está um guia passo a passo para implementar essa funcionalidade:

1. Configuração de Autenticação: Use o sandbox de desenvolvedor da DocuSign para obter um token de acesso. Para ambientes de produção, integre-se com o sistema IAM (Identity and Access Management) do seu aplicativo. Os recursos IAM da DocuSign fazem parte de seus planos aprimorados, incluindo integrações SSO com provedores como Okta ou Azure AD, garantindo acesso seguro à API sem expor credenciais.

2. Recuperar Detalhes do Envelope: Comece obtendo o envelope usando GET /envelopes/{envelopeId}. Isso confirma o status do envelope (por exemplo, "sent" ou "in_progress") e fornece metadados como datas de criação e vencimento.

3. Consultar Destinatários: Chame o endpoint de destinatários. A resposta inclui um array de objetos de destinatários, cada um contendo:

   • id: Identificador único.
   • email: E-mail do destinatário.
   • status: Status atual (filtre por "sent" ou "needs_to_sign" para identificar destinatários não assinados).
   • routingOrder: Ordem no fluxo de assinatura.
   • name: Nome do destinatário.

   Um trecho JSON de exemplo da resposta da API:

   {
     "recipients": {
       "signers": [
         {
           "email": "john.doe@example.com",
           "status": "sent",
           "name": "John Doe",
           "signedDateTime": null
         },
         {
           "email": "jane.smith@example.com",
           "status": "signed",
           "name": "Jane Smith",
           "signedDateTime": "2025-01-15T10:00:00Z"
         }
       ]
     }
   }
   

4. Filtrar Destinatários Não Assinados: Em seu código (por exemplo, usando Python com a biblioteca requests ou Node.js com Axios), analise a resposta e filtre os casos em que status != "signed" e signedDateTime é nulo. Para operações em lote, use o endpoint GET /envelopes com parâmetros de consulta como status=sent para listar vários envelopes.

   Exemplo de código Python:

   import requests
   
   access_token = "your_access_token"
   account_id = "your_account_id"
   envelope_id = "your_envelope_id"
   base_url = "https://demo.docusign.net/restapi"
   
   headers = {
       "Authorization": f"Bearer {access_token}",
       "Accept": "application/json"
   }
   
   response = requests.get(
       f"{base_url}/v2.1/accounts/{account_id}/envelopes/{envelope_id}/recipients",
       headers=headers
   )
   
   if response.status_code == 200:
       data = response.json()
       unsigned_recipients = [
           r for r in data.get('recipients', {}).get('signers', [])
           if r.get('status') != 'signed' and r.get('signedDateTime') is None
       ]
       print("Unsigned recipients:", unsigned_recipients)
   

5. Tratamento de Erros e Melhores Práticas: Lide com limites de taxa (por exemplo, 1000 chamadas de API por minuto) e erros como 404 (envelope não encontrado). Para usuários corporativos, utilize os planos de API avançados da DocuSign, que incluem webhooks da Connect API para atualizações de status em tempo real. Isso evita a pesquisa e reduz as chamadas de API.

Essa abordagem garante que você possa notificar programaticamente os destinatários não assinados, escalar atrasos ou integrar-se a sistemas CRM como o Salesforce. Em ambientes comerciais, essa automação pode reduzir o acompanhamento manual em até 70%, de acordo com benchmarks da indústria dos recursos de desenvolvedor da DocuSign.

O preço da API da DocuSign começa em US$ 600/ano para o plano Starter (40 envelopes por mês), escalando para opções corporativas personalizadas. Para equipes em setores regulamentados, combinar isso com recursos IAM – como trilhas de auditoria avançadas e acesso baseado em função – pode aumentar a conformidade sem desenvolvimento personalizado.

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

Explorando o Ecossistema da DocuSign e os Recursos IAM

A DocuSign se estende além da assinatura básica, oferecendo ferramentas integradas como CLM (Contract Lifecycle Management) em seu conjunto Intelligent Agreement Management (IAM). O IAM CLM automatiza a criação, negociação e execução de contratos, extraindo dados de envelopes para rastrear obrigações. Para usuários de API, ele suporta a incorporação de cerimônias de assinatura e a extração de dados de destinatários não assinados em painéis.

Na prática, as empresas usam o IAM para visibilidade de ponta a ponta: as entradas de destinatários não assinados de um envelope acionam alertas de risco ou fluxos de trabalho de aprovação. O preço para atualizações do IAM é personalizado, geralmente agrupado com o plano Business Pro a US$ 480/usuário/ano, adicionando recursos de governança e análise.

Panorama Competitivo: Uma Comparação Neutra

O mercado de assinatura eletrônica é competitivo, com plataformas diferenciadas em profundidade de API, preços e conformidade regional. Aqui está uma tabela de comparação Markdown dos principais players, focando em recursos de API para gerenciamento de destinatários, preços principais e vantagens. Os dados são de fontes públicas de 2025 para garantir a neutralidade.

Esta tabela destaca as compensações: a DocuSign se destaca em um ecossistema maduro, enquanto outras plataformas priorizam acessibilidade ou vantagens de nicho.

Adobe Sign: Visão Geral da Integração e API

O Adobe Sign, parte do Adobe Document Cloud, enfatiza processos centrados em PDF. Sua API espelha a DocuSign no rastreamento de destinatários, usando GET /agreements/{agreementId}/participants para listar as partes não assinadas. É adequado para indústrias criativas, com edição de PDF integrada. Os preços começam em US$ 10/mês para o plano Individual, escalando para taxas corporativas personalizadas. A vantagem da Adobe reside na integração perfeita com o Acrobat e ferramentas de marketing, mas as cotas de API podem limitar o uso de alto volume.

HelloSign (Dropbox Sign): Simplicidade para SMBs

O HelloSign, agora Dropbox Sign, oferece uma API simples para gerenciamento de envelopes. Recupere destinatários não assinados via GET /v3/signature_request/{request_id}, filtrando por status. É elogiado por sua facilidade de uso, com modelos e lembretes integrados. A US$ 180/ano para o plano Essentials, é econômico para pequenas equipes, embora falte o IAM avançado da DocuSign.

eSignGlobal: Uma Alternativa Otimizada para APAC

A eSignGlobal se posiciona como uma concorrente global, suportando conformidade em mais de 100 países e regiões importantes. Ela tem uma vantagem particular 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 – geralmente exigindo uma abordagem profunda de integração de ecossistemas, em vez dos modelos ESIGN/eIDAS baseados em estrutura comuns nos EUA e na UE. Os requisitos da APAC envolvem acoplamento profundo de hardware/nível de API com identidades digitais de governo para empresa (G2B), uma barreira técnica muito além dos métodos de verificação de e-mail ou autodeclaração dos mercados ocidentais.

A API da plataforma inclui consultas de status de destinatário semelhantes às da DocuSign, suportando envio em massa e webhooks no plano Professional. Os preços são competitivos: o plano Essential custa apenas US$ 16,6/mês (equivalente a US$ 199/ano em algumas promoções), permitindo até 100 documentos assinados, assentos de usuário ilimitados e verificação de código de acesso – mantendo a conformidade. Ele se integra perfeitamente com o iAM Smart de Hong Kong e o Singpass de Cingapura, adequado para operações APAC transfronteiriças.

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

Implicações Comerciais e Recomendações

De uma perspectiva de negócios, a API da DocuSign continua sendo uma referência para confiabilidade no rastreamento de envelopes, especialmente para empresas globais. No entanto, alternativas estão ganhando reconhecimento à medida que as empresas se expandem para regiões diversificadas. Para aqueles que buscam alternativas ao DocuSign, a eSignGlobal se destaca como uma opção de conformidade regional, particularmente na APAC, equilibrando custo e recursos sem taxas por assento. Avalie com base em sua capacidade, integrações e geografia para encontrar a melhor correspondência.