API de Assinatura White-Label para Plataformas SaaS

Para uma plataforma SaaS, assinatura digital costuma ser uma das features mais pedidas — e uma das mais arriscadas de construir do zero. Operar certificados, referência temporal, trilha de auditoria, containers PAdES/CAdES e cadeias de confiança ICP-Brasil significa, na prática, virar uma autoridade certificadora dentro do seu próprio produto. Uma API de assinatura white-label resolve isso: você embute a experiência de assinar sob a sua marca, com isolamento por cliente, webhooks e billing próprio, sem nunca tocar na criptografia.

Este guia é para quem constrói SaaS — CTOs, tech leads e product engineers — e quer adicionar embedded signing ao produto como mais uma funcionalidade nativa, não como um redirecionamento para uma ferramenta de terceiros. Vamos cobrir embedded vs. checkout hospedado, branding white-label, arquitetura multi-tenant, isolamento por cliente, quota e billing, webhooks e os modelos de autenticação OAuth2 e mTLS.

Se você está avaliando o terreno, vale começar pela visão geral da API de assinatura digital da SignDocs e, se quiser ver o embed em ação no fluxo mais curto, pelo quickstart de 5 minutos. Aqui o foco é a decisão de arquitetura de quem vai oferecer assinatura como parte de um produto.

Por que um SaaS não deve construir assinatura do zero

Adicionar "assinar documento" como botão no seu produto parece simples, mas a tecnologia por trás de uma assinatura com validade jurídica é densa. Para fazer isso corretamente no Brasil, você precisaria operar e manter:

• Cadeia de confiança ICP-Brasil: integração com autoridades certificadoras, validação de cadeias A1 e A3, verificação de revogação (CRL/OCSP).
• HSMs e gestão de chaves: hardware security modules para guardar e operar chaves criptográficas com segurança.
• Referência temporal e trilha de auditoria: registrar o momento de cada etapa com carimbo de hora do servidor e consolidar tudo numa trilha append-only que sustente a prova.
• Containers e padrões: geração correta de PAdES (PDF), CAdES (qualquer arquivo) e PKCS#7/CMS no nível baseline (B-B), vinculando o hash SHA-256 do documento à cadeia de certificados.
• Pacote de evidências: trilha de auditoria, IPs, geolocalização, hashes e o arquivo .p7m que sustenta o documento em juízo.
• Compliance contínuo: LGPD, retenção, residência de dados e atualização frente a mudanças regulatórias.

Nada disso é o core do seu SaaS. Construir e manter essa pilha consome trimestres de engenharia e cria responsabilidade jurídica permanente. Uma API white-label entrega tudo isso como serviço, e você consome via REST. A regra de ouro: seu SaaS é dono da experiência e do relacionamento com o cliente; o provedor é dono da tecnologia de assinatura.

Embedded signing: assinar dentro do seu produto

O coração de uma integração white-label é o embedded signing: a experiência de assinatura é aberta de dentro da sua interface, sem que o usuário navegue para outro produto. Na prática, a API cria uma sessão de assinatura e devolve um clientSecret que o SDK oficial @signdocs-brasil/js usa para abrir o checkout de assinatura como popup a partir da sua tela, com callbacks de conclusão para a sua aplicação reagir na hora.

Na SignDocs, a forma mais direta de criar essa experiência é a Assinatura Expressa, exposta pelo endpoint POST /v1/signing-sessions. Uma única chamada cria a sessão e devolve o material necessário para o embed. O mesmo endpoint atende tanto o embedded quanto o checkout hospedado — você escolhe o modo de apresentação.

Para o embed, entregue o clientSecret ao seu frontend e abra o checkout com o SDK oficial — a comunicação com a sua página (conclusão, erro, fechamento) chega por callbacks, sem você implementar postMessage na mão:

Para o modo hospedado, o link final é a url combinada com o clientSecret como query (?cs=) — pronto para redirecionar ou enviar ao signatário.

Embedded vs. checkout hospedado

Há dois modos de apresentar a assinatura ao usuário final, e a escolha define a profundidade da experiência white-label:

A recomendação prática para SaaS é começar pelo checkout hospedado para validar o fluxo rápido e migrar para embedded quando a experiência for prioridade — sem trocar de endpoint. Detalhamos o modo redirecionado na página da Assinatura Expressa.

Branding white-label: a marca é sua

White-label real vai além de carregar um iframe. Para que o cliente final não perceba o provedor, a integração precisa cobrir três camadas de marca:

