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

API Firma.dev v1.10.0 está ativo. Esta é a versão mais rica em funcionalidades até à data, entregando cinco funcionalidades adicionais sem alterações disruptivas. Se estiver na v1.9.0, a sua integração existente funciona sem modificações. Tudo aqui é nova capacidade, sem trabalho de migração.

Aqui está o que está dentro da caixa.

O que há na v1.10.0

As cinco funcionalidades são aditivas. Novos campos têm valor por defeito null ou false. Sem remoções de esquema, sem alterações de comportamento.

Lógica de campo condicional

Esta é a funcionalidade principal. Os campos agora podem ter required_conditions e visibility_conditions dinâmicas que avaliam com base em outros valores de campo no momento da assinatura. Em vez de construir lógica de formulário condicional na sua própria UI, define as regras uma vez na API e a Firma.dev trata da avaliação tanto no cliente quanto no lado do servidor.

A estrutura é compositá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.

Aqui está um exemplo prático. Suponha que tem um contrato de trabalho onde um campo de nome do cônjuge deve aparecer apenas quando o signatário marca a caixa "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 não está assinalada, o campo do nome do cônjuge permanece oculto e ignora a validação por completo. Quando está assinalado, aparece e pode ser definido como obrigatório através de uma regra required_conditions separada usando a mesma estrutura.

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 dependente onde campos adicionais de assinatura surgem com base num valor monetário ou nível de risco

• Formulários progressivos que se adaptam conforme o signatário preenche informações, mantendo a visão inicial limpa

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

Suporte a documentos DOCX

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

Isto aplica-se à criação de modelos, substituição de documentos de modelo, 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 PDF existentes permanecem completamente inalteradas. Se já estiver a carregar PDFs, nada muda. Isto apenas remove a etapa de conversão para equipas que criam documentos no Word.

Ponto final de rastreamento de auditoria

Um novo endpoint GET /signing-requests/{id}/audit retorna o registo completo de eventos cronológicos 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, baixado) numa única linha do tempo.

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

Este endpoint cobre o pedido de conformidade mais comum: produzir um pacote de evidências que mostre exatamente quem fez o quê, quando e de onde. Se necessita para registos de auditoria internos, relatórios regulatórios ou feeds de atividades voltados para o cliente, os dados estão todos numa única chamada.

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

Controlo de 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 configuração show_signature_frame permite controlar isto em três níveis com uma cadeia de herança limpa:

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

2. Espaço de trabalho sobrepõe Empresa (null herda)

3. Pedido de Assinatura sobrepõe 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 uso principal aqui é marca branca. Se está a incorporar a Firma.dev no seu próprio produto e deseja 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-a. Inversamente, indústrias regulamentadas que requerem identificadores de assinatura visíveis podem mantê-la explicitamente ativada.

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

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

• false (padrão): O pedido é rejeitado com um erro listando os campos dependentes

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

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

Sumário técnico

Novos esquemas: ConditionSet, ConditionGroup, Condition

Atualização da v1.9.0

Sem alterações disruptivas. Sem remoções de campo. Sem alterações de comportamento. Novos campos têm valor por defeito null ou false, pelo que as integrações existentes requerem zero modificação. Se vier de uma versão anterior, o mesmo se aplica a todas as versões desde a v1.0.0. Verifique o changelog completo da API para o histórico completo da versão.

Para detalhes sobre a v1.9.0 (verificação OTP, substituição de documento de modelo), veja a secção de changelog da v1.9.0.

Começar

Novo na Firma.dev? Pague conforme o uso preços a $0.029 por envelope, sem contratos ou mínimos. Comece com a Firma.dev gratuitamente, sem necessidade de cartão de crédito.

Obter chave API agora

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