Firma.dev API v1.6, v1.7 e v1.8: Dividir PDFs, Assinaturas Desenhadas à 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 sem interrupção. Aqui está o que há de novo e como usá-lo.

v1.6.0: Divisão de Downloads de PDF e Limpeza de Tipos de Campos

Lançado em 12 de fevereiro de 2026

O recurso mais solicitado na v1.6 é a divisão de downloads de PDF. Anteriormente, quando um pedido de assinatura era concluído, você recebia um único PDF combinado que incluía tanto o documento assinado quanto o certificado do rastro de auditoria. Agora você 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 você precisar de um link novo, basta buscar o pedido de assinatura novamente. Isso é particularmente útil se você precisar armazenar o documento assinado em um sistema e o rastro de auditoria em outro, ou se seus usuários finais só precisarem do PDF assinado limpo sem as páginas de certificado anexadas.

A v1.6 também limpou a nomeação dos tipos de campos. 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 se quebrará. Se você preferir as formas normalizadas, elas também funcionam.

Changelog completo da v1.6

v1.7.0: Assinaturas Desenhadas à Mão

Lançado em 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. A v1.7 introduz a configuração hand_drawn_only para aplicar exatamente isso.

Adicione-a às configuraçõ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 completamente as opções de assinatura digitadas e baseadas em fontes. Os assinantes devem desenhar sua assinatura à mão. Isso é útil para indústrias com alta conformidade, como saúde e serviços financeiros, onde reguladores ou auditores esperam assinaturas manuscritas específicas.

A configuração padrão é false, assim, solicitações de assinatura existentes não são afetadas.

Esta versão também adicionou campos de configurações legadas compatíveis com versões anteriores 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 você está construindo algo novo, permaneça com o objeto settings. Os campos legados estão disponíveis para equipes migrando de sistemas mais antigos.

Changelog completo da v1.7

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

Lançado em 3 de março de 2026

A v1.8 é a maior das três. O principal recurso é a API de Modelos de Emails, que dá a você controle total sobre os emails de notificação que a Firma.dev envia durante o processo de assinatura.

Você pode personalizar modelos para cinco tipos de emails: 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}}.

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 workspace substituem modelos a nível de empresa, que substituem os padrões internos. Isso significa que você pode definir um modelo em toda a empresa e depois personalizá-lo por Workspace do Cliente para cenários de marca própria onde cada um dos seus clientes precisa de seus próprios emails com a marca.

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

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

Melhorias no Esquema

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

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

Respostas de pedidos de assinatura foram divididas em formas específicas do endpoint (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) com dados inline e campos de marcação temporal padronizados. Isso torna as respostas mais previsíveis e fáceis de digitar na sua base de código.

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

Observe que a v1.8 também corrigiu vários nomes de campos na especificação OpenAPI para corresponder às respostas reais da API. Se sua integração já lida com os campos de resposta reais (que quase certamente faz), nenhuma alteração é necessária.

Changelog completo da v1.8

Atualizando

Todos os três lançamentos são totalmente compatíveis com versões anteriores. Sem mudanças de quebra, sem etapas de migração necessárias. Você pode atualizar sua versão da API da v1.5 direto para a v1.8 e tudo continuará funcionando como antes, com os novos recursos disponíveis imediatamente.

Para o changelog completo com cada mudança de esquema e nota de migração, consulte o Changelog da API na documentação. Se você está apenas começando com a Firma.dev, pode obter sua chave de API gratuitamente e começar a construir hoje.

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