Firma.dev API v1.6, v1.7, e v1.8: Dividir PDFs, Assinaturas à Mão, e Modelos de Email Personalizados

Três lançamentos da API foram publicados desde v1.5, e os três são atualizações retrocompatíveis e sem quebras. Eis as novidades e como as utilizar.

v1.6.0: Downloads de PDF separados e limpeza dos tipos de campo

Lançado a 12 de fevereiro de 2026

A funcionalidade mais pedida na v1.6 é o download separado de PDFs. Anteriormente, quando um pedido de assinatura era concluído, recebia um único PDF combinado que incluía tanto o documento assinado como o certificado do registo de auditoria. Agora pode descarregá-los em separado.

Dois novos campos estão disponíveis nos pedidos de assinatura concluídos:

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

Ambos os URLs são pré-assinados e expiram após 1 hora. Se precisar de uma ligação nova, basta voltar a obter o pedido de assinatura. Isto é particularmente útil se precisar de guardar o documento assinado num sistema e o registo de auditoria noutro, ou se os seus utilizadores finais apenas precisarem do PDF assinado limpo, sem as páginas do certificado anexadas.

A v1.6 também simplificou a nomenclatura dos tipos de campo. A API aceita agora tanto initials como initial, bem como textarea e text_area, e normaliza-os automaticamente. Se a sua integração já utilizava os nomes originais, nada deixa de funcionar. Se preferir as formas normalizadas, essas também funcionam.

Registo de alterações completo da v1.6

v1.7.0: Assinaturas desenhadas à mão

Lançado a 27 de fevereiro de 2026

Alguns fluxos de trabalho exigem que os signatários desenhem fisicamente a sua assinatura, em vez de selecionarem uma opção dactilografada ou gerada por fonte. A v1.7 introduz a definição hand_drawn_only para impor exatamente isso.

Adicione-a às definições do seu pedido de assinatura:

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

Quando ativada, a interface de assinatura remove por completo as opções de assinatura dactilografada e baseada em fontes. Os signatários têm de desenhar a sua assinatura à mão. Isto é útil para setores fortemente regulados, como a saúde e os serviços financeiros, onde os reguladores ou auditores esperam especificamente assinaturas manuscritas.

A definição tem false por predefinição, pelo que os pedidos de assinatura existentes não são afetados.

Esta versão também adicionou campos de definições legadas retrocompatíveis ao esquema SigningRequest. São versões baseadas em inteiros (0/1) das definições booleanas, concebidas para integrações mais antigas que esperam esse formato. Se estiver a criar algo novo, mantenha-se no objeto settings. Os campos legados existem para equipas a migrar de sistemas mais antigos.

Registo de alterações completo da v1.7

v1.8.0: API de modelos de email e suporte a idiomas

Lançado a 3 de março de 2026

A v1.8 é a maior das três. A funcionalidade principal é a API de modelos de email, que lhe dá controlo total sobre os emails de notificação que a Firma.dev envia durante o processo de assinatura.

Pode personalizar modelos para cinco tipos de email: signing_invite, next_signer, signing_expired, signing_cancelled e signing_declined. Os modelos suportam corpos em HTML com marcadores como {{signer_name}}, {{document_name}} e {{signing_link}}.

Eis um exemplo rápido:

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Por favor assine: {{document_name}}",
  "body": "<p>Olá {{signer_name}},</p><p>Revise e assine usando esta ligação: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Por favor assine: {{document_name}}",
  "body": "<p>Olá {{signer_name}},</p><p>Revise e assine usando esta ligação: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Por favor assine: {{document_name}}",
  "body": "<p>Olá {{signer_name}},</p><p>Revise e assine usando esta ligação: {{signing_link}}</p>"
}

Os modelos seguem uma hierarquia: os modelos ao nível do workspace substituem os modelos ao nível da empresa, que por sua vez substituem os predefinidos incorporados. Isto significa que pode definir um modelo para toda a empresa e depois personalizá-lo por Espaço de Trabalho do Cliente para cenários de marca branca em que cada um dos seus clientes precisa dos seus próprios emails com a respetiva marca.

Além dos modelos personalizados, a v1.8 adiciona um campo language tanto a Company como a WorkspaceSettings. Defina-o para um dos sete idiomas suportados (pt, es, it, pt, fr, de e el) e os modelos de email incorporados da Firma.dev usarão automaticamente esse idioma. Em combinação com as substituições ao nível do workspace, pode servir mercados internacionais sem gerir infraestrutura de email separada.

Melhorias no esquema

A v1.8 também trouxe várias melhorias de esquema que vale a pena conhecer:

O esquema Template inclui agora recipients, fields, settings, page_count e expiration_hours em linha quando obtém um único modelo. Isto significa menos chamadas à API para obter a imagem completa da configuração de um modelo.

As respostas dos pedidos de assinatura foram divididas em estruturas específicas por endpoint (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) com dados em linha e campos de timestamp padronizados. Isto torna as respostas mais previsíveis e mais fáceis de tipar na sua base de código.

Os webhooks ganharam três novos campos: description, consecutive_failures e auto_disabled_at. Os campos de acompanhamento de falhas são particularmente úteis para monitorização. Se um webhook começar a falhar, pode agora ver quantas falhas consecutivas ocorreram e se a Firma.dev o desativou automaticamente.

Note que a v1.8 também corrigiu vários nomes de campos na especificação OpenAPI para corresponder às respostas reais da API. Se a sua integração já trata os campos reais das respostas (o que quase de certeza acontece), não são necessárias alterações.

Registo de alterações completo da v1.8

Atualização

As três versões são totalmente retrocompatíveis. Sem alterações incompatíveis, sem passos de migração necessários. Pode atualizar a versão da sua API da v1.5 diretamente para a v1.8 e tudo continuará a funcionar como antes, com as novas funcionalidades disponíveis de imediato.

Para o registo de alterações completo com todas as mudanças de esquema e notas de migração, consulte o Registo de alterações da API na documentação. Se está apenas a começar com a Firma.dev, pode obter a sua chave de API gratuitamente e começar a desenvolver hoje.

Notas de lançamento anteriores: v1.5 | v1.3 e v1.4