Guias
Campos Condicionais: Crie Fluxos de Trabalho de Assinatura Inteligentes e Ramificados Através da API
A maioria dos documentos a assinar não são estáticos. Um campo para o nome do cônjuge apenas deve aparecer quando alguém seleciona "Casado". Uma secção de divulgação adicional deve tornar-se obrigatória quando uma transação excede um determinado montante em dólares. Um bloco de endereço de envio apenas é relevante quando o signatário assinala "Enviar para um endereço diferente".
Sem campos condicionais, está a construir toda essa lógica na sua própria camada de UI. Está a gerir botões de visibilidade, regras de validação e casos excecionais no lado do cliente, esperando que nada seja contornado. Funciona, até deixar de funcionar.
A API do Firma.dev agora suporta campos condicionais de forma nativa. Define as regras no esquema de campos e a API trata da visibilidade, do estado de obrigatoriedade e da aplicação no lado do servidor aquando do envio. Não é necessária lógica de UI personalizada.
Dois tipos de condições
Cada objeto de campo na API do Firma.dev aceita agora duas novas propriedades anuláveis: required_conditions e visibility_conditions.
required_conditions sobrepõe-se à marcação estática required de um 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 campos no momento do envio. Se as condições forem avaliadas como falsas, o campo é opcional, independentemente do que diz a marcação required.
visibility_conditions controla se o signatário chega sequer a ver o campo. Quando definido, o campo permanece oculto, a menos que as condições sejam avaliadas como verdadeiras. Os campos ocultos são totalmente ignorados durante a validação, pelo que não receberá erros em campos que o signatário nunca viu.
Ambas as propriedades são anuláveis. Quando deixadas como null (o padrão), o campo comporta-se exatamente como antes: a marcação estática required determina se é obrigatório e o campo está sempre visível. As integrações existentes não precisam de quaisquer alterações.
O esquema de condições
As condições utilizam uma estrutura aninhada de três níveis: ConditionSet, ConditionGroup e Condition. Esta é a parte que vale a pena compreender com atenção, pois é o que lhe confere uma lógica booleana combinável sem árvores profundamente aninhadas.
ConditionSet é o contentor de nível superior. Tem duas propriedades: um operador logic (seja and ou or) e uma matriz de groups (objetos ConditionGroup). O operador lógico determina como os grupos se combinam. Se logic for and, todos os grupos devem ser avaliados como verdadeiros. Se logic for or, basta que um único grupo seja avaliado como verdadeiro.
ConditionGroup contém uma matriz de conditions (objetos Condition individuais). Eis o detalhe fundamental: as condições dentro de um grupo são combinadas utilizando a lógica oposta à do ConditionSet pai. Se o ConditionSet utilizar and, as condições dentro de cada grupo são combinadas com or. Se o ConditionSet utilizar or, as condições dentro de cada grupo utilizam and.
Este padrão de lógica oposta é o que torna o esquema expressivo sem exigir um aninhamento profundo. Permite-lhe construir instruções como "(montante > 50000 OU tipo de cliente é igual a Enterprise) E região não está vazia" com apenas dois grupos dentro de um ConditionSet and. O primeiro grupo conteria duas condições (montante e tipo de cliente, combinados com or porque o pai é and) e o segundo grupo conteria uma condição para a verificação da região.
Condition é uma avaliação única. Refere-se a um field_id (o UUID de outro campo no documento), um operator e um value opcional para comparação.
Referência do operador
O Firma.dev suporta 10 operadores de comparação em campos condicionais:
is_filled verifica se um campo tem algum valor. Útil para mostrar campos de acompanhamento quando um signatário começa a preencher uma secção. is_empty é o inverso e funciona bem para exigir um campo alternativo quando um campo principal é deixado em branco.
equals e not_equals fazem a correspondência exata de valores. Mostre campos de cônjuge quando o estado civil for igual a "Casado" ou oculte uma secção quando o país não for igual a "US".
contains e not_contains verificam sub-strings. Pode mostrar campos relacionados com conformidade quando um campo de descrição contém "regulado" ou ignorar uma secçã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 tratam de comparações numéricas. Estes são os operadores a que recorreria ao construir lógica baseada em limites, como exigir a aprovação do gestor quando um montante excede 10.000 ou aplicar termos simplificados quando o valor de um contrato fica abaixo de um determinado número.
Como as condições se parecem na prática
O registo de alterações da API inclui um exemplo do padrão condicional mais simples: tornar um campo obrigatório apenas quando outro campo tiver sido preenchido. A propriedade required_conditions recebe um ConditionSet com lógica and, um único grupo e uma única condição utilizando o operador is_filled:
O field_id refere-se ao UUID do campo que está a avaliar. Neste caso, sempre que esse campo referenciado tiver algum valor, o campo atual passa a ser obrigatório. Quando estiver vazio, o campo volta a ser opcional.
Pode desenvolver este padrão em várias direções. Para visibilidade condicional, utilizaria a mesma estrutura de ConditionSet sob visibility_conditions em vez de required_conditions. Um campo de texto "Nome do Cônjuge" que apenas aparece quando uma caixa de seleção "Casado" está marcada utilizaria visibility_conditions com uma única condição is_filled a apontar para o UUID do campo da caixa de seleção.
Para lógica de várias 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 montante da transação for superior a 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 montante com greater_than, o segundo verifica o país com equals.
O padrão mais expressivo utiliza a regra da lógica oposta. Digamos que quer mostrar uma secção de "Termos Especiais" quando (montante > 50.000 OU tipo de cliente é igual a "Enterprise") E região não está vazia. Definiria a logic do ConditionSet para and com dois grupos. O primeiro grupo contém duas condições (montante e tipo de cliente), que são automaticamente combinadas com or porque o pai utiliza and. O segundo grupo contém a condição única de 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 signatário submete. Isto não é opcional e não é algo que possa ser contornado por adulterações 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 devolve um erro de validação quando esse campo estiver vazio. Se as visibility_conditions de um campo forem avaliadas como falsas, o campo é ocultado e totalmente ignorado durante a validação. Sem casos excecionais, sem condições de corrida entre a sua UI e o backend.
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 no lado do cliente pode renderizar a visibilidade e os estados de obrigatoriedade em tempo real para uma boa experiência do signatário, mas a fonte da verdade reside no lado do servidor.
Onde as condições funcionam
Os campos condicionais estão disponíveis em todas as superfícies no Firma.dev: a UI do editor de modelos, a UI do editor de pedidos de assinatura, o editor de modelos incorporado, o editor de pedidos de assinatura incorporado e a API REST completa para modelos e 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 são totalmente acessíveis através da API. Não há lacunas de funcionalidades entre as ferramentas visuais e a interface programática.
Como começar
Os campos condicionais foram disponibilizados como parte da API do Firma.dev v1.10.0. São totalmente cumulativos, sem alterações que quebrem a compatibilidade. Os campos sem condições continuam a funcionar exatamente como antes e as integrações existentes exigem zero modificações.
Pode começar a utilizar required_conditions e visibility_conditions em qualquer objeto de campo hoje mesmo. Consulte o registo de alterações da API para obter a referência completa do esquema e a documentação da API para obter a especificação completa dos campos.
O Firma.dev cobra 0,049 € por envelope sem mínimos mensais, sem taxas por utilizador e sem compromissos iniciais. Se está a construir fluxos de trabalho de assinatura que se precisam de adaptar com base nos dados introduzidos pelo signatário, os campos condicionais permitem-lhe mover essa lógica para onde ela pertence: para a API, aplicada em cada submissão.
Comece a utilizar o Firma.dev gratuitamente, sem necessidade de cartão de crédito.
Artigos relacionados
A nossa plataforma foi projetada para capacitar empresas de todos os tamanhos a trabalhar de forma mais inteligente e alcançar seus objetivos com confiança.
