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

A API v1.10.0 do Firma.dev está disponível. Esta é a versão com mais funcionalidades até à data, trazendo cinco funcionalidades adicionais sem quaisquer alterações estruturais. Se está na v1.9.0, a sua integração atual funciona sem modificações. Tudo o que está aqui são novas capacidades, não trabalhos de migração.

Eis o que está incluído.

O que há na v1.10.0

As cinco funcionalidades são cumulativas. Os novos campos têm como valor predefinido null ou false. Sem remoções de esquemas, sem alterações de comportamento.

Lógica de campos condicionais

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

A estrutura é associá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 dos grupos entre si, ao passo que 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.

Eis um exemplo prático. Imagine que tem um contrato de trabalho onde um campo para o nome do cônjuge apenas deve aparecer quando o assinante seleciona 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 está desmarcada, o campo do nome do cônjuge permanece oculto e ignora totalmente a validação. Quando assinalada, aparece e pode ser definida como obrigatória através de uma regra required_conditions separada que utiliza a mesma estrutura.

Alguns casos de uso que isto possibilita diretamente:

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

• Secções de aprovação dependentes onde surgem campos adicionais de aprovação com base num valor monetário ou nível de risco

• Formulários progressivos que se adaptam à medida que o assinante preenche as informações, mantendo a visualização inicial limpa

O detalhe fundamental para integrações sensíveis à conformidade: as condições são aplicadas no lado do servidor aquando do envio. Um assinante não pode contornar a visibilidade ou as regras de obrigatoriedade por meio de adulteração no lado do cliente. Se um campo deve ser obrigatório com base no valor de outro campo, o Firma.dev valida isso no lado do servidor antes de aceitar o documento assinado.

Suporte de documentos DOCX

Todos os endpoints de carregamento de documentos aceitam agora ficheiros .docx juntamente com PDFs. Ao carregar um documento Word, o Firma.dev converte-o automaticamente para PDF do lado do servidor. Sem pré-processamento do lado do cliente, sem dependências adicionais no seu fluxo de trabalho.

Isto aplica-se à criação de modelos, substituição de documentos de modelos, criação de pedidos de assinatura e 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 existentes de PDF não são afetadas de forma alguma. Se já carrega PDFs, nada muda. Isto apenas remove a etapa de conversão para as equipas que redigem documentos no Word.

Endpoint de pista de auditoria

Um novo endpoint GET /signing-requests/{id}/audit devolve o registo cronológico completo de eventos para qualquer pedido de assinatura. Associa tanto as ações de administração (criadas, editadas, enviadas, canceladas) como as ações dos assinantes (visualizadas, assinadas, recusadas, descarregadas) numa única linha do tempo.

Cada evento inclui uma marca temporal, origem (admin ou signer), tipo de evento, identidade do agente, endereço IP (para eventos de assinantes) e metadados específicos do evento.

Este endpoint cobre o requisito de conformidade mais comum: produzir um pacote de provas que mostra exatamente quem fez o quê, quando e a partir de onde. Quer necessite dele para registos de auditoria interna, relatórios regulamentares ou fluxos de atividade voltados para o cliente, os dados estão todos numa única chamada.

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

Controlo da moldura de assinatura

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

1. A Empresa define o padrão (ativado por predefinição)

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

3. O 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 incorporar o Firma.dev no seu próprio produto e pretender assinaturas limpas sem qualquer moldura do Firma.dev no documento final, defina isto como false ao nível do espaço de trabalho e todos os pedidos de assinatura nesse espaço de trabalho irão herdá-lo. Por outro lado, setores regulados que exigem identificadores de assinatura visíveis podem explicitamente mantê-la ativada.

Forçar remoção de condições ao eliminar utilizadores

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

• false (predefinido): O pedido é rejeitado com um erro que lista os campos dependentes

• true: Remove automaticamente as referências de condição e prossegue com a eliminação

Isto é importante se gere destinatários programaticamente em fluxos de trabalho dinâmicos. Sem o parâmetro force_remove_conditions, eliminar um destinatário cujos campos alimentam condições noutros campos exigiria que resolvesse manualmente cada referência de condição primeiro.

Resumo técnico

Novos esquemas: ConditionSet, ConditionGroup, Condition

Atualização a partir de v1.9.0

Sem alterações de rutura estrutural. Sem remoções de campos. Sem alterações de comportamento. Os novos campos têm o valor predefinido de null ou false, pelo que as integrações existentes exigem zero modificações. Se vem de uma versão anterior, o mesmo aplica-se a cada lançamento desde a v1.0.0. Verifique o registo de alterações completo da API para ver o histórico completo de versões.

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

Começar

Novo no Firma.dev? Modelo de pagamento à medida que consome com preço de $0.049 por envelope, sem contratos ou consumos mínimos. Comece a utilizar o Firma.dev gratuitamente, sem necessidade de cartão de crédito.

Obter chave API

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