Guias
Campos Condicionais: Crie Fluxos de Trabalho de Assinatura Inteligentes e Ramificados Através da API
A maioria dos documentos de assinatura não é estática. Um campo de nome do cônjuge só deve aparecer quando alguém seleciona "Casado." Uma secção adicional de divulgação deve tornar-se obrigatória quando uma transação excede um determinado montante em dólares. Um bloco de morada de envio só é relevante quando o signatário assinala "Enviar para morada diferente."
Sem campos condicionais, estás a construir toda essa lógica na tua própria camada de UI. Estás 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 de forma nativa. Defines as regras no esquema dos teus campos, e a API trata da visibilidade, do estado obrigatório e da imposição do lado do servidor no momento do envio. Não é necessária lógica de UI personalizada.
Dois tipos de condições
Cada objeto de campo na API da Firma.dev aceita agora duas novas propriedades anuláveis: required_conditions e visibility_conditions.
required_conditions substitui a sinalização estática required de um campo. Quando defines required_conditions, o campo torna-se obrigatório apenas quando as condições avaliam para true com base nos valores de outros campos no momento do envio. Se as condições avaliarem para false, o campo é opcional, independentemente do que a sinalização required indique.
visibility_conditions controla se o signatário vê o campo de todo. Quando definido, o campo permanece oculto a menos que as condições avaliem para true. Os campos ocultos são ignorados por completo durante a validação, por isso não terás erros em campos que o signatário nunca viu.
Ambas as propriedades são anuláveis. Quando deixadas como null (o valor predefinido), o campo comporta-se exatamente como antes: a sinalizaçã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 das condições
As condições usam uma estrutura aninhada em três níveis: ConditionSet, ConditionGroup e Condition. Esta é a parte que vale a pena compreender com cuidado, porque é o que te dá lógica booleana composável sem árvores profundamente aninhadas.
ConditionSet é o contentor de nível superior. Tem duas propriedades: um operador logic (ou 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 têm de avaliar para true. Se logic for or, basta que qualquer grupo individual avalie para true.
ConditionGroup contém uma matriz de conditions (objetos Condition individuais). Eis o detalhe crucial: as conditions dentro de um grupo são combinadas usando a lógica oposta à do ConditionSet pai. Se o ConditionSet usar and, as conditions dentro de cada grupo são combinadas com or. Se o ConditionSet usar or, as conditions dentro de cada grupo usam and.
Este padrão de lógica oposta é o que torna o esquema expressivo sem exigir uma aninhagem profunda. Permite-te construir afirmações como "(amount > 50000 OU tipo de cliente = Enterprise) E região não está vazia" com apenas dois grupos dentro de um ConditionSet and. O primeiro grupo teria duas condições (amount e tipo de cliente, combinadas com or porque o pai é and), e o segundo grupo teria uma condição para a verificação da região.
Condition é uma única avaliação. Faz referência a um field_id (o UUID de outro campo no documento), a um operator e a um value opcional para comparação.
Referência de operadores
A API da 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 seguimento quando um signatário começa a preencher uma secção. is_empty é o inverso e funciona bem para exigir um campo de recurso quando um campo principal é deixado em branco.
equals e not_equals fazem correspondência exata de valores. Mostra campos do cônjuge quando o estado civil é "Casado", ou oculta uma secção quando o país não é "US."
contains e not_contains verificam substrings. Podes mostrar campos relacionados com conformidade quando um campo de descrição contém "regulado," ou saltar 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. São os operadores a que recorrerias ao construir lógica baseada em limites, como exigir aprovação de um 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 apresentam 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 usando o operador is_filled:
O field_id referencia o UUID do campo que estás a avaliar. Neste caso, sempre que esse campo referenciado tiver qualquer valor, o campo atual torna-se obrigatório. Quando está vazio, o campo volta a ser opcional.
Podes desenvolver este padrão em várias direções. Para visibilidade condicional, usarias a mesma estrutura ConditionSet em visibility_conditions em vez de required_conditions. Um campo de texto "Nome do cônjuge" que só aparece quando a caixa de verificação "Casado" está selecionada usaria visibility_conditions com uma única condição is_filled a apontar para o UUID do campo da caixa de verificação.
Para lógica com múltiplas condições, acrescentas mais grupos ou mais condições dentro dos grupos. Se precisares de um campo de certificação de conformidade que seja obrigatório apenas quando o montante da transação for superior a 10 000 E o país for "US", criarias um ConditionSet com and lógico 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 usa a regra da lógica oposta. Imagina que queres mostrar uma secção "Termos Especiais" quando (amount > 50 000 OU tipo de cliente = "Enterprise") E a região não está vazia. Definias a propriedade logic do ConditionSet como and com dois grupos. O primeiro grupo contém duas condições (amount e tipo de cliente), que são automaticamente combinadas com or porque o pai usa and. O segundo grupo contém a condição única da região. O resultado é uma estrutura limpa e legível que, de outra forma, exigiria árvores booleanas aninhadas.
Aplicação do 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 manipulação do lado do cliente.
Se um campo for condicionalmente obrigatório e a condição avaliar para true no momento do envio, a API devolve um erro de validação quando esse campo está vazio. Se as visibility_conditions de um campo avaliarem para false, o campo fica oculto e é ignorado por completo durante a validação. Sem casos extremos, sem condições de corrida entre a tua UI e o backend.
Para fluxos de trabalho de conformidade, isto importa. As condições que defines na API são as condições que são aplicadas, ponto final. A tua UI do lado do cliente pode renderizar em tempo real os estados de visibilidade e obrigatoriedade para proporcionar uma boa experiência ao signatário, 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 interface do editor de modelos, a interface 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 ficam totalmente acessíveis via API. Não existe diferença funcional entre as ferramentas visuais e a interface programática.
Como começar
Os campos condicionais foram lançados como parte da API v1.10.0 da Firma.dev. São totalmente aditivos, sem alterações que quebrem compatibilidade. Os campos sem condições continuam a funcionar exatamente como antes, e as integrações existentes não requerem quaisquer modificações.
Podes começar a usar required_conditions e visibility_conditions em qualquer objeto de campo hoje. Consulta o registo de alterações 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 por utilizador e sem compromissos iniciais. Se estás a criar fluxos de assinatura que precisam de se adaptar com base na entrada do signatário, os campos condicionais permitem-te mover essa lógica para o sítio onde ela pertence: para a API, aplicada em cada envio.
Começa a usar a 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.
