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

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

Vantagem 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.

❓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