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

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

Eis o que há de novo.

O que há de novo na v1.10.0

Todas as cinco funcionalidades são adicionais. Os novos campos assumem por predefinição null ou false. Sem remoções de esquema, sem 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 criar lógica condicional de formulários na sua própria interface, define as regras uma vez na API e o Firma.dev trata da avaliação tanto no cliente como no servidor.

A estrutura é combiná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 como os grupos se relacionam entre si, 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.

Eis um exemplo prático. Suponha que tem um contrato de trabalho onde o campo do nome do cônjuge só deve aparecer quando o signatário seleciona a 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á desselecionada, o campo do nome do cônjuge permanece oculto e ignora totalmente a validação. Quando selecionada, este aparece e pode ser definido como obrigatório através de uma regra de required_conditions separada que utiliza a mesma estrutura.

Alguns casos de utilização 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 onde campos adicionais de validação surgem com base num valor monetário ou nível de risco

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

O detalhe crucial para integrações sensíveis a 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 de obrigatoriedade através de manipulação no cliente. Se um campo deve ser obrigatório com base no valor de outro campo, o Firma.dev valida isso no servidor antes de aceitar o documento assinado.

Suporte a documentos DOCX

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

Isto aplica-se à criação de modelos, substituição de documentos em modelos, 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 de PDF existentes não são de todo afetadas. Se já carrega PDFs, nada muda. Isto apenas elimina a etapa de conversão para equipas que criam documentos no Word.

Endpoint de registo 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 ações de administrador (criado, editado, enviado, cancelado) como ações do signatário (visualizado, assinado, recusado, transferido) numa única linha cronológica.

Cada evento inclui uma 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 responde ao pedido de conformidade mais comum: gerar um pacote de evidências que mostre com exatidão quem fez o quê, quando e a partir de onde. Quer necessite dele para registos de auditoria interna, relatórios regulamentares ou feeds de atividade para clientes, os dados estão todos numa única chamada.

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

Controlo da moldura de assinatura

Por predefinição, os PDFs concluídos incluem uma moldura visual à volta de cada assinatura com um ID de Assinatura. A nova definição show_signature_frame permite controlar isto a três níveis com uma cadeia de herança clara:

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

2. O Espaço de trabalho sobrepõe-se à Empresa (null herda)

3. O Pedido de Assinatura sobrepõe-se ao 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 utilização aqui é o white-labeling. Se estiver a integrar 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 visíveis de assinatura podem mantê-lo explicitamente ativado.

Forçar remoção de condições na eliminação de utilizadores

Esta melhoria foca-se na ergonomia para programadores. Quando se elimina um destinatário cujos campos são referenciados nas condições de outros campos (da lógica condicional acima referida), a API anteriormente não tinha como gerir 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 de condição e prossegue com a eliminação

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

Resumo técnico

Novos esquemas: ConditionSet, ConditionGroup, Condition

Atualizar a partir da v1.9.0

Sem alterações que quebrem a compatibilidade. Sem remoções de campos. Sem alterações de comportamento. Os novos campos assumem por predefinição null ou false, pelo que as integrações existentes não exigem qualquer modificação. Se estiver a migrar a partir de uma versão anterior, o mesmo aplica-se a todas as versões desde a v1.0.0. Consulte o registo de alterações completo da API para ver o histórico de versões na íntegra.

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

Começar

Novo no Firma.dev? Modelo de pagamento à medida que utiliza a 0,049 € por envelope, sem contratos nem 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 completa da API, consulte a documentação do Firma.dev.