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 incompatível, mas novas funcionalidades … tudo em fevereiro de 2026. 👊

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

Ambas as versões partilham o mesmo tema: mais controlo sem mais complexidade. E nenhuma introduz alterações incompatíveis, pelo que pode adotar estas funcionalidades ao seu ritmo.

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

Aqui está tudo o que há de novo na 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 a forma como os atualiza. Três novos tipos de campo dão-lhe mais opções para recolher dados. As operações PATCH passam agora a suportar atualizações de campos individuais. E um novo template_user_id torna explícita a correspondência de destinatários.

Três Novos Tipos de Campo

A enumeração de tipos de campo inclui agora textarea, url e radio_buttons:

O tipo radio continua a funcionar por compatibilidade retroativa, mas radio_buttons é o nome canónico daqui em diante.

O Tipo de Campo url

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

Use 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": "Ver Termos & 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": "Ver Termos & 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": "Ver Termos & Condições" }
  }
}

Caso de uso: termos e políticas incorporados. Se o seu fluxo de assinatura exigir que os signatários reconheçam os termos de serviço, as 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, reveem o conteúdo referenciado e continuam a assinar. Não há necessidade de anexar vários PDFs nem de 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 com frequência. Atualize o URL associado uma vez e todos os novos pedidos de assinatura apontam para a versão atual.

O Tipo de Campo textarea

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

Operações PATCH para Campos Individuais

Anteriormente, atualizar um único campo num modelo significava enviar a carga útil completa do modelo ou usar o endpoint PUT abrangente. Agora, tanto os endpoints PATCH de Template como de Signing Request suportam operações de campo único.

Template PATCH (PATCH /templates/{id}) pode atualizar:

• Propriedades do modelo

• Um único utilizador

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

Signing Request PATCH (PATCH /signing-requests/{id}) pode atualizar:

• Propriedades do pedido de assinatura

• Um único destinatário

• Um único 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 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 a carga útil completa do modelo.

Correspondência de Utilizadores do Modelo com template_user_id

Ao criar pedidos de assinatura a partir de modelos, pode agora usar template_user_id para corresponder explicitamente 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 baseava-se na propriedade order. Continua a funcionar como alternativa, mastemplate_user_id elimina a ambiguidade. Se o seu modelo tiver vários signatários e quiser garantir que a Jane recebe a função "Buyer" (e não a função "Seller"), a correspondência explícita garante que a pessoa certa recebe os campos certos.

Alterações ao Esquema da v1.4

Enumeração de tipos de campo atualizada 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"]

Esquema do destinatário inclui agora template_user_id para correspondência explícita de utilizadores 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 Email Domains para envio de emails de marca branca, acompanhamento do custo em créditos para visibilidade de utilização e tratamento do estado declined nos pedidos de assinatura.

API Email Domains

Uma categoria de API completa 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 do domínio de email com estado de verificação

• DomainDnsRecord: Detalhes do registo DNS para verificação do 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 principal de envio.

Caso de uso: emails de assinatura de marca branca. Se estiver a desenvolver uma integração de API de assinatura eletrónica para o seu produto SaaS, os seus clientes esperam que os emails provenham da sua marca. Um email de pedido de assinatura de contracts@yourplatform.com gera confiança. Um email de noreply@firma.dev levanta questões.

Os domínios de email personalizados combinam bem com Espaços de Trabalho do Cliente para implementações completas de marca branca. Cada um dos seus clientes recebe um espaço de trabalho isolado com modelos e pedidos de assinatura que nunca fazem referência à Firma.dev na experiência do signatário.

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

Acompanhamento do Custo em Créditos

Dois novos campos fornecem 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 do espaço de trabalho, show_credit_cost_in_editor, permite alternar se os custos em créditos são mostrados nos editores incorporados de modelos e de assinatura.

Isto é importante para plataformas SaaS que repercutem custos nos clientes ou precisam de acompanhar a utilização por espaço de trabalho. Com o custo em 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 consultar endpoints analíticos separados.

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

Estado declined do Pedido de Assinatura

Os pedidos de assinatura suportam agora o estado declined:

• Adicionado declined aos valores da enumeração SigningRequest.status

• Adicionado o campo date_declined ao esquema SigningRequest

Quando um signatário recusa assinar, isso fica refletido no estado e no carimbo temporal. Isto complementa os campos declined_on e decline_reason em SigningRequestUser que foram lançados na v1.2.

Melhorias ao Esquema da v1.3

Campos do modelo:

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

• Descrição de multi_group_id melhorada para explicar o agrupamento mutuamente exclusivo de campos para caixas de verificação e botões de opção

• Esclarecido que page_number começa em 1 e não pode exceder o número de páginas do documento

Campos do pedido de assinatura:

• As mesmas melhorias de multi_group_id dos campos do modelo

Notas de Migração

Nem a v1.3 nem a v1.4 introduzem alterações incompatíveis.

Migração da v1.2 para a v1.3:

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

• Estado declined adicionado à enumeração de estados do pedido de assinatura

• O acompanhamento do custo em créditos está disponível em modelos e pedidos de assinatura

Migração da v1.3 para a v1.4:

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

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

• 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ções.

Crie a Sua Integração de API de Assinatura Eletrónica

irma.dev foi criado para programadores que precisam de adicionar assinatura de documentos aos seus produtos sem a complexidade 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 nos campos, melhor personalização de marca branca e controlo granular sobre modelos e pedidos de assinatura.

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

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