Checklist: 20 Perguntas Técnicas Antes de Contratar uma API de Assinatura

Toda demo de API de assinatura é bonita. O custo real aparece depois: na integração que travou num limite não documentado, no webhook que se perdeu sem retry, na disputa judicial em que a "evidência" era um PDF que só o fornecedor sabia ler. Este checklist reúne as 20 perguntas que expõem esses custos antes do contrato — agrupadas em seis blocos, cada uma com o porquê. Copie, cole no e-mail para os fornecedores candidatos e exija resposta por escrito. Para cada pergunta, incluímos a resposta da SignDocs — inclusive onde ela é "não".

Bloco 1 — Avaliação e desenvolvimento

1. Existe ambiente de homologação gratuito e completo, sem cartão de crédito?
Por quê: se você não consegue validar o fluxo inteiro antes de assinar contrato, a avaliação é fé, não engenharia.
SignDocs: sim — api-hml.signdocs.com.br, gratuito, sem cartão, com o fluxo completo (sessões, envelopes, webhooks, evidências). Entidades expiram em 7 dias. Detalhes.

2. Há SDKs oficiais nas linguagens da minha stack — mantidos pelo fornecedor, não pela comunidade?
Por quê: SDK comunitário abandonado vira dívida técnica sua.
SignDocs: seis SDKs oficiais — TypeScript/Node (npm), Python (PyPI), PHP (Composer), Java (Maven), C#/.NET (NuGet), Go — todos com OAuth2 e verificação de webhook embutidos.

3. A documentação mostra payloads reais de requisição e resposta, ou só descrições?
Por quê: documentação sem JSON real significa engenharia reversa por tentativa e erro.
SignDocs: docs com payloads completos em docs.signdocs.com.br, mais quickstarts por linguagem.

4. Quantas chamadas são necessárias para o caso mais simples (um documento, um signatário)?
Por quê: a ergonomia do caso simples prevê a do complexo.
SignDocs: uma — POST /v1/signing-sessions recebe documento e signatário e devolve o link de assinatura.

Bloco 2 — Segurança da integração

5. Como é a autenticação da API — tokens estáticos ou credenciais de curta duração?
Por quê: um token estático vazado vale até alguém notar; um token de minutos, quase nada.
SignDocs: OAuth2 client-credentials com bearer token de 15 minutos, JWT assinado com ES256 e chaves em KMS. Detalhes.

6. Os webhooks são assinados criptograficamente? Como eu verifico?
Por quê: webhook sem assinatura é um endpoint seu que aceita ordens de qualquer um.
SignDocs: HMAC-SHA256 sobre {timestamp}.{corpo}, com tolerância de 5 minutos contra replay; os SDKs trazem o verificador pronto. Detalhes.

7. Qual a política de retry dos webhooks quando meu endpoint falha?
Por quê: a diferença entre "perdi o evento" e "recebi atrasado" é a diferença entre reconciliação manual e nenhuma.
SignDocs: retry com backoff exponencial; idempotência pelo id do evento; e o estado é sempre reconstruível por GET /v1/transactions.

8. Há suporte a mTLS para cenários regulados?
Por quê: BACEN, Open Finance e clientes enterprise exigem.
SignDocs: sim, como recurso de contrato enterprise. Detalhes.

9. Existe idempotência nas operações de criação?
Por quê: sem ela, um timeout de rede vira documento duplicado — e cobrança duplicada.
SignDocs: header X-Idempotency-Key com janela de 24h: mesmo corpo devolve a resposta original; corpo diferente com a mesma chave, 409.

Bloco 3 — Prova e evidências

10. O que exatamente fica registrado como evidência de cada assinatura?
Por quê: é isso que você apresentará numa contestação — "trilha de auditoria" sem detalhes é slogan.
SignDocs: método de autenticação de cada etapa (com resultado e horários), IP, geolocalização, user-agent, hash SHA-256 do documento e carimbo de hora do servidor, consolidados no evidence pack (.p7m).

