Firma.dev API v1.3 + v1.4: Novos Tipos de Campo, Domínios de Email Personalizados e Controlo Granular

Lançámos duas versões de API consecutivas, apenas na última semana. Nada significativo a alterar, mas novas funcionalidades … tudo em fevereiro de 2026. 👊

A Versão 1.3 foi lançada com domínios de e-mail personalizados e acompanhamento de custos de crédito. A Versão 1.4 seguiu com três novos tipos de campo e operações PATCH detalhadas para campos individuais.

Ambas as versões partilham o mesmo tema: mais controlo sem mais complexidade. E nenhuma introduz alterações que quebrem a compatibilidade, para que possa adotar estas funcionalidades ao seu próprio ritmo.

Se está à procura de uma solução de assinatura de API que lhe dê flexibilidade sem forçar migrações, é isso que parece.

Aqui está tudo o que há de novo no v1.3 e v1.4.

v1.4.0: Novos Tipos de Campo e Atualizações Granulares

Data de Lançamento: 31 de janeiro de 2026

A Versão 1.4 expande o que pode fazer com campos de documentos e como os atualiza. Três novos tipos de campo oferecem mais opções para a recolha de dados. As operações PATCH agora suportam atualizações de campo individuais. E um novo parâmetro template_user_id torna a correspondência de destinatários explícita.

Três Novos Tipos de Campo

O enum de tipo de campo agora inclui textarea, url e radio_buttons:

O tipo radio ainda funciona para compatibilidade retroativa, mas radio_buttons é o nome canónico daqui em diante.

Os Tipos de Campo url

O novo tipo de campo url permite incorporar links clicáveis diretamente nos seus documentos de assinatura. O campo é automaticamente definido como read_only: true uma vez que os assinantes clicam no link em vez de o editarem.

Use read_only_value para definir o URL alvo e format_rules.urlDisplayText para personalizar o que os assinantes veem:

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

Uso: Termos e políticas incorporados. Se o seu fluxo de assinatura requer que os assinantes reconheçam os termos de serviço, políticas de privacidade ou contratos externos, o tipo de campo url mantém tudo num documento. Os assinantes clicam no link, revêem o conteúdo referenciado e continuam a assinar. Não é necessário anexar vários PDFs ou redirecionar os assinantes para páginas externas antes que possam concluir o fluxo de trabalho.

Isto é especialmente útil para plataformas SaaS onde os termos mudam frequentemente. Atualize o URL ligado uma vez e cada novo pedido de assinatura aponta para a versão atual.

O Tipo de Campo textarea

O tipo de campo textarea suporta entrada de texto em várias linhas. Use-o quando precisar que os assinantes forneçam respostas mais longas: instruções especiais, notas de entrega ou qualquer texto em formato livre que não caiba num campo de text de linha única.

Operações PATCH para Campos Individuais

Anteriormente, atualizar um único campo num modelo significava enviar o payload completo do modelo ou usar o endpoint PUT abrangente. Agora, tanto os endpoints PATCH de Pedido de Assinatura quanto de Modelo suportam operações de campo único.

PATCch de Modelo (PATCH /templates/{id}) pode atualizar:

• Propriedades do modelo

• Um único utilizador

• Um único campo (novo no v1.4)

PATCch de Pedido de Assinatura (PATCH /signing-requests/{id}) pode atualizar:

• Propriedades do pedido de assinatura

• Um único destinatário

• Um único campo (novo no v1.4)

Para criar um novo campo, inclua o objeto field sem um id:

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

Para atualizar um campo existente, inclua o field.id:

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

Esta abordagem granular simplifica a gestão de campos quando precisa ajustar a posição de um campo único, alterar o estado requerido de um campo ou adicionar um novo campo sem reconstruir o entire payload do modelo.

Correspondência de Usuário de Modelo com template_user_id

Ao criar pedidos de assinatura a partir de modelos, agora pode usar template_user_id para corresponder explicitamente os destinatários aos usuários do modelo:

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

Antes do v1.4, a correspondência de destinatários baseava-se na propriedade ordem. Isso ainda funciona como solução de recurso, mastemplate_user_id remove qualquer ambiguidade. Se o seu modelo tem vários assinantes e você deseja garantir que Jane receba o papel de "Comprador" (não o papel de "Vendedor"), a correspondência explícita garante que a pessoa certa receba os campos certos.

Alterações no Esquema v1.4

Enum de tipo de campo atualizado de:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

Para:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

O esquema de destinatário agora inclui template_user_id para correspondência explícita de usuários de modelo ao criar pedidos de assinatura.

v1.3.0: Domínios de Email Personalizados e Visibilidade de Uso

A Versão 1.3 introduziu a API de Domínios de Email para envio de e-mails com rótulo branco, acompanhamento dos custos de crédito para visibilidade de uso e manuseio de status recusado para pedidos de assinatura.

