O Que Enviámos em Janeiro de 2026

Janeiro foi um mês atarefado. Lançámos um conjunto de atualizações para o Firma.dev pelas quais estamos bastante entusiasmados, e a maioria delas veio diretamente do feedback que recebemos de programadores que constroem sobre a API.

O tema deste mês foi tornar a API mais rápida, mais flexível e mais fácil de integrar. Algumas destas alterações são pequenas melhorias na qualidade de vida. Outras desbloqueiam fluxos de trabalho completamente novos. Estamos agora na versão 1.2.0, e tudo o que está aqui já está disponível hoje.

Aqui está o resumo.

Pedidos de Assinatura 40% Mais Rápidos

Passámos um par de semanas a analisar o desempenho e conseguimos reduzir a nossa latência média de pedidos de assinatura de 820ms para cerca de 500ms. Trata-se de uma melhoria de cerca de 40% em termos gerais.

As alterações foram maioritariamente trabalho de infraestrutura. Limpámos algumas consultas de base de dados que se tinham tornado ineficientes ao longo do tempo, e mudámos os recursos estáticos para trás do AWS CloudFront para armazenamento em cache na periferia. Nada de revolucionário, mas o tipo de trabalho que se acumula.

Se está a incorporar assinaturas no seu produto, isto importa mais do que pode parecer. 300ms de latência não parecem muito, mas é a diferença entre um fluxo de assinatura que parece instantâneo e um que parece lento. Respostas mais rápidas significam menos fluxos abandonados e menos fricção para os seus utilizadores.

Pedidos de Assinatura Únicos (Sem Necessidade de Modelo)

Anteriormente, se quisesse enviar um documento para assinatura através do Firma.dev, tinha de criar primeiro um modelo. Isso fazia sentido para fluxos de trabalho repetitivos, como contratos de trabalho ou acordos de confidencialidade (NDAs), mas adicionava etapas desnecessárias para documentos de uma única utilização.

Agora pode ignorar completamente o modelo. Carregue um PDF diretamente, defina os seus campos e destinatários inline, e envie-o. Uma chamada de API, sem necessidade de criação de modelo.

Isto é útil para acordos ad-hoc, contratos únicos ou qualquer situação em que não vá reutilizar a estrutura do documento. Continua a ter todos os mesmos tipos de campos, opções de assinante e rastreamento. Apenas não tem de configurar um modelo primeiro.

Consulte o endpoint de criação de pedido de assinatura para obter detalhes de implementação.

Endpoint Atómico de Criação + Envio

Falando em reduzir chamadas de API: adicionámos um novo endpoint atómico que lhe permite criar e enviar um pedido de assinatura numa única chamada.

Anteriormente, chamaria o endpoint de criação e, em seguida, o endpoint de envio. Dois pedidos, duas viagens de ida e volta. O novo endpoint /signing-requests/create-and-send combina ambos num só.

Mas o verdadeiro benefício é a integridade transacional. O endpoint valida tudo antes de criar o quer que seja. Se algo falhar na validação, nada é criado e não lhe é cobrado nada. Os créditos só são deduzidos após o pedido de assinatura ser criado com sucesso e os e-mails serem enviados.

A partir dos documentos: "Chamada única à API em vez de dois pedidos separados... Dedução de crédito atómica – só cobra se tudo for bem-sucedido."

Se está a construir automações ou fluxos de trabalho de alto volume, este endpoint é mais limpo e fiável do que encadear duas chamadas.

Campos de Apenas Leitura

Agora pode marcar campos como apenas leitura ao criar ou atualizar um pedido de assinatura. Estes são campos que aparecem no documento com valores pré-preenchidos, mas que o assinante não pode editar.

Isto é útil para coisas como valores de contratos, números de referência, totais calculados ou IDs de funcionários. Qualquer coisa que o assinante precise de ver para contextualização, mas que não deva poder alterar.

Encontrará a propriedade read_only no endpoint de atualização abrangente. Defina-a como true em qualquer campo de texto e este torna-se visível, mas não editável.

Controlos de E-mail Granulares

Adicionámos quatro novas configurações que lhe dão um controlo detalhado sobre quais os e-mails que o Firma.dev envia em seu nome:

• send_signing_email – a notificação inicial "por favor, assine este documento"

• send_finish_email – a confirmação de "assinatura concluída"

• send_expiration_email – o lembrete quando um pedido está prestes a expirar

• send_cancellation_email – a notificação quando um pedido é cancelado

