Novo no Firma.dev: Comprovativo de que o Signatário Introduziu o Código Único, em Cada Certificado

A API v1.40.3 da Firma.dev foi lançada a 20 de outubro de 2026 e altera o que o código de uso único por e-mail deixa registado. Quando um pedido de assinatura exige o código, o momento em que o signatário o introduz corretamente passa a ser registado na pista de auditoria, com a hora e o endereço IP, e impresso no certificado de conclusão.

Novo: A verificação do código passa a constar do registo

A Firma.dev regista agora a introdução do código em dois locais. A pista de auditoria recebe um novo evento otp_verified, registado quando o signatário introduz o código correto. O certificado de conclusão imprime, para cada signatário, como se autenticou e quando o código foi verificado. Ambos aplicam-se a pedidos de assinatura concluídos a partir de 20 de outubro. Os certificados emitidos antes dessa data mantêm-se exatamente como estavam.

O que o certificado de conclusão apresenta

Cada linha de signatário no certificado inclui agora uma linha de Autenticação, apresentada de uma de duas formas:

• Email Link, para um signatário que assinou sem código de uso único

• Email Link + One-Time Code (code verified <hora>), para um signatário que introduziu o código

A linha Identidade junto ao topo resume todo o pedido. Quando todos os signatários se autenticaram da mesma forma, apresenta esse método. Quando diferem, apresenta "Mixed (see signers)", indicando que deve consultar as linhas individuais.

Um esquema simplificado de uma linha de signatário para quem utilizou o código:

Signer:          Alice Johnson (alice@example.com)
Viewed:          2026-10-21 09:14:11
Authentication:  Email Link + One-Time Code (code verified 2026-10-21 09:14:03)

Signer:          Alice Johnson (alice@example.com)
Viewed:          2026-10-21 09:14:11
Authentication:  Email Link + One-Time Code (code verified 2026-10-21 09:14:03)

Signer:          Alice Johnson (alice@example.com)
Viewed:          2026-10-21 09:14:11
Authentication:  Email Link + One-Time Code (code verified 2026-10-21 09:14:03)

A hora do código surge antes da hora de visualização (Viewed) nesse esquema, o que é expectável. O signatário introduz o código antes de o documento ser carregado, pelo que a verificação ocorre antes da primeira visualização (pareceria estranho no papel se não soubesse o motivo).

O que a pista de auditoria regista

O novo evento é o otp_verified, descrito como "Entered the one-time code sent by email". Como qualquer evento de signatário, inclui um carimbo de data/hora, o nome e o e-mail do signatário como interveniente, e o respetivo endereço IP. Abra qualquer pedido de assinatura no painel de controlo e clique no separador Pista de Auditoria para o visualizar na cronologia, juntamente com as visualizações, o preenchimento de campos e as assinaturas.

O código em si nunca é incluído. O evento faz referência ao registo do código verificado através do respetivo ID, pelo que a pista associa a introdução a um código específico sem expor o código a quem quer que a consulte.

Quando o signatário conclui, o evento document_finished inclui essa mesma referência, desde que a sessão de conclusão tenha estado associada a um código verificado. Desta forma, associa-se a introdução do código à assinatura concluída, na mesma pista...

Para mais informações sobre o que deve conter uma pista completa, consulte o nosso artigo explicativo sobre a pista de auditoria de assinaturas eletrónicas e a página de funcionalidades da pista de auditoria.

Por que motivo é importante quando surgem dúvidas mais tarde

Imagine um contrato assinado há seis meses... o signatário diz agora que nunca o viu, ou um auditor a verificar a documentação de fornecedores quer saber como confirmou a identidade de quem assinou. Ambas as questões apontam para o mesmo documento.

Com o código de uso único ativado, o certificado responde a ambas numa só página. Demonstra que o signatário comprovou o acesso ao seu endereço de e-mail ao introduzir o código e indica quando o fez. A pista de auditoria acrescenta o endereço IP a partir do qual o código foi introduzido. Pode reencaminhar o certificado tal como está, sem que ninguém tenha de pesquisar em painéis de controlo ou em históricos de e-mails para reconstituir a cronologia...

A Firma.dev está em conformidade com o ESIGN Act, o UETA, o eIDAS (SES e AES) e o eIDAS do Reino Unido, e as assinaturas efetuadas com a mesma são juridicamente vinculativas em mais de 55 países. A prova do código de uso único abrange a perspetiva do signatário no registo. Se também pretender incluir a perspetiva da sua empresa no documento final, os selos de organização permitem-no, e ambos funcionam em perfeita sintonia.

