Campos Condicionais: Crie Fluxos de Trabalho de Assinatura Inteligentes e Ramificados Através da API

A maioria dos documentos para assinatura não são estáticos. Um campo de nome de cônjuge deve aparecer apenas quando alguém seleciona "Casado." Uma seção adicional de divulgação deve se tornar obrigatória quando uma transação excede um determinado valor em dólares. Um bloco de endereço de envio só importa quando o assinante marca "Enviar para endereço diferente."

Sem campos condicionais, está a construir toda essa lógica na sua própria camada de UI. Está a gerir alternâncias de visibilidade, regras de validação e casos extremos no lado do cliente, e a esperar que nada seja contornado. Funciona até deixar de funcionar.

A API da Firma.dev agora suporta campos condicionais nativamente. Define as regras no seu esquema de campo, e a API lida com a visibilidade, o estado de obrigatório e a aplicação no lado do servidor na submissão. Não é necessária nenhuma lógica de UI personalizada.

Dois tipos de condições

Cada objeto de campo na API da Firma.dev agora aceita duas novas propriedades anuláveis: required_conditions e visibility_conditions.

required_conditions sobrepõe a flag required estática num campo. Quando define required_conditions, o campo torna-se obrigatório apenas quando as condições são avaliadas como verdadeiras com base noutros valores de campo no momento da submissão. Se as condições forem avaliadas como falsas, o campo é opcional, independentemente do que a flag required diz.

visibility_conditions controla se o assinante vê o campo de todo. Quando configurado, o campo permanece oculto a menos que as condições sejam avaliadas como verdadeiras. Campos ocultos são totalmente ignorados durante a validação, para que não receba erros em campos que o assinante nunca viu.

Ambas as propriedades são anuláveis. Quando deixadas como null (o padrão), o campo se comporta exatamente como antes: a flag required estática determina se é necessário, e o campo está sempre visível. As integrações existentes não precisam de alterações.

O esquema de condições

As condições usam uma estrutura aninhada de três níveis: ConditionSet, ConditionGroup e Condition. Esta é a parte que vale a pena entender bem, porque é o que lhe dá lógica booleana componível sem árvores profundamente aninhadas.

ConditionSet é o contêiner de nível superior. Tem duas propriedades: um operador logic (ou and ou or) e um array de groups (objetos ConditionGroup). O operador de lógica determina como os grupos se combinam. Se logic for and, todos os grupos devem ser avaliados como verdadeiros. Se logic for or, qualquer grupo individual avaliando como verdadeiro é suficiente.

ConditionGroup contém um array de conditions (objetos de avaliação individual). Aqui está o detalhe chave: as condições dentro de um grupo são combinadas usando a lógica oposta do ConditionSet pai. Se o ConditionSet usar and, as condições dentro de cada grupo são combinadas com or. Se o ConditionSet usar or, as condições dentro de cada grupo usam and.

Este padrão de lógica oposta é o que torna o esquema expressivo sem exigir aninhamentos profundos. Permite construir declarações como "(valor > 50.000 OU tipo de cliente igual a Enterprise) E região não está vazia" com apenas dois grupos dentro de um ConditionSet de and. O primeiro grupo conteria duas condições (valor e tipo de cliente, combinadas com or porque o pai é and), e o segundo grupo conteria uma condição para a verificação da região.

Condition é uma única avaliação. Refere-se a um field_id (o UUID de outro campo no documento), um operator, e um value opcional para comparação.

Referência de operadores

A Firma.dev suporta 10 operadores de comparação em campos condicionais:

is_filled verifica se um campo tem algum valor de todo. Útil para mostrar campos de seguimento quando um assinante começa a preencher uma seção. is_empty é o inverso, e funciona bem para exigir um campo de fallback quando um campo principal é deixado em branco.

equals e not_equals fazem a correspondência de valores exatos. Mostrar campos de cônjuge quando o estado civil é igual a "Casado," ou esconder uma seção quando o país não for igual a "US."

contains e not_contains verificam substrings. Pode mostrar campos relacionados à conformidade quando um campo de descrição contém "regulado," ou pular uma seção quando as notas não mencionam uma palavra-chave específica.