• Visual na tela de assinatura: o campo appearance da sessão aceita companyName, logoUrl, brandColor e cores de fundo, texto e botão — por sessão, ou seja, por tenant do seu SaaS.
• Comunicações: para controle total da marca, omita o owner na criação da sessão e entregue o link de assinatura você mesmo, pelos seus e-mails e dentro do seu produto. Se preferir delegar, informe o owner e a SignDocs envia o convite por e-mail em seu nome.
• Documento final: o PDF carimbado e a verificação pública preservam a referência técnica de validade (hash, carimbo de hora do servidor, emissor) — é o lastro de confiança que o seu SaaS herda e pode expor ao cliente.

Um detalhe operacional que vale para qualquer add-on de assinatura: quando o seu backend é quem dispara o convite, o e-mail automático do provedor só deve sair quando o remetente (owner) for diferente do signatário. Se você mesmo entrega o link dentro do seu SaaS, mantenha a entrega de e-mail desligada para evitar comunicações duplicadas com a marca errada.

Arquitetura multi-tenant: dois modelos

O coração da decisão de arquitetura de um SaaS é como separar os seus clientes (tenants) dentro da API de assinatura. Há dois modelos, e a escolha tem impacto direto em compliance, billing e isolamento.

Modelo 1 — Conta única com isolamento lógico

Seu SaaS usa uma credencial mestre (um único par de credenciais OAuth2) e separa os tenants por metadados. Cada transação carrega um tenant_id no campo metadata, e seu backend filtra, agrupa e fatura por esse identificador.

• Prós: integração mais simples, uma só credencial para gerenciar, onboarding instantâneo de novos tenants (sem provisionamento externo).
• Contras: isolamento é responsabilidade da sua aplicação; um bug no filtro de tenant_id pode vazar dados entre clientes. Auditoria e quota são agregadas.
• Indicado para: SaaS B2B2C onde o tenant é invisível ao usuário final e o volume por tenant é moderado.

Modelo 2 — Subcontas por cliente

Cada cliente do seu SaaS recebe uma conta própria na plataforma, com credenciais OAuth2 isoladas, quota e webhooks independentes. Seu SaaS atua como orquestrador, mantendo o mapeamento seu_tenant → conta_signdocs. O provisionamento de cada subconta é dimensionado junto ao time SignDocs — não há endpoint self-service de criação de contas —, o que torna esse modelo adequado a carteiras menores de clientes de maior porte.

• Prós: isolamento forte no nível da plataforma, faturamento e auditoria por cliente, branding e endpoints de webhook separados.
• Contras: exige fluxo de provisionamento, gestão de N credenciais e rotação de segredos por conta.
• Indicado para: SaaS cujos clientes têm requisitos de compliance, auditoria ou marca próprios — especialmente em verticais reguladas.

Quota, billing e medição por tenant

Como provedor white-label, a camada de cobrança é sua. Isso é uma vantagem: você define planos, margem e limites, e decide se repassa o custo, cobra por documento, por assinatura ou inclui no preço do seu produto. A API fornece os dados de consumo; a lógica de billing fica do seu lado.

O gatilho de medição mais confiável é o webhook de conclusão. Quando o evento TRANSACTION.COMPLETED chega, seu backend registra o uso vinculado ao tenant_id e atualiza o medidor do cliente. Como webhooks operam com semântica de entrega pelo menos uma vez, a contabilização precisa ser idempotente — usando o id do evento para não cobrar duas vezes pelo mesmo documento.

Para enforcement de limites, seu SaaS verifica a quota do tenant antes de criar a sessão de assinatura, bloqueando ou pedindo upgrade quando o plano estoura. Os fundamentos de idempotência, retry e tratamento de reentregas estão detalhados no nosso guia de webhooks e eventos da API de assinatura, que é leitura essencial antes de ligar a medição em produção.

Webhooks: o tecido conectivo do seu SaaS

Em uma plataforma SaaS, webhooks são o que mantém o seu produto sincronizado com o ciclo de vida da assinatura sem polling. Cada evento dispara reações: atualizar o status do contrato na sua UI, liberar a próxima etapa do onboarding do seu cliente, contabilizar uso, notificar o time.

• TRANSACTION.CREATED — registre o ID e inicie o timer de SLA do tenant.
• STEP.COMPLETED — atualize o progresso na tela do seu produto em tempo real, etapa a etapa.
• SIGNING_SESSION.COMPLETED / ENVELOPE.ALL_SIGNED — avance o fluxo; o segundo fecha assinaturas multi-signatário.
• TRANSACTION.COMPLETED — gatilho de billing e de liberação da feature dependente.
• TRANSACTION.EXPIRED / TRANSACTION.CANCELLED — limpe estado e notifique o tenant (antes da expiração, TRANSACTION.DEADLINE_APPROACHING permite lembrar o signatário).

Cada webhook chega via HTTPS POST com assinatura HMAC-SHA256 no header, e seu receptor deve validar a assinatura, conferir o timestamp contra replay e responder com 2xx rapidamente, processando o evento de forma assíncrona. No modelo de subcontas, configure um endpoint por conta ou roteie por um header de identificação; no modelo de conta única, roteie pelo tenant_id do payload.

