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

Três lançamentos de API foram enviados desde v1.5, e todos os três são atualizações não-disruptivas e fáceis de implementar. Veja o que há de novo e como usá-lo.

v1.6.0: Dividir Downloads de PDF e Limpeza de Tipos de Campo

Lançado a 12 de fevereiro de 2026

A funcionalidade mais solicitada no v1.6 é a divisão de downloads de PDF. Anteriormente, quando uma solicitação de assinatura era concluída, recebia um único PDF combinado que incluía tanto o documento assinado quanto o certificado de trilha de auditoria. Agora pode baixá-los separadamente.

Dois novos campos estão disponíveis em solicitações de assinatura concluídas:

{
  "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 um link novo, basta buscar a solicitação de assinatura novamente. Isto é particularmente útil se precisar armazenar o documento assinado em um sistema e a trilha de auditoria em outro, ou se seus utilizadores finais apenas precisarem do PDF assinado limpo sem as páginas de certificado anexadas.

O v1.6 também limpou a denominação de tipos de campo. A API agora aceita tanto initials quanto initial, assim como textarea e text_area, e os normaliza automaticamente. Se sua integração já estava usando os nomes originais, nada será quebrado. Se preferir as formas normalizadas, essas também funcionam.

Registro de alterações completo do v1.6

v1.7.0: Assinaturas Desenhadas à Mão

Lançado a 27 de fevereiro de 2026

Alguns fluxos de trabalho exigem que os assinantes desenhem fisicamente sua assinatura em vez de selecionar uma opção digitada ou gerada por fonte. O v1.7 introduz a configuração hand_drawn_only para impor exatamente isso.

Adicione-o às configurações da sua solicitação 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 ativado, a interface de assinatura remove completamente as opções de assinatura digitadas e baseadas em fontes. Os assinantes devem desenhar sua assinatura à mão. Isto é útil para indústrias rigorosas em compliance, como saúde e serviços financeiros, onde reguladores ou auditores esperam assinaturas manuscritas especificamente.

A configuração tem como padrão false, portanto, solicitações de assinatura existentes não são afetadas.

Este lançamento também adicionou campos de configuração legados retrocompatíveis ao esquema SigningRequest. Estes são versões baseadas em inteiros (0/1) das configurações booleanas, projetadas para integrações mais antigas que esperam esse formato. Se estiver construindo algo novo, mantenha-se com o objeto settings. Os campos legados estão lá para equipes migrando de sistemas mais antigos.

Registro de alterações completo do v1.7

v1.8.0: API de Modelos de Email e Suporte a Idiomas

Lançado a 3 de março de 2026

O v1.8 é o maior dos três. A principal novidade é a API de Modelos de Email, que lhe dá controle 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. Modelos suportam corpos HTML com marcadores como {{signer_name}}, {{document_name}} e {{signing_link}}.

Aqui está um exemplo rápido:

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

Os modelos seguem uma hierarquia: modelos a nível de espaço de trabalho substituem modelos a nível de empresa, que substituem os padrões internos. Isso 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 onde cada um dos seus clientes precisa dos seus próprios emails de marca.

Além dos modelos personalizados, o v1.8 adiciona um campo de language tanto para Company quanto para WorkspaceSettings. Defina-o como um dos sete idiomas suportados (en, es, it, pt, fr, de, el

) e os modelos de email internos da Firma.dev usarão automaticamente esse idioma. Combinado com substituições a nível de espaço de trabalho, pode atender mercados internacionais sem precisar gerenciar uma infraestrutura separada de email.

Melhorias no Esquema

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

O esquema Template agora inclui recipients, fields, settings, page_count e expiration_hours em linha quando busca um único modelo. Isso significa menos chamadas de API para obter uma visão completa da configuração de um modelo.

As respostas da solicitação de assinatura foram divididas em formatos específicos de endpoints (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) com dados em linha e campos de carimbo de data e hora padronizados. Isso 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 rastreamento de falhas são particularmente úteis para monitorização. Se um webhook começar a falhar, agora pode ver quantas falhas consecutivas ocorreram e se a Firma.dev o desativou automaticamente.

Note que o 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á lida com os campos de resposta reais (o que quase certamente faz), não são necessárias alterações.

Registro de alterações completo do v1.8

Atualizando

Todos os três lançamentos são totalmente retrocompatíveis. Sem alterações disruptivas, sem passos de migração necessários. Pode atualizar sua versão da API de v1.5 diretamente para v1.8 e tudo continuará funcionando como antes, com os novos recursos disponíveis imediatamente.

Para o registro de alterações completo com todas as mudanças de esquema e notas de migração, consulte o Registro de Alterações da API na documentação. Se estiver apenas começando com a Firma.dev, pode obter sua chave de API gratuitamente e começar a construir hoje mesmo.

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