Ativar o código de uso único

Pode exigir o código para todo um espaço de trabalho nas respetivas definições (essa alteração tem de ser feita por um Proprietário) ou por pedido através da API com settings.require_otp_verification:

{
  "settings": {
    "require_otp_verification": true
  }
}

{
  "settings": {
    "require_otp_verification": true
  }
}

{
  "settings": {
    "require_otp_verification": true
  }
}

A verificação é realizada exclusivamente por e-mail. Os signatários recebem o código na sua caixa de entrada e introduzem-no antes da abertura do documento. Saiba mais sobre o fluxo do signatário na página de funcionalidades do OTP por e-mail.

O código não tem custos adicionais. Paga 0,049 € por envelope (~5¢ USD), no modelo pay-as-you-go, sem consumos mínimos mensais nem custos por utilizador. Mais detalhes na página de preços.

Para programadores: Obter as provas a partir da API

GET /signing-requests/{id}/audit devolve a lista completa de eventos em results. Filtre pelo event correspondente a otp_verified e, de seguida, consulte timestamp, ip_address e details.otp_code_id. Um evento assemelha-se a isto:

{
  "id": "a1b2c3d4-0000-0000-0000-000000000007",
  "timestamp": "2026-10-21T09:14:03.000Z",
  "source": "signer",
  "event": "otp_verified",
  "description": "Entered the one-time code sent by email",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42",
  "details": {
    "channel": "email",
    "otp_code_id": "5f0c9e2a-0000-0000-0000-000000000001"
  }
}

{
  "id": "a1b2c3d4-0000-0000-0000-000000000007",
  "timestamp": "2026-10-21T09:14:03.000Z",
  "source": "signer",
  "event": "otp_verified",
  "description": "Entered the one-time code sent by email",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42",
  "details": {
    "channel": "email",
    "otp_code_id": "5f0c9e2a-0000-0000-0000-000000000001"
  }
}

{
  "id": "a1b2c3d4-0000-0000-0000-000000000007",
  "timestamp": "2026-10-21T09:14:03.000Z",
  "source": "signer",
  "event": "otp_verified",
  "description": "Entered the one-time code sent by email",
  "actor": { "name": "Alice Johnson", "email": "alice@example.com" },
  "ip_address": "203.0.113.42",
  "details": {
    "channel": "email",
    "otp_code_id": "5f0c9e2a-0000-0000-0000-000000000001"
  }
}

Os eventos document_finished também incluem details.otp_code_id quando a sessão de conclusão esteve associada a um código verificado, permitindo assim associar a conclusão à introdução do código. Estes eventos aplicam-se a pedidos com menos de 1000 linhas de rastreio. Pedidos maiores mantêm o truncamento existente.

As respostas de verify-signing-otp também se tornaram mais precisas nesta versão:

• 404 SIGNING_USER_NOT_FOUND para um signatário desconhecido

• 404 SIGNING_REQUEST_NOT_FOUND quando o pedido foi eliminado

• 400 INVALID_INPUT para um signingUserId com formato incorreto

• 200 com code: "SIGNING_STATE_CHANGED" e um state quando o pedido já não pode ser assinado (cancelado, recusado, expirado, já assinado e afins)

• 500 INTERNAL para uma falha na base de dados

Um código correto que encontre uma falha transitória já não consome uma das tentativas do signatário. Não há alterações ao esquema OpenAPI e event continua a ser uma cadeia de texto livre.

As descrições administrativas também mudaram. Um cancelamento a partir do painel de controlo surge agora como "Signing Request Cancellation requested", uma eliminação surge como "Signing Request Deletion requested" e uma nova tentativa de certificado acrescenta "Certificate regeneration requested". A Firma.dev regista cada linha antes de a alteração ocorrer, pelo que "requested" regista o pedido e não confirma a sua conclusão. Verifique o estado do pedido antes de agir sobre uma destas linhas. As linhas registadas antes da v1.40.3 mantêm a redação antiga.

A lista completa encontra-se no registo de alterações da API e no guia da pista de auditoria.

Resumo

Ative o código de uso único e cada pedido concluído a partir de 20 de outubro passará a conter prova do mesmo: um evento otp_verified com o carimbo de data/hora e o endereço IP na pista de auditoria, bem como uma linha de Autenticação na linha de cada signatário no certificado.

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