SignDocs Brasil

O SignDocs Brasil é o plugin oficial do WordPress para assinaturas eletrônicas com validade jurídica no Brasil. Incorpore fluxos de assinatura em qualquer página com um shortcode ou bloco Gutenberg, envie envelopes multi-signatário (sequenciais ou paralelos), verifique evidências assinadas direto no painel do WordPress e acompanhe tudo por um log de auditoria com exportação para CSV.

Construído sobre o SDK PHP oficial do SignDocs Brasil (signdocs-brasil/signdocs-brasil-php), o plugin aproveita cache de token OAuth compartilhado entre os workers do PHP-FPM, idempotência determinística, rotação de segredo de webhook com janela de tolerância e observabilidade via cabeçalhos de resposta RateLimit-* / Deprecation / Sunset.

O plugin é voltado ao mercado brasileiro (conformidade com a MP 2.200-2/2001, ICP-Brasil, NT65/ITI para o crédito consignado do INSS), mas funciona para qualquer fluxo de assinatura no mundo. A interface de assinatura é hospedada em sign.signdocs.com.br, isolada da sua instalação WordPress — assim, um site WordPress comprometido não consegue forjar assinaturas.

Por que SignDocs Brasil?

• Conformidade brasileira — MP 2.200-2/2001, pacote de evidências PKCS#7/CMS, suporte a certificado ICP-Brasil A1/A3, fluxo NT65/ITI para crédito consignado do INSS
• Sete políticas de verificação — CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, BIOMETRIC_PLUS_OTP, DIGITAL_CERTIFICATE, BIOMETRIC_SERPRO, BIOMETRIC_SERPRO_AUTO_FALLBACK
• Envelopes multi-signatário — sequenciais (cada signatário aguarda o anterior) ou paralelos (todos assinam ao mesmo tempo), com download consolidado em .p7s ou PDF combinado ao final
• Dois modos de autenticação — OAuth2 client_credentials (simples) ou Private Key JWT ES256 (para clientes regulados que não podem armazenar segredos compartilhados)
• Integração WooCommerce — envia o link de assinatura por email automaticamente após a conclusão do pedido
• Trilha de auditoria completa — toda chamada de API e toda entrega de webhook são registradas em uma tabela dedicada, com visão filtrável (WP_List_Table) e exportação para CSV
• GDPR / LGPD — handlers de exportação e de eliminação de dados registrados no painel de privacidade do WordPress
• Observabilidade — cabeçalhos RateLimit-* capturados para o widget do painel; avisos de descontinuação (RFC 8594 Deprecation / Sunset) aparecem como avisos no admin
• Zero código — configure tudo pelo painel do WordPress

Funcionalidades