11. As evidências podem ser verificadas de forma independente, sem depender do fornecedor?
Por quê: prova que só o emissor consegue validar vale menos no dia em que você discorda do emissor.
SignDocs: sim — verificador público, aberto a qualquer pessoa, sem conta; o .p7m é um container padrão PKCS#7 legível por ferramentas de mercado.

12. Que níveis de autenticação do signatário a API oferece — e posso variar por signatário?
Por quê: exigir certificado de todo mundo trava conversão; aceitar só clique enfraquece contratos críticos. O desenho certo é por risco.
SignDocs: clique, clique+OTP, biometria facial com prova de vida (e variantes com cross-check governamental), certificado ICP-Brasil — um policy.profile por signatário, no mesmo envelope. Detalhes.

13. Certificado ICP-Brasil é nativo ou módulo adicional pago?
Por quê: no Brasil, assinatura qualificada não é recurso exótico — cobrar à parte é sinal de plataforma pensada para outro mercado.
SignDocs: nativo. A1 no fluxo da API (o signatário usa o certificado dele; a chave nunca sai do titular); A3 físico pelo assinador desktop. Detalhes.

14. Há carimbo de tempo de ACT credenciada (RFC 3161)? Que nível de assinatura é gerado?
Por quê: pergunta que expõe fornecedores que prometem "carimbo do tempo" sem dizer qual.
SignDocs: não — resposta honesta: o nível gerado é o baseline (PAdES-B/CAdES-B), com carimbo de hora do servidor amarrado ao hash na trilha append-only, sem ACT/LTV. Para a maioria dos contratos privados isso é suficiente; se o seu caso exigir ACT, pergunte a qualquer fornecedor qual ACT e em qual nível. Nossa explicação completa.

Bloco 4 — Operação em produção

15. Quais são os rate limits e as cotas — e o que acontece quando estouro?
Por quê: o limite que você descobre em produção custa caro; o comportamento no estouro (erro claro vs falha silenciosa) custa mais.
SignDocs: headers RateLimit-* padrão nas respostas, cotas por operação dimensionadas em contrato, erros RFC 7807 com código legível. Detalhes.

16. Como o fornecedor comunica incidentes e disponibilidade?
Por quê: sem página de status, cada instabilidade vira um ticket seu.
SignDocs: status.signdocs.com.br, pública.

17. Os erros da API são estruturados e acionáveis?
Por quê: "400 Bad Request" sem detalhe é uma tarde de debugging; um código de erro documentado é um if.
SignDocs: problem+json (RFC 7807) com tipo, código e mensagem em pt-BR voltada ao signatário quando aplicável. Catálogo.

Bloco 5 — Compliance e dados

18. Onde os dados são processados e armazenados, e sob quais compromissos LGPD?
Por quê: seu DPO vai perguntar; melhor você perguntar primeiro. Desconfie de "dados 100% no Brasil" sem documento que sustente.
SignDocs: infraestrutura AWS multi-região (sa-east-1 e us-east-1), DPA público, Tabela de Retenção e sub-operadores documentados na Central de Confiança.

19. Consigo exportar todos os meus documentos e evidências se decidir sair?
Por quê: lock-in de prova é o pior lock-in — pergunte antes de entrar.
SignDocs: sim — documentos assinados e evidence packs são baixáveis pela API (/download e /evidence) a qualquer momento; e a verificação independe de nós (pergunta 11).

20. O modelo de preço é público e previsível para o meu volume?
Por quê: por documento, por envelope, por signatário e por "crédito" produzem contas muito diferentes no mesmo uso.
SignDocs: o acesso de produção à API é um plano sob medida — dimensionado por volume e requisitos com o time comercial, sem tabela pública. A contrapartida é a que importa numa avaliação: você valida tudo tecnicamente no sandbox gratuito antes de qualquer conversa de preço. O raciocínio de custo está em quanto custa uma API de assinatura.