Autenticação: OAuth2 e mTLS

O acesso à API se dá por OAuth2 no fluxo client-credentials: seu backend troca o par client_id/client_secret por um access token (bearer) de curta duração, usado nas chamadas seguintes. O token é um JWT assinado com ECDSA (ES256), com expiração em 15 minutos e chaves protegidas em KMS no lado do provedor.

O detalhamento de escopos, expiração e rotação está no guia de autenticação OAuth2 da API de assinatura. Para clientes enterprise e regulados — fintechs sob supervisão do BACEN, integrações Open Finance — há ainda mTLS (mutual TLS), em que tanto o seu backend quanto a API apresentam certificados, garantindo autenticação mútua no nível de transporte além do bearer token.

Perfis de assinatura e métodos de autenticação do signatário

Como a marca é sua, mas a validade jurídica é do provedor, vale entender o que está disponível para configurar por fluxo. O campo policy.profile define o perfil da assinatura por sessão — de CLICK_ONLY e CLICK_PLUS_OTP a BIOMETRIC_PLUS_OTP e DIGITAL_CERTIFICATE (certificado ICP-Brasil A1, o formato usado em integrações via API; para titulares de token A3, o aplicativo SignDocs oferece o assinador desktop). Assim cada fluxo do seu SaaS escolhe o rigor proporcional ao risco. Para uma visão completa dos perfis, consulte a seção de métodos de autenticação em o que é uma API de assinatura digital.

Padrões, evidências e validade jurídica

Quando o seu SaaS opera em verticais sensíveis, os seus clientes vão perguntar pela base de validade. A boa notícia: você herda toda a conformidade do provedor sem operar nada disso. A assinatura gera containers PAdES (PDF) e CAdES (qualquer arquivo) sobre PKCS#7/CMS no nível baseline (assinatura + cadeia de certificados ICP-Brasil + carimbo de hora do servidor + trilha de auditoria append-only), mais o pacote de evidências em .p7m que vincula o hash SHA-256, a identidade e os dados de autenticação e serve de prova técnica e jurídica. Os padrões PAdES/CAdES definem ainda níveis com carimbo de tempo de uma ACT e LTV (B-T, B-LT, B-LTA), que não são gerados atualmente pela API. A base legal no Brasil é a MP 2.200-2/2001 (ICP-Brasil), com operação LGPD-first.

Cada documento pode ser conferido na verificação pública de assinatura, em verificador.signdocs.com.br — um diferencial de confiança que o seu SaaS pode expor sob a sua própria marca. Importante para marketing honesto: a SignDocs roda em múltiplas regiões AWS, então o posicionamento correto é "ICP-Brasil-nativo, produto e suporte em pt-BR e LGPD-first", e não "dados nunca saem do Brasil".

Verticais que combinam com white-label SaaS

O padrão de embutir assinatura sob a sua marca se aplica a praticamente qualquer SaaS vertical. Alguns casos com guias dedicados:

• Fintechs e plataformas financeiras: contratos de crédito, cessão e abertura de conta com mTLS e perfis de alto nível — veja a API de assinatura para fintechs.
• RH e people-tech: admissão digital, termos e aditivos assinados dentro do seu ATS/HRIS — veja a API de assinatura para RH e admissão digital.
• E-commerce e marketplaces: contratos de seller, termos de adesão e onboarding de vendedores — veja a API de assinatura para e-commerce e marketplaces.

Em todos esses casos, a sua plataforma é a marca que o usuário vê, e a assinatura é apenas mais um recurso nativo. É exatamente o que o modelo white-label viabiliza.

Roteiro de integração em 6 passos

1. Escolha o modelo multi-tenant: conta única com tenant_id nos metadados ou subcontas por cliente, conforme seus requisitos de isolamento e billing.
2. Configure OAuth2 (e mTLS se regulado): obtenha credenciais no ambiente de homologação e implemente o fluxo client-credentials.
3. Crie a sessão de assinatura: chame POST /v1/signing-sessions com documento, signatário, policy.profile e metadata.tenant_id.
4. Embuta a experiência: abra o checkout via SDK @signdocs-brasil/js com o clientSecret, ou redirecione para o checkout hospedado (url?cs=...).
5. Receba webhooks: valide HMAC-SHA256, processe de forma idempotente e roteie por tenant; conecte TRANSACTION.COMPLETED ao seu billing.
6. Promova para produção: valide o fluxo end-to-end em HML (lembre do TTL de 7 dias), depois troque o host e as credenciais para o ambiente produtivo.

Esse roteiro mantém o seu time focado no produto, enquanto a complexidade criptográfica e regulatória fica encapsulada na API.