Novidades no Firma.dev: Personalize a sua página de assinatura até aos botões (White-Label)

A página de assinatura da Firma.dev já reflete a sua marca: o seu logótipo, as suas cores, os seus termos de signatário, os seus e-mails e a sua página de conclusão. A partir da API v1.40.0, lançada a 17 de outubro de 2026, também segue as suas regras sobre o que um signatário pode fazer nela. Duas novas definições ocultam os botões Recusar assinatura e Guardar e concluir mais tarde nas páginas de assinatura alojadas e incorporadas, pelo que uma plataforma SaaS que utilize a assinatura incorporada dentro do seu próprio produto decide agora que ações disponibiliza aos seus signatários.

Novo: escolha quais os botões que os seus signatários veem

A versão adiciona dois seletores. allow_decline controla o botão Recusar assinatura e show_save_for_later controla Guardar e concluir mais tarde. Ambos se aplicam à página de assinatura alojada e ao iframe de assinatura incorporado, e ambos estão visíveis por predefinição, pelo que as suas páginas de assinatura permanecem exatamente como estão até definir um valor.

Ocultar o botão Recusar assinatura é uma regra estritamente aplicada. Com allow_decline definido como false, a Firma.dev rejeita qualquer recusa nesse pedido de assinatura, tanto para signatários como para aprovadores, e o pedido só pode ser interrompido através do seu cancelamento... o que transfere a decisão de recusa para o seu produto. Ocultar Guardar e concluir mais tarde apenas remove o botão.

A sua página de assinatura, em white-label de ponta a ponta

A visibilidade dos botões é a camada mais recente de um conjunto de funcionalidades white-label que as plataformas SaaS já utilizam para fazer com que a assinatura incorporada tenha o aspeto e o comportamento de parte da sua própria aplicação. Os controlos atuais, agrupados pelo local onde o signatário os encontra:

Na página de assinatura

• Botões da página de assinatura (novo): mostrar ou ocultar Recusar assinatura e Guardar e concluir mais tarde.

• Etiquetas dos botões: renomeie nove botões da vista de assinatura por idioma com signing_button_label_overrides, incluindo Recusar assinatura e Guardar e concluir mais tarde. Mais detalhes em etiquetas de botões de assinatura personalizadas.

• Tema de cores: 11 definições hexadecimais color_* ao nível da empresa e do espaço de trabalho. Cinco delas também aplicam o tema aos editores incorporados.

• Definições de visualização: moldura de assinatura, marca de água parcial, código QR, verificação OTP por e-mail, aceitação de termos, navegação guiada e transferência pré-assinatura.

• Termos do signatário: a sua própria declaração de consentimento por idioma, com uma ligação opcional para os termos.

• Cores de fundo dos campos e uma interface de utilizador de assinatura em 15 idiomas, selecionados através do parâmetro lang.

Incorporação

• Assinatura incorporada num iframe que emite eventos postMessage signing.started, signing.completed, signing.declined e signing.error. O guia de início rápido da API de assinatura eletrónica incorporada explica detalhadamente o processo.

• Editores incorporáveis de modelos e pedidos de assinatura com controlos de tema e de fecho.

E-mails

• Um domínio de envio personalizado verificado com SPF, DKIM e DMARC, e a parte local do seu próprio endereço de remetente.

• O seu logótipo (PNG ou JPEG, até 2 MB) nos e-mails de assinatura e certificados.

• Modelos de e-mail personalizados ao nível da empresa ou do espaço de trabalho, além de opções por pedido que desativam os e-mails de assinatura, conclusão, expiração e cancelamento da Firma.dev. Consulte e-mails e hiperligações de assinatura eletrónica white-label.

Após a assinatura

• Uma página de conclusão com o seu próprio título, mensagem e redirecionamento HTTPS, abordada em personalização da página de conclusão.

• Selos organizacionais com o carimbo da sua empresa em PDFs concluídos.

Por cliente

• Com os Espaços de Trabalho de Clientes, todas as definições que suportam o nível de espaço de trabalho podem diferir de cliente para cliente.

As etiquetas e a visibilidade acumulam-se, de modo que um espaço de trabalho pode renomear Recusar assinatura para "Pedir alterações", enquanto outro espaço de trabalho o oculta completamente. O guia completo da API de assinatura eletrónica white-label aborda cada controlo em detalhe, e a página de funcionalidades de assinatura eletrónica white-label disponibiliza a visão geral. Tudo isto está disponível pelo mesmo preço de tudo o resto nos preços da Firma.dev: 0,049 € por envelope (~5¢ USD), pré-pago (pay-as-you-go), sem consumos mínimos mensais nem taxas por utilizador.

Quatro níveis, o mais específico prevalece

Cada botão pode ser configurado em quatro níveis: empresa, espaço de trabalho, modelo e pedido de assinatura. A Firma.dev lê primeiro o valor do próprio pedido de assinatura. Quando este for null, aplica-se o valor do espaço de trabalho, e quando o espaço de trabalho também for null, aplica-se o valor da empresa. A predefinição da empresa é true, e é por isso que nada se altera até definir um valor. Duas regras de temporização tornam-se relevantes assim que isto estiver em produção.

Os modelos são copiados na criação

Um pedido de assinatura criado a partir de um modelo copia os valores do modelo no momento em que é criado. Um valor passado no parâmetro settings da chamada de criação substitui o do modelo, e o valor null reverte para o espaço de trabalho. Editar o modelo mais tarde não afeta os pedidos que já tenham sido criados a partir dele.

As alterações de espaço de trabalho e empresa chegam aos pedidos já enviados