greater_than, less_than, greater_than_or_equal, e less_than_or_equal lidam com comparações numéricas. Estes são os operadores que usaria ao construir lógica baseada em limites, como exigir aprovação do gerente quando um valor excede 10.000 ou aplicar termos simplificados quando um valor de contrato cai abaixo de um determinado número.

Como as condições são na prática

O changelog da API inclui um exemplo do padrão condicional mais simples: tornar um campo obrigatório apenas quando outro campo foi preenchido. A propriedade required_conditions leva um ConditionSet com lógica and, um único grupo, e uma única condição usando o operador is_filled:

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

O field_id referência o UUID do campo que está a avaliar. Neste caso, sempre que esse campo referenciado tiver qualquer valor, o campo atual torna-se obrigatório. Quando estiver vazio, o campo reverte para opcional.

Pode expandir este padrão em várias direções. Para visibilidade condicional, usaria a mesma estrutura ConditionSet sob visibility_conditions em vez de required_conditions. Um campo de texto "Nome do Cônjuge" que só aparece quando uma caixa de seleção "Casado" está marcada usaria visibility_conditions com uma única condição is_filled apontando para o UUID do campo de seleção.

Para lógica de múltiplas condições, adiciona mais grupos ou mais condições dentro dos grupos. Se precisar que um campo de certificação de conformidade seja obrigatório apenas quando o valor da transação for maior que 10.000 E o país for igual a "US," criaria um ConditionSet com lógica and contendo dois grupos, cada um com uma condição. O primeiro grupo verifica o valor com greater_than, o segundo verifica o país com equals.

O padrão mais expressivo usa a regra de lógica oposta. Digamos que deseja mostrar uma seção "Termos Especiais" quando (valor > 50.000 OU tipo de cliente igual a "Enterprise") E a região não estiver vazia. Configuraria a logic do ConditionSet para and com dois grupos. O primeiro grupo contém duas condições (valor e tipo de cliente), que são automaticamente combinadas com or porque o pai usa and. O segundo grupo contém uma única condição para a região. O resultado é uma estrutura limpa e legível que, de outra forma, exigiria árvores booleanas aninhadas.

Aplicação no lado do servidor

Todas as condições são avaliadas no lado do servidor quando o assinante envia. Isto não é opcional, e não é algo que pode ser contornado com manipulação no lado do cliente.

Se um campo for condicionalmente obrigatório e a condição for avaliada como verdadeira no momento da submissão, a API retorna um erro de validação quando esse campo está vazio. Se as visibility_conditions de um campo forem avaliadas como falsas, o campo é oculto e totalmente ignorado durante a validação. Sem casos extremos, sem condições de corrida entre a sua UI e o back-end.

Para fluxos de trabalho de conformidade, isto é importante. As condições que define na API são as condições que são aplicadas, ponto final. A sua UI do lado do cliente pode renderizar os estados de visibilidade e obrigatoriedade em tempo real para uma boa experiência do assinante, mas a fonte de verdade vive no lado do servidor.

Onde as condições funcionam

Os campos condicionais estão disponíveis em todas as superfícies da Firma.dev: a UI do editor de templates, a UI do editor de pedidos de assinatura, o editor de templates incorporado, o editor de pedidos de assinatura incorporado e a API REST completa tanto para templates quanto para pedidos de assinatura.

As condições definidas através da API aparecem e são avaliadas corretamente em todas as superfícies de UI, e as condições configuradas através dos editores estão totalmente acessíveis através da API. Não há lacuna de funcionalidades entre as ferramentas visuais e a interface programática.

Começando

Os campos condicionais foram lançados como parte da API v1.10.0 da Firma.dev. São totalmente aditivos sem mudanças disruptivas. Campos sem condições continuam a funcionar exatamente como antes, e as integrações existentes não requerem modificações.

Pode começar a usar required_conditions e visibility_conditions em qualquer objeto de campo hoje. Verifique o changelog da API para a referência completa do esquema, e a documentação da API para a especificação completa do campo.

A Firma.dev cobra €0,029 por envelope sem mínimos mensais, sem taxas de assento, e sem compromissos iniciais. Se está a construir fluxos de trabalho de assinatura que precisam se adaptar com base na entrada do assinante, campos condicionais permitem mover essa lógica para onde ela pertence: na API, aplicada em cada submissão.

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