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

Enviámos duas versões da API seguidas, apenas na última semana. Nada a quebrar, mas novas funcionalidades... tudo em fevereiro de 2026. 👊

A Versão 1.3 chegou com domínios de email personalizados e rastreamento de custo de crédito. A Versão 1.4 seguiu 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 críticas, para que possa adotar estas funcionalidades ao seu próprio ritmo.

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

Aqui está tudo novo nas 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 os campos de documento e como atualizá-los. Três novos tipos de campo oferecem mais opções para recolher dados. As operações PATCH agora suportam atualizações de campo individual. E um novo parâmetro template_user_id torna o emparelhamento de destinatários explícito.

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 já que os assinantes clicam no link em vez de o editar.

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" }
  }
}

Exemplo de uso: Termos e políticas embutidos. Se o seu fluxo de assinatura exigir 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 há necessidade de anexar múltiplos PDFs ou redirecionar os assinantes para páginas externas antes de concluir o fluxo de trabalho.

Isto é especialmente útil para plataformas SaaS onde os termos mudam frequentemente. Atualize o URL vinculado 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 multilinha. Use-o quando precisar que os assinantes forneçam respostas mais longas: instruções especiais, notas de entrega ou qualquer texto em formulário 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 a carga completa do modelo ou usar o ponto de extremidade PUT completo. Agora, tanto o Template quanto os pontos de extremidade PATCH do Pedido de Assinatura suportam operações de campo único.

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

• Propriedades do template

• 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 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 único campo, alterar o status de exigência de um campo ou adicionar um novo campo sem reconstruir a carga completa do modelo.

Correspondência de Utilizador de Template com template_user_id

Ao criar pedidos de assinatura a partir de modelos, agora pode usar template_user_id para corresponder explicitamente destinatários a utilizadores do template:

{
  "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. Isso ainda funciona como alternativa, mas template_user_id remove a ambiguidade. Se o seu template tiver vários assinantes e quiser garantir que Jane receba o papel de "Comprador" (e não o de "Vendedor"), a correspondência explícita garante que a pessoa certa receba os campos corretos.

Alterações de Esquema na v1.4

Enumeração de tipo 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 de destinatário agora inclui template_user_id para correspondência explícita de utilizador de template 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 emails de marca branca, rastreamento de custo de crédito para visibilidade de uso, e o tratamento de estado de recusado para pedidos de assinatura.

API de Domínios de Email

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

Oito novos pontos de extremidade:

Novos esquemas:

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

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

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

Exemplo de uso: Emails de assinatura de 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 constrói confiança. Um email de noreply@firma.dev levanta questões.

Os domínios de email personalizados combinam bem com Workspaces de Cliente para implementações completas de marca branca. Cada um dos seus clientes obtém um workspace isolado com templates e pedidos de assinatura que nunca referenciam Firma.dev na experiência de assinante.

Para uma visão mais aprofundada sobre opções de marca branca, veja os nossos guias sobre API de assinatura de documentos de marca branca e emails de assinatura eletrónica de marca branca.

Rastreamento de Custo de Crédito

Dois novos campos fornecem visibilidade no uso de crédito:

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

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

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

Isto é importante para plataformas SaaS que passam custos para os clientes ou precisam rastrear o uso por workspace. Com o custo de crédito visível ao nível do template 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 pontos de extremidade analíticos separados.

A $0.029 por envelope, os custos permanecem previsíveis. Mas a visibilidade de onde vão esses créditos ajuda a otimizar.

Estado de Recusado do Pedido de Assinatura

Os pedidos de assinatura agora suportam um estado declined:

• Adicionado declined aos valores enum de SigningRequest.status

• Adicionado campo date_declined ao esquema SigningRequest

Quando um assinante recusa assinar, verá isso refletido no estado 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 de Template:

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

• Descrição aprimorada de multi_group_id para explicar a agrupagem mutuamente exclusiva de campos para caixas de seleção e botões de rádio

• 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:

• Mesmas melhorias de multi_group_id que nos campos de template

Notas de Migração

Nem a v1.3 nem a v1.4 introduzem alterações críticas.

Migrar da v1.2 para a v1.3:

• Configuração de domínio de email está disponível mas é opcional

• Status declined adicionado ao enum de status do pedido de assinatura

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

Migrar da v1.3 para a v1.4:

• Tipo de campo radio renomeado para radio_buttons (ambos aceitos para compatibilidade retroativa)

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

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

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

Construa A Integração da API de Assinatura Eletrónica

irma.dev é feita para desenvolvedores que precisam adicionar assinatura de documentos aos seus produtos sem o overhead de contratos empresariais ou integrações complexas. Preço por uso a $0.029 por envelope. Sem mínimos. Sem contratos.

Estas versões refletem o que ouvimos dos clientes: mais flexibilidade de campos, melhor marca branca, e controlo granular sobre templates e pedidos de assinatura.

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

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