Qualquer pedido de assinatura cujo valor próprio seja null adota as alterações do espaço de trabalho ou da empresa, incluindo pedidos que já tenham sido enviados para assinatura. Mude allow_decline para false num espaço de trabalho ativo e todos os pedidos em aberto sem valor próprio perdem também o botão Recusar... por isso, verifique primeiro o que está em curso.

Onde encontrar no painel de controlo

• Empresa: Definições > Definições da empresa, sob Botões da página de assinatura. Dois seletores definem a predefinição para todos os espaços de trabalho.

• Espaço de trabalho: o separador Definições do espaço de trabalho, sob Botões da página de assinatura. Escolha Mostrar, Ocultar ou Utilizar predefinição da empresa, e a alteração é guardada imediatamente.

• Modelo e pedido de assinatura: o separador de definições do documento na barra lateral do editor, com Mostrar, Ocultar ou Utilizar predefinição do espaço de trabalho. Um pedido de assinatura pode ser alterado até ser enviado.

Execute o seu próprio fluxo de recusa dentro do seu produto

Quando um signatário diz que não, muitos produtos precisam de saber o motivo. Uma ferramenta de vendas precisa dele no registo do negócio, uma aplicação de crédito quer que um gestor de empréstimos ligue de volta e um marketplace quer enviar um orçamento revisto. Com allow_decline: false, a Firma.dev rejeita qualquer recusa no pedido, tornando o botão Recusar na sua própria interface de utilizador na única forma de um signatário dizer que não.

Um fluxo típico decorre da seguinte forma:

1. Defina allow_decline: false no pedido de assinatura, no respetivo modelo ou no espaço de trabalho, e incorpore a página de assinatura num iframe a apontar para https://app.firma.dev/signing/{signing_request_user_id}.

2. Coloque o seu próprio botão Recusar junto ao iframe. Quando o signatário clicar nele, abra a sua própria caixa de diálogo e recolha um motivo.

3. Encaminhe esse motivo para onde ele pertence: uma nota no CRM, um alerta para o gestor de conta, um pedido de suporte.

4. A partir do seu backend, cancele o pedido de assinatura com o motivo anexado.

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/SIGNING_REQUEST_ID/cancel \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Signer declined in app: pricing", "notify_signers": true}'

reason é opcional e tem um limite de 500 carateres. notify_signers tem como predefinição true, por isso defina-o como false se o seu produto enviar a sua própria mensagem ao signatário. A operação de cancelamento funciona num pedido que tenha sido enviado e que ainda não esteja concluído ou cancelado, devolvendo 409 caso contrário. A mesma regra abrange os aprovadores, porque a ocultação de Recusar aplica-se a todos os participantes no pedido.

A Firma.dev está em conformidade com o ESIGN Act, UETA, eIDAS (SES e AES) e UK eIDAS, e as assinaturas são legalmente vinculativas em mais de 55 países, independentemente dos botões que apresentar.

Formulários de assinatura única

Um formulário de uma página com uma única assinatura não tem motivos para ser retomado... oculte Guardar e concluir mais tarde nesse modelo e o signatário tem menos um botão em que pensar.

Um fluxo de trabalho, regras diferentes

Mantenha o botão Recusar ativo como predefinição da empresa e desative-o num único modelo... por exemplo, numa confirmação de política interna, onde a recusa não faz parte do processo. Todos os outros modelos mantêm o botão.

Configure com a API

Todos os quatro níveis aceitam as mesmas duas chaves. A predefinição da empresa aceita apenas true ou false:

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": true, "show_save_for_later": true}'

Uma substituição no espaço de trabalho aceita null para reverter para o valor da empresa:

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/WORKSPACE_ID/settings \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allow_decline": false, "show_save_for_later": null}'

Por pedido, as chaves são incluídas em settings no POST /signing-requests ou POST /signing-requests/create-and-send. Este exemplo utiliza os destinatários do modelo porque não foram passados nenhuns:

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order form - Acme",
    "template_id": "TEMPLATE_ID",
    "settings": {"allow_decline": false, "show_save_for_later": false}
  }'

No PUT /signing-requests/{id} o mesmo objeto fica sob signing_request_properties.settings, e no PUT /templates/{id} sob template_properties.settings. O POST /templates e as rotas PATCH aceitam um settings de nível superior. Qualquer valor diferente de true, false ou null devolve 400 VALIDATION_ERROR identificando a chave, e nada é gravado. A tabela completa de rotas encontra-se no registo de alterações da API para a v1.40.0.

Também na v1.40.0: Um 413 claro para pedidos com tamanho excessivo

Os corpos dos pedidos com mais de 6 MiB devolvem agora 413 REQUEST_TOO_LARGE com a estrutura padrão de error e code. Anteriormente, o gateway respondia com um 502, o que fornecia pouca informação sobre o problema. Para ficheiros maiores, solicite um URL de carregamento com POST /documents, carregue o ficheiro para o mesmo e passe document_id ou document_ids na sua chamada de criação.

Em resumo, a v1.40.0 permite-lhe ocultar Recusar assinatura e Guardar e concluir mais tarde ao nível da empresa, do espaço de trabalho, do modelo ou do pedido. A ocultação do botão Recusar é estritamente aplicada, e o endpoint de cancelamento fornece ao seu próprio fluxo de recusa uma forma simples e limpa de fechar o pedido. E tudo isto assenta sobre o logótipo, cores, etiquetas, termos do signatário, e-mails e página de conclusão que já controla.

Comece a utilizar a Firma.dev gratuitamente, sem necessidade de cartão de crédito.