API de Domínios de Email

Uma categoria completa de API para configurar domínios de e-mail personalizados. Em vez de os e-mails de pedidos de assinatura serem enviados de noreply@firma.dev, eles podem ser enviados de signing@yourbrand.com.

Oito novos endpoints:

Novos esquemas:

• Domínio: Configuração de domínio de e-mail com status de verificação

• DomainDnsRecord: Detalhes do registro DNS para verificação de domínio

O fluxo de verificação funciona como a maioria das configurações de domínios de e-mail: adicione o seu domínio, verifique a propriedade com um registro TXT, configure SPF/DKIM/DMARC, finalize com o provedor de e-mail e defina o seu domínio de envio principal.

Uso: E-mails de assinatura com rótulo branco. Se está a construir uma integração de API de assinatura eletrónica para o seu produto SaaS, os seus clientes esperam que os e-mails venham da sua marca. Um e-mail de pedido de assinatura de contracts@yourplatform.com constrói confiança. Um e-mail de noreply@firma.dev levanta questões.

Domínios de email personalizados combinam bem com Espaços de Trabalho do Cliente para implementações com rótulo branco completo. Cada um dos seus clientes recebe um espaço de trabalho isolado com modelos e pedidos de assinatura que nunca fazem referência ao Firma.dev na experiência do signatário.

Para uma visão mais aprofundada das opções de rótulo branco, veja os nossos guias sobre API de assinatura de documentos com rótulo branco e e-mails de e-assinatura com rótulo branco.

Acompanhamento de Custos de Crédito

Dois novos campos fornecem visibilidade sobre o uso de créditos:

• credit_cost no esquema Modelo: Número de créditos consumidos ao enviar um pedido de assinatura a partir deste modelo

• credit_cost no esquema Pedido de Assinatura: Créditos consumidos quando este pedido de assinatura foi enviado

Uma nova configuração de espaço de trabalho, show_credit_cost_in_editor, permite alternar se os custos de crédito são exibidos nos editores incorporados de modelo e assinatura.

Isto é importante para plataformas SaaS que repassam custos para clientes ou precisam de monitorar o uso por espaço de trabalho. Com o custo de crédito visível ao nível do modelo e do pedido de assinatura, pode construir painéis de faturação, definir alertas de uso ou mostrar aos clientes o seu consumo sem consultar endpoints analíticos separados.

A um custo de €0.029 por envelope, os custos mantêm-se previsíveis. Mas a visibilidade sobre onde esses créditos são gastos ajuda a otimizar.

Status de Pedido de Assinatura Recusado

Os pedidos de assinatura agora suportam um status recusado:

• Adicionado recusado aos valores do enum SigningRequest.status

• Adicionado campo date_declined ao esquema SigningRequest

Quando um assinante recusa-se a assinar, isso será refletido no status e no carimbo de data/hora. Isto complementa os campos declined_on e decline_reason em SigningRequestUser que foram lançados na v1.2.

Melhorias no Esquema v1.3

Campos do Modelo:

• Adicionado campo date_default para definir valores de data padrão (formato ISO 8601)

• Aprimorada a descrição do multi_group_id para explicar agrupamento de campos mutuamente exclusivo para caixas de seleção e botões de opção

• Esclarecido que page_number é indexado a partir de 1 e não deve exceder o número de páginas do documento

Campos de pedido de assinatura:

• Mesma melhoria de multi_group_id que os campos do modelo

Notas de Migração

Nem o v1.3 nem o v1.4 introduzem alterações que quebrem a compatibilidade.

Ao migrar do v1.2 para o v1.3:

• A configuração de domínios de email está disponível mas é opcional

• Status recusado adicionado ao enum de status de pedido de assinatura

• Rastreamento de custo de crédito disponível em modelos e pedidos de assinatura

Ao migrar do v1.3 para o v1.4:

• O tipo de campo radio foi renomeado para radio_buttons (ambos são aceitos para compatibilidade retroativa)

• Novas capacidades PATCH para atualizações granulares de campo

• template_user_id disponível para correspondência explícita de destinatários

Pode adotar estas funcionalidades de forma incremental. As integrações existentes continuam a funcionar sem modificação.

Construa Sua Integração de API de Assinatura Eletrónica

Firma.dev é construído para desenvolvedores que precisam adicionar assinatura de documentos aos seus produtos sem a sobrecarga de contratos empresariais ou integrações complexas. Preços pay-as-you-go a €0.029 por envelope. Sem mínimos. Sem contratos.

Estas versões refletem o que ouvimos dos clientes: mais flexibilidade de campo, melhor rotulagem branca e controle granular sobre modelos e pedidos de assinatura.

Consulte o histórico completo de alterações da API para histórico de versões e guias de migração. Ou comece a construir agora.

Comece com a Firma.dev gratuitamente—não é necessário cartão de crédito.