Firma.dev API v1.10.0: Campos Condicionais, Suporte a DOCX, Rastro de Auditoria e Mais

A API v1.10.0 da Firma.dev já está disponível. Esta é, até à data, a versão mais rica em funcionalidades, trazendo cinco funcionalidades adicionais sem quaisquer alterações de rutura. Se estiver na v1.9.0, a sua integração existente funciona sem modificações. Tudo aqui é nova capacidade, não trabalho de migração.

Aqui está o que vem incluído.

O que há na v1.10.0

As cinco funcionalidades são aditivas. Os novos campos têm por predefinição null ou false. Não há remoção de esquemas, nem alterações de comportamento.

Lógica condicional de campos

Esta é a funcionalidade principal. Os campos podem agora ter required_conditions e visibility_conditions dinâmicos que são avaliados com base nos valores de outros campos no momento da assinatura. Em vez de construir lógica de formulários condicionais na sua própria IU, define as regras uma vez na API e a Firma.dev trata da avaliação tanto no lado do cliente como no do servidor.

A estrutura é componível. Um ConditionSet contém um ou mais objetos ConditionGroup, e cada grupo contém objetos Condition individuais. O operador logic ao nível do conjunto (and ou or) controla a relação entre grupos, enquanto as condições dentro de um grupo usam o operador oposto.

Estão disponíveis dez operadores de comparação: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, e less_than_or_equal.

Aqui está um exemplo prático. Imagine que tem um contrato de trabalho em que um campo para o nome do cônjuge só deve aparecer quando o signatário assinala uma caixa de verificação "Casado":

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

Quando a caixa de verificação não está assinalada, o campo do nome do cônjuge permanece oculto e ignora totalmente a validação. Quando assinalada, aparece e pode ser definido como obrigatório através de uma regra separada required_conditions usando a mesma estrutura.

Eis alguns casos de uso que isto desbloqueia diretamente:

• Campos de divulgação condicional que aparecem apenas quando um signatário seleciona uma opção específica

• Secções de aprovação dependentes em que campos adicionais de aprovação surgem com base num montante em dólares ou nível de risco

• Formulários progressivos que se adaptam à medida que o signatário preenche a informação, mantendo a vista inicial limpa

O detalhe-chave para integrações sensíveis à conformidade: as condições são aplicadas no servidor aquando da submissão. Um signatário não pode contornar as regras de visibilidade ou obrigatoriedade através de manipulação no lado do cliente. Se um campo tiver de ser obrigatório com base no valor de outro campo, a Firma.dev valida isso no servidor antes de aceitar o documento assinado.

Suporte a documentos DOCX

Todos os endpoints de carregamento de documentos agora aceitam ficheiros .docx juntamente com PDF. Quando carrega um documento Word, a Firma.dev converte-o automaticamente para PDF no servidor. Sem pré-processamento no lado do cliente, sem dependências extra no seu pipeline.

Isto aplica-se à criação de modelos, substituição do documento do modelo, criação de pedidos de assinatura e a todas as operações de atualização PUT/PATCH.

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

As integrações PDF existentes não são de todo afetadas. Se já estiver a carregar PDFs, nada muda. Isto apenas remove a etapa de conversão para equipas que criam documentos no Word.

Endpoint de trilho de auditoria

Um novo endpoint GET /signing-requests/{id}/audit devolve o registo cronológico completo de eventos para qualquer pedido de assinatura. Combina tanto as ações do administrador (criado, editado, enviado, cancelado) como as ações do signatário (visualizado, assinado, recusado, transferido) numa única linha temporal.

Cada evento inclui um carimbo de data/hora, origem (admin ou signer), tipo de evento, identidade do interveniente, endereço IP (para eventos do signatário) e metadados específicos do evento.

Este endpoint cobre o pedido de conformidade mais comum: produzir um pacote de evidências que mostra exatamente quem fez o quê, quando e de onde. Quer precise dele para registos de auditoria internos, relatórios regulamentares ou feeds de atividade voltados para clientes, os dados estão todos numa única chamada.

Para o esquema completo da resposta e os detalhes do endpoint, consulte a referência da API do trilho de auditoria.

Controlo da moldura da assinatura

Por predefinição, os PDFs finalizados incluem uma borda visual em torno de cada assinatura com um Signature ID. A nova definição show_signature_frame permite controlar isto em três níveis com uma cadeia de herança simples:

1. Empresa define a predefinição (ativada por defeito)

2. Espaço de trabalho substitui a Empresa (null herda)

3. Pedido de assinatura substitui o Espaço de trabalho (null herda)

Para desativar a moldura ao nível do espaço de trabalho:

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

O principal caso de uso aqui é a marca branca. Se estiver a integrar a Firma.dev no seu próprio produto e quiser assinaturas limpas, sem qualquer moldura da Firma.dev no documento final, defina isto como false ao nível do espaço de trabalho e cada pedido de assinatura nesse espaço herda-o. Inversamente, setores regulados que exijam identificadores de assinatura visíveis podem mantê-lo explicitamente ativado.

Forçar remoção de condições ao eliminar destinatários

Esta é uma melhoria na ergonomia para programadores. Quando elimina um destinatário cujos campos são referenciados nas condições de outros campos (a partir da lógica condicional acima), a API anteriormente não tinha forma de lidar com essa dependência. Agora, o parâmetro force_remove_conditions controla o comportamento:

• false (predefinição): O pedido é rejeitado com um erro que lista os campos dependentes

• true: Remove automaticamente as referências às condições e prossegue com a eliminação

Isto é importante quando está a gerir destinatários programaticamente em fluxos de trabalho dinâmicos. Sem force_remove_conditions, eliminar um destinatário cujos campos alimentam condições noutros campos exigiria limpar manualmente cada referência de condição primeiro.

Resumo técnico

Novos esquemas: ConditionSet, ConditionGroup, Condition

Atualização a partir da v1.9.0

Sem alterações de rutura. Sem remoção de campos. Sem alterações de comportamento. Os novos campos têm por predefinição null ou false, pelo que as integrações existentes não requerem qualquer modificação. Se estiver a vir de uma versão anterior, o mesmo se aplica a cada lançamento desde a v1.0.0. Consulte o registo completo de alterações da API para o histórico completo de versões.

Para detalhes sobre a v1.9.0 (verificação OTP, substituição do documento do modelo), consulte a secção do registo de alterações da v1.9.0.

Começar

É novo na Firma.dev? Preços pay-as-you-go de $0,029 por envelope, sem contratos nem mínimos. Comece a usar a Firma.dev gratuitamente, sem cartão de crédito.

Obter chave API

Para a referência completa da API, consulte a documentação da Firma.dev.