Adicionar assinaturas eletrônicas a um aplicativo pode parecer uma integração simples. O aplicativo envia um documento, o destinatário o assina, um webhook informa a conclusão e o arquivo finalizado é armazenado.
A parte difícil geralmente chega após o lançamento. Usuários reais abandonam solicitações, links expiram, documentos exigem correções, vários destinatários assinam pedidos diferentes e fluxos de trabalho regulamentados introduzem verificações de identidade adicionais. Cada evento pode interagir com as regras de cobrança do provedor.
O preço deve, portanto, ser tratado como uma restrição de engenharia. Antes de selecionar um plano, os desenvolvedores precisam entender quais eventos de aplicação criam transações faturáveis e como esses eventos se comportam em escala de produção.
Envelopes não são documentos ou assinaturas
Muitas plataformas de assinatura eletrônica medem o uso da API usando um contêiner de transação comumente chamado de envelope. Um envelope pode conter vários documentos e pode ser enviado a um ou mais destinatários.
Esta unidade nem sempre corresponde à forma como um aplicativo descreve sua atividade. Uma equipe de produto pode contar os documentos carregados, enquanto o fornecedor conta os envelopes. Outra equipe pode medir as assinaturas concluídas mesmo que as transações incompletas ainda consumam a cota.
Por exemplo, enviar um contrato com várias páginas para um destinatário pode criar um envelope. Adicionar páginas de suporte à mesma transação pode não alterar essa contagem. O envio de um anexo separadamente, entretanto, pode criar outra transação faturável.
Documentos corrigidos, links expirados, cancelamentos e reenvios introduzem mais incertezas. Seu tratamento difere entre serviços e contratos, portanto, os desenvolvedores devem documentar as respostas a diversas perguntas:
-
Que ação cria um novo envelope?
-
Vários documentos podem ser incluídos em uma transação?
-
O reenvio de uma solicitação expirada consome mais cota?
-
As solicitações canceladas ou abandonadas são faturáveis?
-
As transações de sandbox contam para o subsídio?
Estas regras pertencem à documentação técnica do projeto. Eles afetam o comportamento da aplicação, as estimativas de custos e os procedimentos de suporte.
Assentos influenciam a arquitetura do aplicativo
Alguns planos atribuem cotas de transação a usuários licenciados ou identidades de remetentes. Isto cria uma decisão arquitetônica: cada solicitação deve ser enviada por meio de uma conta de integração ou cada cliente, departamento ou funcionário precisa de um remetente separado?
Um protótipo pode encaminhar tudo através de uma conta porque é mais fácil de configurar. Essa abordagem pode se tornar inadequada quando o aplicativo exigir marcas, permissões, trilhas de auditoria ou propriedade de dados separadas.
Antes de implementar o modelo de conta, confirme se os remetentes somente API exigem licenças pagas. Verifique também se o provedor permite que uma conta central envie documentos para vários clientes.
A resposta pode alterar significativamente a integração. Uma conta de serviço é simples de gerenciar, mas pode fornecer separação insuficiente. Contas de remetentes individuais melhoram a atribuição, mas podem aumentar o trabalho de provisionamento e os custos recorrentes.
Calcule o custo efetivo de uma transação concluída
Os principais preços mensais não fornecem uma comparação justa. Os planos podem incluir diferentes números de assentos, transações e recursos. Eles também podem aplicar taxas diferentes por excedentes e verificações de identidade.
Uma métrica melhor é o custo efetivo por envelope concluído:
Custo efetivo=taxa base + assentos + excedentes + verificações de identidade envelopes preenchidos\text{Custo efetivo} = \frac{\text{taxa base + assentos + excedentes + verificações de identidade}} {\text{envelopes preenchidos}}
A distinção entre envelopes enviados e preenchidos é importante. Uma transação que expira ou é abandonada ainda pode consumir a cota mesmo que a aplicação não receba nenhum documento concluído.
Os desenvolvedores podem modelar essas variáveis com uma pequena função JavaScript:
function estimateMonthlyCost({
baseFee,
seats,
seatPrice,
envelopesSent,
envelopesCompleted,
includedEnvelopes,
overagePrice,
identityChecks,
identityCheckPrice
}) {
const seatCost = seats * seatPrice;
const billableOverages = Math.max(
0,
envelopesSent - includedEnvelopes
);
const overageCost =
billableOverages * overagePrice;
const identityCost =
identityChecks * identityCheckPrice;
const total =
baseFee + seatCost + overageCost + identityCost;
return {
total,
completionRate: envelopesSent
? envelopesCompleted / envelopesSent
: 0,
effectiveCostPerCompletion: envelopesCompleted
? total / envelopesCompleted
: 0
};
}
const estimate = estimateMonthlyCost({
baseFee: 49,
seats: 8,
seatPrice: 15,
envelopesSent: 900,
envelopesCompleted: 810,
includedEnvelopes: 500,
overagePrice: 0.65,
identityChecks: 120,
identityCheckPrice: 1.25
});
console.log(estimate);
Os valores de exemplo são ilustrativos. Substitua-as pelas taxas e regras de cobrança que estão sendo avaliadas.
Execute o cálculo em relação ao uso normal, um mês de pico e um cenário com muitas falhas. O cenário final deve incluir links expirados, novas tentativas e solicitações abandonadas. Isto revela como a taxa de conclusão afeta o custo real de cada transação bem-sucedida.
Impedir que novas tentativas criem envelopes duplicados
Falhas na rede tornam o faturamento mais complicado. Imagine que o provedor aceita uma solicitação, mas a conexão é fechada antes que a aplicação receba a resposta. Se o aplicativo repetir a solicitação imediatamente, poderá criar um segundo envelope.
Use uma chave de idempotência quando a API oferecer suporte a uma. Uma chave de idempotência permite que o servidor reconheça tentativas repetidas como a mesma operação.
A aplicação também deve gerar e armazenar seu próprio identificador de transação antes de fazer a solicitação externa. Se a resposta for incerta, reconcilie a transação por meio do endpoint de status do provedor ou de eventos de webhook, em vez de criar outra cegamente.
Falhas temporárias devem usar espera exponencial:
const wait = milliseconds =>
new Promise(resolve =>
setTimeout(resolve, milliseconds)
);
async function retry(operation, attempts = 4) {
let lastError;
for (let attempt = 0; attempt < attempts; attempt++) {
try {
return await operation();
} catch (error) {
lastError = error;
if (attempt === attempts - 1) {
break;
}
await wait(500 * 2 ** attempt);
}
}
throw lastError;
}
Não tente novamente todos os erros. Credenciais inválidas, arquivos não suportados e falhas de validação exigem correção. As novas tentativas automáticas devem ser limitadas a problemas temporários de rede, limites de taxa e erros de servidor adequados.
A verificação de identidade pode ser cobrada separadamente
Um pedido de assinatura e uma verificação de identidade não são necessariamente o mesmo produto. Os fluxos de trabalho básicos podem depender de um link de e-mail ou de um código único. As transações regulamentadas podem exigir verificações de documentos, identificação eletrónica ou outros métodos de verificação mais rigorosos.
Estas operações poderão ser cobradas separadamente do envelope. Se a verificação falhar e o usuário tentar novamente, outra taxa poderá ser aplicada.
Para fluxos de trabalho europeus, os desenvolvedores devem revisar o documento oficial Quadro regulatório eIDAS. As equipes jurídicas e de conformidade devem determinar o nível de assinatura exigido; os desenvolvedores não devem selecioná-lo apenas nas descrições dos recursos da API.
Rastreie as verificações de identidade como uma métrica separada:
-
Verificações iniciadas e concluídas.
-
Tentativas falhadas.
-
Tentativas repetidas para a mesma transação.
-
Custo por verificação bem-sucedida.
-
Fluxos de trabalho que exigem verificação mais robusta.
Em algumas aplicações, a verificação de identidade pode tornar-se uma despesa maior do que a própria transação de assinatura.
Teste todo o fluxo de trabalho do documento
O teste deve abranger mais do que a solicitação que cria um envelope. Deve incluir seleção de arquivos, validação, tratamento de destinatários, processamento de webhook, arquivamento e verificações de integridade.
Se os usuários selecionarem PDFs no navegador, o guia do SitePoint para Tipos de entrada HTML explica as entradas do arquivo e o accept atributo. Lembre-se disso accept melhora o seletor de arquivos, mas não é um controle de segurança completo. Valide o tipo e tamanho do arquivo no aplicativo.
Se os usuários copiarem links de assinatura ou identificadores de auditoria, o SitePoint Guia da API da área de transferência abrange permissões do navegador e padrões de implementação seguros.
Após o retorno de um arquivo assinado, verifique sua integridade antes de arquivá-lo ou processá-lo. Os desenvolvedores podem usar uma ferramenta baseada em navegador para verifique se um PDF assinado foi modificado sem criar uma conta ou enviar o documento. Para um fluxo de trabalho integrado, use o processo de validação documentado do fornecedor e preserve o arquivo original assinado e as evidências de auditoria.
A verificação de integridade não é o mesmo que validar a identidade do signatário. Um hash criptográfico pode mostrar se um arquivo foi alterado, enquanto a validação de assinatura também examina informações de certificado e assinatura.
Monitore o uso da produção
Uma estimativa em planilha não pode prever todos os padrões de produção. Registre as métricas operacionais assim que a integração for lançada.
As medidas úteis incluem:
-
Envelopes criados e concluídos.
-
Solicitações expiradas e abandonadas.
-
Novas tentativas e eventos de prevenção de duplicação.
-
Verificações de identidade tentadas e concluídas.
-
Uso por cliente ou fluxo de trabalho.
-
Custo efetivo por envelope preenchido.
Crie alertas para aumentos inesperados na criação de transações, novas tentativas ou falhas nas verificações de identidade. Um aumento repentino de custos pode indicar uma mudança no produto, um bug de integração ou abuso automatizado.
Evite registrar conteúdos de documentos, assinar links ou informações pessoais desnecessárias. Use identificadores internos e contagens agregadas sempre que possível.
Perguntas a serem respondidas antes de se comprometer
Obtenha respostas por escrito sobre as regras operacionais e de faturamento que afetam a implementação:
-
O que cria uma transação faturável?
-
Envelopes incompletos ou cancelados são cobrados?
-
As licenças não utilizadas são acumuladas?
-
As transações sandbox são gratuitas?
-
As chamadas de API estão sujeitas a limites separados?
-
As identidades de remetente adicionais exigem licenças?
-
Por quanto tempo os documentos e registros de auditoria são retidos?
-
Todos os arquivos e evidências podem ser exportados quando o contrato terminar?
As respostas podem estar espalhadas por uma página de preços, documentação da API, termos de serviço e artigos de suporte. Revise todos eles antes que o aplicativo se torne dependente de uma estrutura de conta específica.
Considerações finais
O preço da assinatura eletrônica é uma preocupação de engenharia porque as regras de cobrança influenciam a arquitetura da conta, novas tentativas, observabilidade, verificação de identidade e armazenamento de documentos.
Modele os custos usando os eventos que o aplicativo gera, em vez do preço principal do provedor. Rastreie os envelopes enviados e concluídos, separe os custos de verificação de identidade, evite solicitações duplicadas e monitore o comportamento real da produção.
Um modelo cuidadoso não eliminará todas as cobranças inesperadas. No entanto, tornará essas acusações visíveis antes que se tornem problemas arquitectónicos dispendiosos.