• Shortcode [signdocs] e bloco Gutenberg para incorporar o botão de assinatura em qualquer página ou post
• Custom post type signdocs_envelope para fluxos multi-signatário com repetidor de signatários
• Página administrativa “Verificar Documento” — cole um ID de evidência ou de envelope e inspecione identidades dos signatários, CNPJ do tenant e downloads consolidados
• Log de auditoria com filtros por nível, tipo de evento e intervalo de datas, além de exportação em CSV por streaming (via php://output, segura para exportações de vários GB)
• Rotação de segredo de webhook com janela de tolerância de 7 dias — ambos os segredos (atual + anterior) são aceitos durante a rotação
• Cobertura dos 17 tipos de evento de webhook, incluindo os eventos NT65 (STEP.PURPOSE_DISCLOSURE_SENT, TRANSACTION.DEADLINE_APPROACHING)
• Capacidades personalizadas (signdocs_manage, signdocs_send, signdocs_verify, signdocs_view_logs) concedidas automaticamente a administrador / editor / autor
• Comandos WP-CLI (wp signdocs health | send | status | webhook-test | log-tail) para automação via shell
• Integração WooCommerce — aba de produto “Assinatura SignDocs”, email automático com o link de assinatura e notas de pedido após a conclusão
• Popup, redirecionamento ou overlay — escolha o modo de incorporação que combina com o seu tema
• Assinatura anônima opcional, com limitação de taxa (rate limiting)
• Credenciais criptografadas com AES-256-CBC em wp_options
• Receptor de webhook reforçado: trava de desvio de timestamp (≤300s), verificação HMAC-SHA256 com comparação em tempo constante, deduplicação contra replay via X-SignDocs-Webhook-Id
• Cache de token OAuth compartilhado via transients do WordPress (WpTransientTokenCache implementa a TokenCacheInterface do SDK) — um único token reaproveitado por todos os workers do PHP-FPM
• Chaves de idempotência determinísticas em toda chamada que cria recursos — retentativas via AJAX nunca criam sessões duplicadas
• Observador de descontinuação (RFC 8594) que exibe um aviso no admin quando a API sinaliza a remoção de um endpoint
• Traduzível: Inglês, Português (Brasil), Espanhol

Casos de uso

• Escritórios de advocacia — procurações, contratos, termos e envelopes multi-parte
• Imobiliárias — contratos de locação e de compra/venda assinados por inquilino, proprietário e fiador (envelope sequencial)
• E-commerce — termos de serviço, contratos de fornecedor, NDAs pós-compra
• RH e departamento pessoal — contratos de trabalho, termos de confidencialidade, documentação de onboarding
• Educação — fichas de matrícula e autorização dos responsáveis (responsáveis + aluno em envelope paralelo)
• SaaS — termos de uso e contratos de licença no onboarding
• Crédito consignado do INSS (específico do Brasil) — fluxo NT65 com verificação biométrica SERPRO e notificação de averbação da finalidade
• Bancos e instituições financeiras — o Private Key JWT permite assinar sem armazenar um segredo compartilhado no banco de dados

Como funciona

1. Configure as credenciais da API SignDocs Brasil no painel do WordPress (Client ID + Secret, ou Chave Privada + Key ID)
2. Adicione um shortcode, um bloco Gutenberg ou crie um envelope multi-signatário pelo admin
3. O signatário clica em “Assinar Documento” e é redirecionado ao domínio seguro sign.signdocs.com.br (a assinatura nunca acontece dentro do seu site WordPress — isso isola a sua instalação de qualquer comprometimento)
4. O signatário conclui o fluxo conforme a política configurada (aceite, OTP, biometria, certificado digital)
5. Os webhooks atualizam o status no painel do WordPress em tempo real; o pacote de evidências .p7m fica disponível para download e verificação

Links

• Site oficial
• Documentação da API
• Suporte
• Criar conta gratuita
• Repositório no GitHub

Uso

Shortcode

Adicione em qualquer página ou post:

Com formulário de nome / email / CPF:

Atributos disponíveis:

• document_id (obrigatório) — ID do anexo PDF na biblioteca de mídia
• policy — uma de: CLICK_ONLY, CLICK_PLUS_OTP, BIOMETRIC, BIOMETRIC_PLUS_OTP, DIGITAL_CERTIFICATE, BIOMETRIC_SERPRO, BIOMETRIC_SERPRO_AUTO_FALLBACK
• locale — idioma: pt-BR, en, es
• mode — modo de incorporação: redirect (padrão), popup, overlay
• button_text — rótulo do botão (padrão: “Assinar Documento”)
• show_form — "true" para exibir campos de nome / email / CPF / CNPJ
• return_url — URL de redirecionamento após a assinatura
• class — classe CSS adicional para o botão

Bloco Gutenberg

1. No editor de blocos, clique em “+” para adicionar um bloco
2. Pesquise por “SignDocs” ou “Assinatura”
3. Selecione um PDF na barra lateral à direita
4. Configure a política, o idioma e o modo
5. Publique a página

Envelopes multi-signatário

Para contratos com mais de um signatário (por exemplo, proprietário + inquilino + fiador), use o menu Envelopes:

1. Painel > Assinaturas > Envelopes > Adicionar Novo
2. Selecione o modo de assinatura:
   • SEQUENTIAL — cada signatário assina em ordem; o próximo só recebe o link quando o anterior conclui
   • PARALLEL — todos os signatários podem assinar simultaneamente, em qualquer ordem
3. Adicione os signatários (nome + email + CPF ou CNPJ + política opcional por signatário)
4. Anexe o PDF e publique
5. Cada signatário recebe um email com o link individual; o admin vê o status do envelope atualizar conforme cada assinatura é concluída
6. Após todos assinarem, um PDF combinado e carimbado (ou um .p7s consolidado, para documentos não-PDF) fica disponível para download

Os eventos de webhook STEP.STARTED, STEP.COMPLETED e STEP.FAILED são registrados por signatário no log de cada envelope.

WooCommerce

1. Edite um produto e abra a aba “Assinatura SignDocs”
2. Marque “Requer assinatura” e selecione o PDF
3. Configure a política de verificação
4. Quando um pedido é concluído, o link de assinatura é enviado por email ao cliente automaticamente
5. Após a assinatura, uma nota é adicionada ao pedido com o ID de evidência

O CPF ou CNPJ do cliente deve estar presente no pedido. O plugin lê as chaves de meta padrão _billing_cpf / _billing_cnpj usadas pela extensão Brazilian Market on WooCommerce. Se nenhum estiver presente, o plugin adiciona uma nota ao pedido explicando o requisito e não cria a sessão.

Verificação de documentos

A página Assinaturas > Verificar (requer a capacidade signdocs_verify):

1. Cole um evidence_id (assinatura única) ou um envelope_id (multi-signatário)
2. O plugin chama GET /v1/verify/{id} ou GET /v1/verify/envelope/{id} e exibe:
   • Identidades de cada signatário (nome, CPF/CNPJ)
   • CNPJ do tenant
   • Horários de cada etapa
   • O perfil de política aplicado
   • Links de download: pacote de evidências (.p7m), PDF assinado, .p7s consolidado (envelopes), PDF combinado (envelopes)
3. Use os arquivos de evidência em validadores externos (Validador ITI, Adobe Acrobat) para confirmação independente

Log de auditoria

A página Assinaturas > Log de Auditoria (requer a capacidade signdocs_view_logs):

• Visão WP_List_Table sobre {prefix}signdocs_log
• Filtros: nível (debug / info / warning / error), tipo de evento, intervalo de datas
• Exportação em CSV via admin-post.php (streaming em blocos, segura para exportações de vários GB)
• Retenção automática de 30 dias pela tarefa cron diária signdocs_prune_logs
• Toda chamada de API, entrega de webhook e aviso de descontinuação é registrada com contexto em JSON

WP-CLI

Para operações via shell (úteis para automação, CI/CD e diagnóstico):

— verifica a conectividade com a API no ambiente configurado

— cria uma sessão de assinatura a partir de um anexo do WordPress e imprime o ID e a URL da sessão

— consulta o status de uma sessão pelo ID

— envia uma entrega de teste para um webhook registrado

— mostra as últimas N entradas do log de auditoria filtradas por nível

Rotação do segredo de webhook

1. Em Configurações > SignDocs Brasil, clique em “Rotacionar Segredo”
2. O plugin solicita um novo segredo à API; o segredo anterior passa a ser o “segredo anterior”, com uma janela de tolerância de 7 dias
3. Durante a janela, o endpoint /wp-json/signdocs/v1/webhook aceita ambos os segredos — entregas em trânsito não são rejeitadas
4. Após 7 dias, a tarefa cron diária signdocs_expire_prev_secret remove o segredo antigo
5. O status da rotação fica visível no admin (com contagem regressiva)

Para desenvolvedores

Hooks disponíveis:

Ciclo de vida da sessão:

• signdocs_session_created — Sessão criada (via API, não necessariamente via WordPress)
• signdocs_signing_completed — Assinatura concluída com sucesso
• signdocs_signing_cancelled — Assinatura cancelada pelo integrador ou pelo signatário
• signdocs_signing_expired — Sessão expirada sem conclusão
• signdocs_signing_failed — Assinatura falhou (erro irrecuperável)
• signdocs_transaction_fallback — Fallback acionado (ex.: SERPRO indisponível)

Por etapa (para envelopes e fluxos personalizados):

• signdocs_step_started — Etapa iniciada (OTP enviado, captura biométrica etc.)
• signdocs_step_completed — Etapa concluída
• signdocs_step_failed — Etapa falhou
• signdocs_purpose_disclosure_sent — (NT65) Notificação de averbação da finalidade entregue ao beneficiário
• signdocs_deadline_approaching — (NT65) ≤2 dias úteis antes do prazo de envio ao INSS

Tenant / API:

• signdocs_quota_warning — Uso do tenant cruzou um limite (80 / 90 / 100%)
• signdocs_api_deprecation_notice — A API sinalizou um endpoint descontinuado

WooCommerce:

• signdocs_wc_signing_completed — Assinatura de um pedido WooCommerce concluída

Cada ação recebe $post_id (do CPT signdocs_signing ou signdocs_envelope) e $payload (o array bruto do webhook) como argumentos, exceto signdocs_quota_warning e signdocs_api_deprecation_notice, que recebem apenas o payload.

Capacidades:

• signdocs_manage — Configurar credenciais, webhook e identidade visual; gerenciar envelopes de outros usuários
• signdocs_send — Criar sessões e envelopes
• signdocs_verify — Usar a página de Verificação e inspecionar evidências
• signdocs_view_logs — Acessar o log de auditoria e exportar CSV

Use current_user_can('signdocs_send') no lugar de manage_options / edit_posts ao adicionar funcionalidades personalizadas.

SDK PHP:

O cliente do SDK já configurado (com credenciais criptografadas e cache de token compartilhado) está disponível via:

Consulte a documentação do SDK PHP para a superfície completa (transactions, envelopes, verification, users, documentGroups, webhooks etc.).

Serviços externos

Este plugin se conecta à plataforma SignDocs Brasil — operada pela mesma empresa que publica o plugin — para criar, entregar e verificar assinaturas eletrônicas. O plugin não funciona sem enviar dados a esses endpoints, porque a assinatura em si acontece nos servidores do SignDocs (o site WordPress apenas orquestra a requisição e armazena a referência do resultado).

API SignDocs Brasil (api.signdocs.com.br / api-hml.signdocs.com.br)

Usada para criar sessões de assinatura, registrar webhooks, verificar evidências assinadas e gerenciar envelopes multi-signatário. O plugin se autentica com as credenciais de API que você informa no painel do WordPress (OAuth2 client_credentials ou, alternativamente, Private Key JWT quando configurado).

• Quais dados são enviados, a cada criação de sessão: o conteúdo do documento PDF (codificado em base64), o nome do signatário, o email do signatário, o CPF ou CNPJ do signatário (um deles é exigido pela API), a política de verificação selecionada (ex.: CLICK_ONLY, BIOMETRIC), a preferência de idioma, uma URL de retorno opcional e campos de metadados que identificam a URL do site WordPress e a origem (shortcode, AJAX, WP-CLI, WooCommerce, envelope).
• Quando: sempre que uma sessão de assinatura é criada. Isso ocorre no envio via AJAX do shortcode, no wp signdocs send da WP-CLI, na conclusão de pedido WooCommerce quando o produto está configurado para assinatura, e em toda criação de envelope / adição de novo signatário.
• Outras chamadas de API que não enviam dados do documento: registro de webhook, consulta de status (GET /v1/signing-sessions/{id}), verificação de evidência (GET /v1/verify/{evidenceId}), status de envelope. Estas enviam apenas o identificador correspondente que você fornece (ID da sessão, ID de evidência, ID do envelope).
• Autenticação: toda chamada de API é autenticada com um token Bearer de curta duração obtido no endpoint OAuth2 no mesmo domínio (POST {baseUrl}/oauth2/token). O plugin envia o seu Client ID e o Client Secret ou uma asserção JWT assinada (quando o modo Private Key JWT está configurado) a esse endpoint na primeira chamada e novamente quando o token em cache expira (tipicamente uma vez por hora, por ambiente); o token de acesso é armazenado em um transient do WordPress e reaproveitado em todas as chamadas seguintes. Nenhum dado do signatário é enviado ao endpoint de token.
• Troca de ambiente: o plugin usa api-hml.signdocs.com.br (HML / sandbox) por padrão e api.signdocs.com.br somente quando o administrador troca explicitamente o ambiente para “Produção” na página de configurações.
• Fornecido por SignDocs Brasil. Termos de Uso. Política de Privacidade.

SDK de navegador SignDocs Brasil (cdn.signdocs.com.br / cdn-hml.signdocs.com.br)

Um arquivo JavaScript (signdocs-brasil.js) carregado do CDN do SignDocs que abre o popup, o redirecionamento ou o overlay de assinatura quando o signatário clica no botão “Assinar Documento” renderizado pelo shortcode ou bloco Gutenberg.

• Quais dados são enviados: nada diretamente por este carregamento de script — é uma requisição de recurso estático, igual à de qualquer outro arquivo JavaScript de um CDN de terceiros. Nenhuma informação pessoal é transmitida pela requisição ao CDN em si; o script é idêntico, byte a byte, para todos os sites que o carregam.
• Quando: a cada visualização de página no front-end que renderiza o shortcode [signdocs] ou o bloco Gutenberg do SignDocs (o script é enfileirado condicionalmente — páginas sem o bloco não o carregam).
• O ambiente do CDN (HML vs. produção) segue a mesma opção signdocs_environment da API.
• Fornecido por SignDocs Brasil. Termos de Uso. Política de Privacidade.

Interface de assinatura SignDocs Brasil (sign.signdocs.com.br)

Após o signatário clicar em “Assinar Documento”, ele é levado à página segura de assinatura em sign.signdocs.com.br — e não a uma página hospedada pelo seu site WordPress. O fluxo de assinatura (OTP, captura biométrica, seleção de certificado digital, confirmação por aceite) é executado inteiramente nesse domínio. Esse isolamento é intencional: mesmo que o seu site WordPress fosse comprometido, um atacante não conseguiria forjar assinaturas, porque os fatores de autenticação são coletados em uma origem separada, sob controle do SignDocs Brasil.

• Quais dados são enviados: o signatário interage diretamente com esse domínio para concluir o fluxo de assinatura. Os dados trocados ali (códigos OTP, fotos biométricas, seleção de certificado) não passam pelo seu site WordPress. O seu plugin recebe de volta apenas o resultado, via o webhook descrito acima.
• Quando: quando o signatário clica no botão de assinatura renderizado pelo plugin e o SDK de navegador abre a superfície de assinatura (popup / redirecionamento / overlay).
• Fornecido por SignDocs Brasil. Termos de Uso. Política de Privacidade.