Gerenciamento e Consultas de Envelopes

Depois que os envelopes estão "em progresso", sua aplicação precisa de visibilidade. Seja para criar um dashboard interno, confirmar uma assinatura ou oferecer suporte ao seu cliente final, saber como consultar e filtrar dados é essencial.

Na API v3, utilizamos o padrão JSON:API para buscas, o que permite filtros poderosos e paginação eficiente.

---

🔍 Consultar Detalhes de um Envelope

Se você tem o ID do envelope, pode obter o status atual, a lista de documentos vinculados e o progresso das assinaturas em uma única chamada.

• Método: GET
• Endpoint: https://app.clicksign.com/api/v3/envelopes/{id}

Documentação Técnica: Veja todos os campos de retorno em Referência da API: Detalhes do Envelope.

O que observar no retorno?

No objeto attributes, o campo status é o seu principal indicador:

• draft: Ainda em montagem.
• running: Disponível para assinatura.
• closed: Sucesso! Processo finalizado.
• canceled: A transação não foi concluída.

---

📑 Listar e Filtrar Envelopes

Para sistemas com alto volume, listar todos os envelopes de uma vez é inviável. Por isso, a API v3 oferece filtros nativos.

• Endpoint: GET /api/v3/envelopes

Exemplos de Filtros Úteis:

Dica de Performance: Sempre utilize filtros para reduzir o tempo de resposta e o consumo de banda da sua integração. Confira a lista completa de filtros na Referência da API: Listar Envelopes.

---

📦 Paginação (Escalabilidade)

Se a sua conta possui milhares de envelopes, os resultados serão entregues em "páginas". No final do JSON de resposta, você encontrará o objeto links com as URLs para next (próxima) e prev (anterior).

• Padrão: 25 itens por página.
• Como mudar: Use ?page[number]=2&page[size]=50.

---

🛠️ Ações de Gerenciamento

Além de consultar, você pode precisar intervir em um fluxo existente:

1. Editar um Envelope

Mudar o nome ou a data de expiração de um rascunho.

• Método: PATCH /api/v3/envelopes/{id}
• Referência: Editar Envelope

2. Excluir um Rascunho

Se o envelope ainda for um draft, você pode removê-lo completamente.

• Método: DELETE /api/v3/envelopes/{id}
• Referência: Excluir Envelope

---

💡 Boas Práticas de Monitoramento

1. Não faça "Polling": Evite ficar perguntando à API o status do envelope de minuto em minuto. Isso consome recursos desnecessários.
2. Use Webhooks: Deixe que a Clicksign avise seu sistema quando o status mudar para completed. Use a consulta (GET) apenas quando precisar de detalhes específicos após o aviso.
3. Visibilidade: Há uma etapa você gostaria de ter mais visão e ainda não existe o webhook? Fale com a gente.
4. Cache de Metadados: Salve o id da Clicksign atrelado ao ID do seu banco de dados interno para consultas instantâneas.

---

🎉 Você concluiu o Guia de Envelopes!

Agora você está pronto para criar, ativar em escala e gerenciar transações complexas com total controle.