Segurança da API SignDocs: Arquitetura, Chaves, Webhooks e Continuidade (Guia para o CISO)

Toda integração de assinatura eletrônica passa, mais cedo ou mais tarde, por uma pergunta do time de segurança: o que exatamente acontece com nossas credenciais, nossos documentos e os dados dos nossos signatários quando chamamos essa API? Este guia responde a essa pergunta na ordem em que ela costuma aparecer num questionário de due diligence: identidade e tokens, transporte, proteção de borda, segredos, webhooks, integridade das evidências, dados pessoais e continuidade. No fim, um checklist do integrador lista o que fica do seu lado.

A regra editorial aqui é simples: cada afirmação abaixo descreve um controle que existe hoje na infraestrutura da SignDocs Brasil. Onde o mercado costuma prometer mais do que entrega, dizemos o que não afirmamos. Se você precisa de um documento assinável para o seu processo de fornecedores, a Central de Confiança reúne os instrumentos públicos (DPA, sub-operadores, tabela de retenção, SLA) que este artigo cita.

1. Identidade e tokens: OAuth2 com chave que nunca sai do KMS

A API usa OAuth2 client credentials. A integração troca client_id e client_secret por um token de acesso em POST /oauth2/token (corpo application/x-www-form-urlencoded), e usa esse token como Bearer nas chamadas seguintes. Três propriedades importam para quem audita:

• Assinatura ES256 no AWS KMS. O token é um JWT assinado com ECDSA P-256. A chave privada é gerada e mantida dentro do AWS KMS: a aplicação pede ao KMS que assine, mas nunca recebe o material da chave. Não há arquivo de chave em disco, em variável de ambiente ou em repositório para vazar.
• Chave multirregião. A mesma chave é replicada entre as regiões da plataforma (detalhes na seção de continuidade), de modo que um token emitido numa região é verificável na outra sem troca de segredo.
• Vida curta: 900 segundos. O expires_in é de 15 minutos. Um token capturado num log ou num proxy tem janela de uso pequena. O cliente deve renovar por demanda, não armazenar tokens por horas.

O client_secret é exibido uma única vez ao ser criado no painel; depois disso só existe cifrado do nosso lado. Credenciais podem ser pausadas, rotacionadas e revogadas pelo próprio cliente, e a boa prática é uma credencial por sistema ou equipe, para que revogar uma não derrube as outras. O passo a passo de obtenção e rotação está em como obter credenciais de API; a mecânica do fluxo OAuth2, em OAuth2 e autenticação da API.

2. Transporte: TLS sempre, mTLS quando o contrato pedir

Toda comunicação com a API é sobre HTTPS; não existe endpoint em texto claro. Para clientes enterprise que exigem autenticação mútua na camada de transporte, a plataforma oferece mTLS opcional: o cliente apresenta um certificado próprio além da credencial OAuth2, e a API só aceita conexões cujo certificado esteja cadastrado. O guia mTLS e segurança enterprise descreve o cadastro e o comportamento em caso de certificado inválido.

O mTLS não substitui o token: ele é uma segunda camada, que responde a uma exigência frequente em bancos, cooperativas e grupos com política de zero trust de rede. Para a maioria das integrações, TLS com credencial rotacionada e token de 15 minutos é o desenho adequado.

3. Proteção de borda: WAF na frente da API

O API Gateway fica atrás de um AWS WAF com duas famílias de regras: um limite de taxa por IP, que bloqueia temporariamente origens que excedem o volume esperado de requisições numa janela curta, e o conjunto de regras gerenciadas da AWS para padrões conhecidos de ataque (injeções, corpos malformados, restrições de tamanho). Essas regras atuam antes da autenticação, ou seja, antes de qualquer código da aplicação ser executado.

Acima do WAF, a própria API aplica limites de uso por credencial: cotas diárias e mensais de operações, sinalizadas ao cliente com os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset nas respostas 429. Erros seguem o formato RFC 7807 (application/problem+json). Os dois mecanismos e a idempotência de requisições estão detalhados em rate limits, paginação e idempotência.

4. Segredos: cifrados em repouso, lidos sob demanda

Os segredos que a plataforma guarda em nome do cliente, e os que usa para operar, ficam cifrados em repouso e são lidos em tempo de execução pelo AWS Secrets Manager ou diretamente por chaves no KMS:

Do seu lado, a contrapartida é igualmente concreta: client_secret e segredo de webhook devem ficar no cofre de segredos do seu ambiente, nunca em código, em variáveis públicas de front-end ou em apps móveis. Esse é o erro mais comum que vemos em integrações e o primeiro item do checklist ao fim do artigo.

5. Webhooks: HMAC, carimbo de tempo e proteção contra replay

Cada evento entregue ao seu endpoint carrega dois cabeçalhos: X-SignDocs-Signature, um HMAC-SHA256 em hexadecimal, e X-SignDocs-Timestamp, o instante do envio em segundos Unix. A assinatura é calculada sobre a string {timestamp}.{payload} com o segredo do webhook. Para validar, o receptor recomputa o HMAC sobre o corpo bruto da requisição (antes de qualquer parse de JSON), compara em tempo constante e rejeita entregas cujo carimbo esteja fora de uma tolerância de 300 segundos. A tolerância é o que impede que uma entrega capturada seja reapresentada horas depois.

Do lado da plataforma, a entrega é feita por um worker com fila: cada tentativa tem timeout de 15 segundos; erros de servidor e de rede são repetidos até três tentativas com espera crescente; uma resposta fora de 2xx após isso é registrada como falha, sem reentrega indefinida. Isso tem duas consequências de segurança para o seu desenho:

• Responda 2xx rápido e processe depois. Endpoints lentos viram falhas de entrega, e tratar o evento de forma síncrona dentro do handler é o caminho para perder eventos. A arquitetura recomendada está em webhooks em fila e reprocessamento.
• O webhook é notificação, não fonte única de verdade. Para decisões com efeito financeiro ou jurídico, reconcilie com GET /v1/transactions/{id} antes de agir. O catálogo de eventos e o formato do payload estão em webhooks e eventos da API.

6. Evidências e integridade: hash, pacote .p7m e verificador público

Segurança de assinatura eletrônica não é só proteger o acesso; é garantir que, anos depois, alguém consiga demonstrar que aquele documento foi assinado por aquela pessoa, daquele jeito. Três controles cuidam disso:

1. SHA-256 do documento. Ao receber o arquivo (base64 na criação ou upload direto por URL pré-assinada), a plataforma calcula e registra o hash SHA-256. O documento assinado passa a estar vinculado a esse hash na trilha de auditoria; qualquer alteração posterior de um byte é detectável. Recomendamos que o cliente calcule e guarde o mesmo hash antes de enviar, para ter a comparação nos próprios registros.
2. Trilha de auditoria por etapa. Cada passo do fluxo (aceite, OTP, prova de vida, comparação facial, cross-check SERPRO quando configurado, assinatura com certificado) registra resultado, carimbo de data e hora em UTC, IP, geolocalização e user-agent do signatário.
3. Pacote de evidências .p7m. Ao concluir, a trilha e o documento são reunidos num pacote CMS/PKCS#7 selado pela plataforma, disponível em GET /v1/transactions/{id}/evidence. Ele pode ser validado de forma independente e é o que se junta a um processo em caso de contestação. Formato e conteúdo estão em evidence pack .p7m.

Qualquer pessoa com o identificador de evidência pode conferir a autenticidade no verificador público (verificador.signdocs.com.br), sem conta e sem acesso à API. Para o time de segurança, isso significa que a prova não depende da continuidade da relação comercial nem de um login na plataforma.

7. Dados pessoais e LGPD: papéis, instrumentos e retenção

Na integração via API, o cliente é o controlador dos dados dos signatários (decide o que coletar e por quê) e a SignDocs Brasil atua como operadora, tratando os dados segundo as instruções do contrato. Os instrumentos que formalizam isso são públicos e não exigem negociação para serem consultados:

• DPA (acordo de tratamento de dados): obrigações da operadora, medidas de segurança, cooperação em incidentes e no atendimento a titulares.
• Lista de sub-operadores: os provedores de infraestrutura e serviços (nuvem, e-mail, SMS, biometria, validação governamental) envolvidos no tratamento, com a finalidade de cada um.
• Tabela de retenção: por quanto tempo cada categoria de dado é mantida e quando é eliminada. Os prazos valem para produção; o ambiente de homologação descarta tudo em 7 dias.
• Política de privacidade e canal do encarregado (DPO) para o exercício de direitos dos titulares.

Dado biométrico é dado sensível. Quando um perfil biométrico é usado, o signatário aceita expressamente o termo de tratamento antes da captura; a imagem é processada para a verificação de identidade no ato de assinar (tecnologia AWS Rekognition) e, quando o perfil inclui o cross-check governamental, comparada com as bases do SERPRO via Datavalid. O que fica na trilha é o resultado das etapas. A plataforma não faz score de risco nem perfilamento de signatários: a biometria é etapa de autenticação, não análise de comportamento.

8. Continuidade: duas regiões e failover por health check

A infraestrutura roda na AWS em us-east-1 como região primária, com uma réplica de failover em sa-east-1 (São Paulo). O DNS da API é gerido pelo Route 53 com health checks: se a região primária deixa de responder, o tráfego é redirecionado para a réplica. A chave KMS que assina os tokens é multirregião, então os tokens continuam válidos após o redirecionamento, e os agendadores internos usam um bloqueio distribuído para que apenas uma região execute cada rotina por vez.

Dois pontos costumam aparecer em due diligence:

• Residência de dados. Os dados são tratados nas duas regiões acima, com a região primária nos Estados Unidos e a réplica em São Paulo. Requisitos contratuais específicos de localização de dados são tratados no plano sob medida, com o time comercial.
• Transparência operacional. A disponibilidade da API é publicada em status.signdocs.com.br, e os compromissos de nível de serviço estão no SLA público, na Central de Confiança.

9. O que não afirmamos

Um questionário de segurança bem feito pergunta também pelo que não existe. Para poupar uma rodada de e-mails:

• Certificações. Não publicamos hoje certificação ISO 27001 nem relatório SOC 2. Os controles descritos aqui podem ser evidenciados em processo de avaliação de fornecedor, mas não há selo de terceiro a citar.
• Score de risco. Nenhuma pontuação de fraude ou perfilamento é calculada sobre signatários ou transações.

10. Checklist do integrador

A segurança de uma integração é compartilhada. Os controles acima cobrem o lado da plataforma; a tabela abaixo cobre o seu.

Com esses itens fechados, a resposta à pergunta do início fica objetiva: suas credenciais são comparadas contra um segredo cifrado e viram tokens de 15 minutos assinados por uma chave que ninguém pode exportar; seus documentos entram por TLS, ganham um hash e saem num pacote de evidências verificável sem a nossa participação; os dados dos seus signatários são tratados sob um DPA público, com sub-operadores nomeados e prazos de retenção declarados, em duas regiões com failover automático. O que resta é a sua avaliação de que isso atende ao seu perfil de risco, e para isso o time comercial pode aprofundar qualquer item deste guia.

Perguntas Frequentes