Todas as quatro opções têm por defeito o valor true, pelo que as integrações existentes funcionam exatamente como antes. Mas se quiser enviar os seus próprios e-mails personalizados em vez dos nossos, pode agora desativar qualquer uma ou todas estas opções e gerir as notificações por si mesmo.

Isto combina perfeitamente com as configurações de marca branca abaixo.

Ignorar os Termos do Firma.dev para uma Experiência Total de Marca Branca

Existe uma nova configuração no seu espaço de trabalho chamada "Exigir Aceitação dos Termos". Quando está ativada (o padrão), os assinantes têm de aceitar os termos e condições do Firma.dev antes de assinar. Quando a desativa, esse passo desaparece por completo.

Isto foi concebido para equipas que pretendem uma experiência de assinatura totalmente de marca branca. Os seus assinantes veem a sua imagem de marca, os seus e-mails (se tiver desativado os nossos) e os seus termos. O Firma.dev permanece invisível.

Se optar por este caminho, recomendamos que tenha os seus próprios termos e condições em vigor. Está a assumir a responsabilidade de informar os assinantes sobre as implicações legais da sua assinatura, por isso certifique-se de que os seus próprios T&Cs cobrem isso.

Combinado com os controlos de e-mail acima, pode agora disponibilizar uma experiência de assinatura totalmente personalizada, sem que qualquer interface de utilizador do Firma.dev apareça aos seus utilizadores finais.

Novos Guias para Programadores

Reescrevemos uma parte da nossa documentação este mês. Três novos guias ficaram disponíveis online:

Guia de Autenticação – Aborda a autenticação com chave de API para pedidos servidor a servidor, além de tokens JWT para incorporar os editores de modelos e de pedidos de assinatura na sua aplicação. Também inclui o novo fluxo de rotação de chave de API com períodos de carência de 24 horas.

Aborda a autenticação com chave de API para pedidos servidor a servidor, além de tokens JWT para incorporar os editores de modelos e de pedidos de assinatura na sua aplicação. Também inclui o novo fluxo de rotação de chave de API com períodos de carência de 24 horas.

Guia de Limites de Débito – Documenta todos os níveis de limites de débito (200 pedidos/min para leituras, 120/min para escritas, e assim por diante). Nota importante aqui: os limites de débito são por espaço de trabalho, e pode ter espaços de trabalho ilimitados na sua conta. Isso confere-lhe, de forma eficaz, uma escalabilidade horizontal ilimitada. Se por algum motivo precisar de limites ainda mais elevados para um caso de utilização específico, entre em contacto com o suporte e podemos aumentá-los, mas os valores predefinidos já foram concebidos para volumes muito elevados.

Guia de Configuração Completo – Um passo a passo completo de ponta a ponta, desde a criação da conta até à assinatura incorporada. Aborda espaços de trabalho, modelos, pedidos de assinatura, editores incorporados, webhooks e gestão de créditos. Se está a dar os primeiros passos, este é o local para começar.

Controlo de Versão Completo da API

Introduzimos um sistema formal de controlo de versões este mês. A API utiliza agora o controlo de versões baseado em cabeçalhos através do cabeçalho X-API-Version, e estamos atualmente na v1.2.0.

A versão curta: estamos empenhados em não quebrar a sua integração. A partir do guia de controlo de versões: "As alterações drásticas só são introduzidas em incrementos de versões principais... Alterações que não causem ruturas, tais como novos campos opcionais ou novos endpoints, não requerem uma nova versão."

Quando eventualmente lançarmos uma v2, a versão antiga não irá simplesmente desaparecer. Receberá avisos de descontinuação nos cabeçalhos de resposta durante pelo menos seis meses antes de qualquer desativação. Os cabeçalhos seguem o RFC 8594, por isso, se já verifica a existência de cabeçalhos de Deprecation e Sunset noutras APIs, saberá o que esperar.

Por enquanto, a v1 está ativa sem qualquer descontinuação programada. Tudo o que lançámos este mês é cumulativo, pelo que a sua integração existente continua a funcionar sem alterações.

Conclusão

Isto foi o mês de janeiro. Muitas pequenas a médias melhorias que se traduzem numa API mais capaz e mais flexível.

Os preços não mudaram. Continuam a ser €0,049 por envelope, no modelo pague-o-que-usar, sem mínimos. Se ainda não experimentou o Firma.dev, pode testar com documentos reais gratuitamente, sem limites, e só pagar quando avançar para produção.

Vamos continuar a lançar novidades. Se houver algo que queira ver na API, diga-nos.

Comece gratuitamente – não é necessário cartão de crédito.