⚠️
Importante: A API 1.9 é uma API legada, portanto não receberá mais atualizações ou melhorias. Todas as evoluções da plataforma estão sendo direcionadas exclusivamente para a versão 3.0 (Envelope).

Pronto para ver na prática?

Agora que explicamos concentualmente as diferenças entre as versões, confira as diferenças mais técnicas entre ambas, com exemplos de código, tudo pensado para facilitar ainda mais a sua migração:

A Clicksign possui, essencialmente, duas arquiteturas de API principais mencionadas na documentação: a versão Legada (anteriormente chamada de API 1.9 ou v1/v2) e a versão atual, robusta e modular (API 3.0).

O foco da migração é a mudança de um modelo centrado no Documento para um modelo centrado no Envelope, o que oferece maior flexibilidade e gestão.

Característica	API Legada (v1 / v1.9) - (`/v1/documents`)	API Atual (v3) - (`/v3/envelopes`)
Entidade Central	Documento	Envelope (Transação)
Arquitetura	Entidades complexas e acopladas.	Sistema baseado em transações. Entidades desacopladas e modulares.
Signatários/Pessoas	Não possui um ciclo de vida.	Possui o mesmo ciclo de vida do Envelope.
Flexibilidade de Fluxo	Configuração de ações (assinar) acoplada ao documento, com pouca flexibilidade para múltiplos papéis.	Máxima flexibilidade com a entidade Requirements. Você define o que (documento), quem (signatário) e como (ação/autenticação) em um único lugar.
Requisitos de Assinatura	Configuração mais limitada, sem todas formas de Autenticação (sem Documentoscopia, Biometria Serpro, Assinatura Posicionada e mais).	Rica e modular. Suporte a qualificação, todas formas de Autenticação (Token, Biometria, Selfie, PIX, etc.) e Rubrica.
Padrão de Dados (Payload)	Estrutura JSON personalizada (não padronizada).	JSON:API `(application/vnd.api+json)`.
Vantagem JSON:API	Exigia a criação de parsers manuais e gestão complexa de relacionamentos.	Reduz o tempo de desenvolvimento ao permitir o uso de bibliotecas client prontas em várias linguagens (JavaScript, Ruby, Python, PHP, etc.), simplificando a serialização e o consumo de dados e relacionamentos.

Detalhes Importantes da Migração

1. Assinatura via API (Passou a ser Assinatura Automática)

API 1.9: O endpoint POST /api/v1/sign permitia que a sua aplicação assinasse documentos em nome de um signatário, utilizando um secret (chave secreta) e o cálculo de um secret_hmac_sha256. Este recurso era destinado a assinaturas recorrentes com autorização prévia.
API 3.0 (Envelope): O conceito de assinatura programática sem interação do usuário é gerenciado pelo recurso de Assinatura Automática. O processo não utiliza mais o endpoint /sign, mas sim a configuração de requisitos de assinatura dentro do Envelope e o uso de um tipo específico de requisito ou feature.

2. Cancelamento

API 1.9: O cancelamento era feito diretamente no endpoint do documento documents/:id/cancel.
API 3.0 (Envelope): A entidade central é o Envelope. Para cancelar um processo, você deve primeiro garantir que os documentos contidos no Envelope sejam canceláveis/excluíveis (o que geralmente é feito via PATCH no documento para alterar seu status, ou DELETE se for um rascunho). A exclusão do Envelope (via DELETE /envelopes/{id}) só é permitida se ele estiver no status de rascunho (draft) e não tiver documentos em processo.

3. Duplicação de Documentos

API 3.0 (Envelope): Na nova API, a duplicação se integra ao fluxo de criação de documentos dentro de um Envelope. Você usa o mesmo endpoint de criação de documento (POST /envelopes/{envelope_id}/documents), mas inclui o ID do documento de origem no payload para indicar que ele deve ser duplicado.

Requirements: A definição de regras

Esta é a chave da nova arquitetura. O Requirement define o "contrato" entre o signatário e o documento, respondendo às três perguntas essenciais:

Quem assina?
O quê assina (qual documento)?
Como se autentica (token, biometria, etc.)?

Isso transforma a forma como você constrói seus fluxos, permitindo que a Clicksign gerencie a complexidade da solução por você.

Bibliotecas Client JSON: API por Linguagem

Utilize bibliotecas especializadas que já implementam todo o padrão JSON:API:

Linguagem/Plataforma	Bibliotecas Recomendadas	Principais Funcionalidades
JavaScript/TypeScript Node.js e Browser	• `kitsu` • `jsonapi-serializer` • `jsonapi-datastore`	• Client HTTP completo integrado • Serialização/deserialização automática • Cache e gerenciamento de estado • Suporte a relacionamentos e inclusões
Ruby Ruby on Rails	• `jsonapi-client` • `jsonapi-resources`	• Interface ActiveRecord-like • Integração nativa com Rails • Mapeamento automático de relacionamentos • Suporte a includes e eager loading
Python	• `jsonapi-requests` • `django-rest-framework-json-api`	• Integração com requests/httpx • Suporte a Django e Flask • Filtros e paginação automáticos • Validação de schemas
PHP	• `neomerx/json-api` • `eloquent-json-api`	• Framework completo de serialização • Integração com Laravel Eloquent • Encoders e decoders customizáveis • Suporte a sparse fieldsets
.NET / C#	• `JsonApiDotNetCore` • `JSONAPI.Net`	• Middleware para ASP.NET Core • Mapeamento automático com Entity Framework • Suporte a filtros LINQ • Validações integradas
Java	• `jsonapi-converter` • `crnk-framework`	• Conversão automática de POJOs • Integração com Spring Boot • Suporte a JPA/Hibernate • Filtros e ordenação dinâmicos
Go	• `jsonapi` • `go-jsonapi`	• Marshaling/unmarshaling automático • Compatível com encoding/json • Suporte a tags de struct • Performance otimizada

Vantagens da padronização

O ponto crucial é que o padrão JSON:API oferece um contrato rigoroso entre o servidor (Clicksign v3) e o client (sua aplicação).

Ao usar qualquer uma dessas libs, você não precisa escrever código personalizado para:

Serialização: Transformar seus objetos em um payload JSON:API válido.
Desserialização: Ler a resposta da Clicksign, extrair os dados, e resolver os relacionamentos (relationships e included).
Filtros/Paginação: Formatar requisições com os parâmetros de filter, sort e page de forma padronizada.

Pronto para esclarecer todas as dúvidas?

Abaixo está o link do FAQ contendo as principais dúvidas relacionadas a migração:

FAQ: Migração

❓Precisa de ajuda? [email protected]

💰Dúvida sobre planos e preços? Veja o comparativo

🔍Não sabe qual versão está usando? Descubra a sua versão

📚Respostas rápidas? Visite nosso FAQ