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

Lançámos duas versões da API consecutivas, apenas na última semana. Nada que cause quebras de compatibilidade, mas sim novas funcionalidades… tudo em fevereiro de 2026. 👊

A versão 1.3 chegou com domínios de email personalizados e controlo de custos por créditos. A versão 1.4 seguiu-se com três novos tipos de campos e operações PATCH granulares para campos individuais.

Ambos os lançamentos partilham o mesmo tema: mais controlo sem maior complexidade. E nenhum introduz alterações que causem quebras, para que possa adotar estas funcionalidades ao seu próprio ritmo.

Se procura uma solução de assinatura por API que lhe dê flexibilidade sem forçar migrações, é este o aspeto que tem.

Eis tudo o que há de novo na v1.3 e v1.4.

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

Data de Lançamento: 31 de janeiro de 2026

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

Três Novos Tipos de Campos

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

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

Os Tipos de Campo url

O novo tipo de campo url permite-lhe incorporar ligações clicáveis diretamente nos seus documentos de assinatura. O campo é automaticamente configurado para read_only: true, uma vez que os signatários clicam na ligação em vez de a editarem.

Utilize read_only_value para definir o URL de destino e format_rules.urlDisplayText para personalizar o que os signatários 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": "Visualizar Termos e Condições" }
  }
}

{
  "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": "Visualizar Termos e Condições" }
  }
}

{
  "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": "Visualizar Termos e Condições" }
  }
}

Caso de utilização: Termos e políticas incorporados. Se o seu fluxo de assinatura exigir que os signatários aceitem termos de serviço, políticas de privacidade ou contratos externos, o tipo de campo url mantém tudo num único documento. Os signatários clicam na ligação, analisam o conteúdo de referência e continuam a assinar. Não é necessário anexar múltiplos PDFs ou redirecionar os signatários para páginas externas antes de poderem concluir o fluxo de trabalho.

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

O Tipo de Campo textarea

O tipo de campo textarea suporta entrada de texto multilinha. Utilize-o quando precisar que os signatários forneçam respostas mais longas: instruções especiais, notas de entrega ou qualquer texto de formato livre que não caiba num campo 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 utilizar o endpoint PUT abrangente. Agora, os endpoints PATCH de Modelo e de Pedido de Assinatura suportam operações em campos individuais.

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

• Propriedades do modelo

• Um único utilizador

• Apenas um campo (novo na v1.4)

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

• Propriedades do pedido de assinatura

• Um único destinatário

• Apenas um campo (novo na 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 de ajustar a posição de um único campo, alterar o estado obrigatório de um campo ou adicionar um novo campo sem reconstruir todo o payload do modelo.

Correspondência de Utilizadores de Modelos com template_user_id

Ao criar pedidos de assinatura a partir de modelos, pode agora utilizar template_user_id para corresponder explicitamente os destinatários aos utilizadores 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 da v1.4, a correspondência de destinatários dependia da propriedade order. Essa forma ainda funciona como alternativa, mas o template_user_id elimina ambiguidades. Se o seu modelo tiver múltiplos signatários e quiser garantir que a Jane recebe a função de "Comprador" (e não a função de "Vendedor"), a correspondência explícita garante que a pessoa certa recebe os campos certos.

Alterações de Esquema na v1.4

Enum do 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ários inclui agora template_user_id para uma correspondência explícita do utilizador do modelo ao criar pedidos de assinatura.

v1.3.0: Domínios de Email Personalizados e Visibilidade de Utilização

A versão 1.3 introduziu a API de Domínios de Email para o envio de emails em marca branca, recolha de custos por créditos para visibilidade de utilização e tratamento de estados recusados para pedidos de assinatura.

API de Domínios de Email

Uma categoria completa de API para configurar domínios de email personalizados. Em vez de os emails de pedido de assinatura virem de noreply@firma.dev, podem vir de signing@yourbrand.com.

Oito novos endpoints:

Novos esquemas:

• Domain: Configuração de domínio de email com estado de verificação

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

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

Caso de utilização: Emails de assinatura em marca branca. Se está a construir uma integração de API de assinatura eletrónica para o seu produto SaaS, os seus clientes esperam que os emails venham da sua marca. Um email de pedido de assinatura de contracts@yourplatform.com gera confiança. Um email de noreply@firma.dev levanta dúvidas.

Os domínios de email personalizados combinam bem com as Áreas de Trabalho de Clientes para implementações completas em marca branca. Cada um dos seus clientes recebe uma área de trabalho isolada com modelos e pedidos de assinatura que nunca mencionam o Firma.dev na experiência do signatário.

Para uma análise mais detalhada sobre as opções de marca branca, consulte os nossos guias sobre API de assinatura de documentos em marca branca e emails de assinatura eletrónica em marca branca.

Controlo de Custos por Créditos

Dois novos campos proporcionam visibilidade sobre a utilização de créditos:

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

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

Uma nova definição de área de trabalho, show_credit_cost_in_editor, permite-lhe alternar se os custos por créditos são apresentados nos editores de modelos e de assinaturas incorporados.

Isto é importante para plataformas SaaS que repercutem os custos nos clientes ou que precisam de controlar a utilização por área de trabalho. Com o custo por créditos visível ao nível do modelo e do pedido de assinatura, pode criar painéis de faturação, definir alertas de utilização ou mostrar aos clientes o seu consumo sem ter de consultar endpoints de analítica separados.

A 0,049 € por envelope, os custos mantêm-se previsíveis. Mas a visibilidade sobre para onde vão esses créditos ajuda a otimizar.

Estado de Pedido de Assinatura Recusado

Os pedidos de assinatura agora suportam o estado declined:

• Adicionado declined aos valores enum de SigningRequest.status

• Adicionado o campo date_declined ao esquema SigningRequest

Quando um signatário se recusa a assinar, verá isso refletido no estado e no carimbo de data/hora. Isto complementa os campos declined_on e decline_reason no SigningRequestUser adicionados na v1.2.

Melhorias no Esquema da v1.3

Campos do modelo:

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

• Descrição melhorada de multi_group_id para explicar o agrupamento de campos mutuamente exclusivos para caixas de seleção e botões de rádio

• Esclareceu-se que page_number tem índice baseado em 1 e não deve exceder a contagem de páginas do documento

Campos do pedido de assinatura:

• As mesmas melhorias do multi_group_id feitas nos campos do modelo

Notas de Migração

Nem a v1.3 nem a v1.4 introduzem alterações que causem quebras de compatibilidade.

Migrar da v1.2 para a v1.3:

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

• O estado declined foi adicionado ao enum de estados dos pedidos de assinatura

• O controlo de custos por créditos está disponível nos modelos e nos pedidos de assinatura

Migrar da v1.3 para a v1.4:

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

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

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

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

Guia de Integração da API de Assinatura Eletrónica

Firma.dev foi desenhado para criadores de software que precisam de adicionar assinaturas de documentos aos seus produtos sem o fardo de contratos empresariais ou integrações complexas. Modelo de preços pré-pago a 0,049 € por envelope. Sem mínimos. Sem contratos.

Estes lançamentos refletem o feedback dos nossos clientes: mais flexibilidade de campos, melhor capacidade de marca branca e controlo granular sobre os modelos e pedidos de assinatura.

Consulte o registo de alterações completo da API para ver o histórico de versões e guias de migração. Ou comece a programar já.

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