E-Signature
BetaColeta de assinatura eletrônica em documento, com trilha de eventos por signatário
Você manda o contrato para assinar por API e acompanha, signatário a signatário, quem viu, quem assinou e quem recusou — com as credenciais do provedor cifradas e o documento isolado por cliente.
- Financeiras e fintechs que precisam de contrato assinado no fim de cada esteira de crédito
- Plataformas B2B que coletam aceite de vários signatários em ordem definida
- Operações que já têm um provedor de assinatura e não querem o código preso a ele
- Integração direta e específica com a API de um provedor de assinatura dentro do seu código
- Planilha de acompanhamento de quem já assinou e quem falta
- Envio manual de contrato por e-mail com pedido de devolução assinada
- Um provedor de assinatura — o BB orquestra, quem assina é o provedor configurado
- Uma autoridade certificadora nem um emissor de certificado ICP-Brasil
- Um gerador de documento (isso é o document-template)
- Um validador de identidade — conferir a assinatura de um arquivo não confere documento de identidade, rosto nem poderes de quem assinou
34 endpoints em 5 recursos.
/e-signature/e-signature/api/v1/esignature/requests/e-signature/api/v1/esignature/webhooks/e-signature/api/v1/esignature/e-signature/healthTelas
o que o usuário vêToque numa tela para ampliar.







Resumo executivo
O E-Signature é a camada que leva um documento até as pessoas que precisam assiná-lo e acompanha o que acontece com ele. Você envia o arquivo e a lista de signatários; o building block cria a solicitação no provedor de assinatura configurado, guarda o vínculo e passa a registrar quem visualizou, quem assinou e quem recusou.
Na prática, ele resolve o fim da esteira de crédito. Sem ele, o contrato aprovado vira um e-mail com anexo, um pedido de devolução assinada e uma planilha de acompanhamento. Com ele, POST /requests devolve um identificador e uma URL de assinatura por signatário, e GET /requests/:id responde a qualquer momento em que pé está cada um.
Está em beta desde janeiro de 2026 e é o único dos três building blocks de documentos publicado com URL própria em AMBIENTES.md. Roda no monolito e em standalone na porta 3014, e está declarado nas pilhas de staging e de produção. Um único provedor está implementado — o OpenSign, auto-hospedado. Os demais aparecem no schema e recusam a operação em tempo de execução. Leia a §15 e a §14 antes de prometer prazo ou validade jurídica a cliente.
Desde 01/10/2026 o bloco também confere assinatura de arquivo: recebe um PDF, P7S ou XML assinado com certificado ICP-Brasil ou gov.br (PAdES, CAdES, XAdES) e devolve válido, inválido ou indeterminado, quem assinou (nome do certificado e CPF/CNPJ mascarado), quando, a cadeia e os motivos. O primeiro provedor é o Verificador de Conformidade ICP-Brasil — o software por trás de validar.iti.gov.br —, gratuito, de código aberto e operado por nós ou pelo LabSEC/UFSC, nunca pelo domínio do ITI (os termos do ITI proíbem). Enviar o arquivo ao verificador começa desligado por organização. O detalhe, com as fontes, está em docs/signature-verification.md.
| Atributo | Valor |
|---|---|
| Identificador | e-signature |
| Categoria | Documentos |
| Escopo | Tenant (exige organizationId no token em todas as rotas, exceto a de webhook) |
| Porta (standalone) | 3014 |
| Path alias | @e-signature |
| Prefixo HTTP | /e-signature |
| Status | Beta desde 2026-01 |
| Depende de | PostgreSQL (schema esignature), Redis, S3, provedor de assinatura; para conferir assinatura, uma instância do Verificador de Conformidade ICP-Brasil, o file-storage e o audit-trail |
| Permissões | ESIGNATURE_ADMIN, ESIGNATURE_CREATE, ESIGNATURE_READ, ESIGNATURE_DELETE |
O problema
negócioO cenário. Uma financeira aprova uma proposta de crédito, gera a cédula e precisa que o devedor assine. Às vezes há um avalista, e ele precisa assinar depois. A operação só é liquidada quando todas as assinaturas estão coletadas, e alguém precisa saber, a qualquer momento, quantas faltam.
O que trava hoje.
- A integração fica presa a um provedor. O código chama a API do fornecedor escolhido, com o vocabulário dele: envelope, recipient, tab, template. Trocar de fornecedor — porque o preço subiu, porque o contrato acabou, porque o cliente exige outro — significa reescrever a integração inteira e migrar o histórico.
- O estado do envelope não conta a história. Saber que uma solicitação está "enviada" não responde se o devedor já viu, se o avalista recusou, ou se falta um dos dois. Quem precisa dessa resposta acaba montando uma planilha ao lado.
- A credencial do provedor mora no lugar errado. Chave de API em variável de ambiente compartilhada significa que todos os clientes da plataforma usam a mesma conta do provedor, e que rotacionar afeta todo mundo ao mesmo tempo.
- O documento circula por e-mail. Contrato com CPF, valor e condições de crédito indo e voltando como anexo é o pior caminho possível: não tem trilha, não tem controle de acesso e não tem prova de quem abriu.
- As duas testemunhas do papel viraram atrito no digital. Para um documento particular ser título executivo extrajudicial, o art. 784, III do CPC exige assinatura do devedor e de duas testemunhas. Coletar duas pessoas sem relação com o negócio, em fluxo digital, é o tipo de exigência que trava contrato pronto. A lei já resolveu isso — mas sob uma condição técnica que nem todo fornecedor cumpre (§14).
- A validade jurídica é presumida, não verificada. Muita gente assume que "assinatura eletrônica vale" sem saber qual nível de assinatura o fornecedor entrega, qual é o ônus da prova em cada nível, e em que hipóteses a lei exige mais do que isso.
O custo de não resolver. O custo operacional é o tempo entre aprovar o crédito e liquidar a operação — cada dia de contrato não assinado é capital parado e é risco de o cliente desistir. O custo estrutural aparece na renegociação com o fornecedor de assinatura: quando a integração é específica, a única alternativa a aceitar o reajuste é um projeto de meses. E o custo caro, que só aparece uma vez, é descobrir numa disputa que o nível de assinatura usado não sustenta o que você precisava provar.
Proposta de valor
negócio| Antes | Depois |
|---|---|
| O código chama a API de um provedor específico | O provedor é uma configuração por organização, cifrada no banco |
| Uma conta do provedor compartilhada por todos os clientes | Cada organização configura a própria credencial, isolada e rotacionável |
| "Está enviado" é tudo que você sabe | Estado por signatário: pendente, enviado, visualizado, assinado, recusado |
| Contrato circula como anexo de e-mail | O arquivo vem do file-storage por identificador e não trafega a cada chamada |
| Trocar de fornecedor é reescrever a integração | A troca é uma configuração nova e um set-default |
O provedor é configuração, não dependência. Toda operação passa por uma interface canônica com oito métodos. A implementação concreta é escolhida por providerType na configuração da organização. Hoje há uma implementação — e é justamente por existir a interface que a segunda custa uma classe, não um projeto.
A credencial é cifrada por organização. O que você envia em credentials é serializado e cifrado com AES-256-GCM antes de tocar o banco, usando ESIGNATURE_CREDENTIAL_MASTER_KEY. Nenhuma rota devolve o campo cifrado nem o conteúdo dele.
O signatário é cidadão de primeira classe. Signer é uma tabela, com estado próprio e carimbos de sentAt, viewedAt, signedAt e declinedAt. "Quem falta assinar" é um filtro, não uma dedução a partir do estado do envelope.
O documento fica na plataforma. fileId aponta para um arquivo já guardado no file-storage. O building block resolve o download internamente e envia ao provedor. O contrato não precisa trafegar em base64 na sua chamada — embora essa opção também exista.
Casos de uso reais
negócioCaso 1 — Uma financeira coleta assinatura de devedor e avalista em ordem Cenário ilustrativo
Financeira de crédito pessoal com garantia de terceiro. Cada operação exige a assinatura do devedor e, depois dela, a do avalista.
O fluxo anterior mandava o contrato para os dois ao mesmo tempo por e-mail. Quando o avalista assinava antes do devedor, o documento voltava fora de ordem e a operação era rejeitada na conferência. Descobrir onde cada contrato estava exigia abrir a caixa de entrada e procurar.
POST /requests com dois signatários e o campo order — 1 para o devedor, 2 para o avalista. O provedor respeita a ordem de envio. A esteira acompanha por GET /requests/:id, que devolve o envelope e a lista de signatários com o estado de cada um.
sequenceDiagram
autonumber
participant App as Esteira de crédito
participant ES as E-Signature
participant Prov as Provedor OpenSign
participant Dev as Devedor — ordem 1
participant Ava as Avalista — ordem 2
App->>ES: POST /requests com dois signatários e order 1 e 2
ES->>Prov: cria o documento em modo sequencial
Prov-->>ES: externalId e signingUrl por signatário
ES-->>App: 201 com o envelope e os signatários
Prov->>Dev: convite com o link individual de assinatura
Dev-->>Prov: assina
Prov->>ES: webhook signed
Note over ES: falta o avalista, envelope vai a PARTIALLY_SIGNED
Prov->>Ava: só agora convida o avalista
Ava-->>Prov: assina
Prov->>ES: webhook signed
Note over ES: todos assinaram, envelope vai a COMPLETED
App->>ES: GET /requests filtrando por businessId
ES-->>App: estado atual de cada signatárioA ordem deixa de depender de disciplina e passa a ser propriedade da solicitação. E a pergunta "onde está o contrato da proposta 481" tem uma resposta em uma chamada, filtrando por businessId. Com o motor local e a página hospedada, a ordem é garantida pelo próprio bloco no momento de assinar — ver o Caso 8.
Caso 2 — Uma plataforma troca de provedor de assinatura sem parar Cenário ilustrativo
Plataforma B2B que atende dezenas de empresas clientes, cada uma com preferência e contrato próprios com fornecedores de assinatura.
A integração original chamava a API de um fornecedor específico, com o vocabulário dele espalhado por vários serviços. Quando um cliente grande exigiu usar o fornecedor com quem já tinha contrato, a resposta foi um projeto de três meses — e a alternativa, perder o cliente.
Cada organização cria a própria configuração em POST /provider-configs com o providerType e as credenciais dela. O resto do código chama sempre a mesma rota; qual provedor atende é decidido pela configuração padrão do tenant, ou pelo configId explícito na chamada.
flowchart LR
App["Sua aplicação<br/>sempre a mesma chamada"] --> ES["E-Signature<br/>interface canônica de 8 métodos"]
ES --> Res{"configId informado?"}
Res -->|sim| Cfg["a configuração indicada"]
Res -->|não| Pad["a configuração padrão do tenant<br/>isDefault e isActive"]
Cfg --> Fab["createESignatureProvider<br/>lê providerType e decifra credenciais"]
Pad --> Fab
Fab --> O["OPENSIGN — implementado"]
Fab --> D["DOCUSIGN — recusa em execução"]
Fab --> A["ADOBESIGN — recusa em execução"]
Fab --> Z["ZAPSIGN — implementado (10/09/2026)"]A escolha de fornecedor vira dado, não código. Vale a ressalva honesta: hoje OpenSign e ZapSign estão implementados (DocuSign e Adobe Sign só existem no enum), então esse caso descreve a arquitetura pronta e não uma capacidade disponível — ver §15.
Caso 3 — Uma operação para de perder contrato em caixa de e-mail Cenário ilustrativo
Operação de originação com cerca de 400 contratos por mês e três pessoas acompanhando o retorno das assinaturas.
O contrato saía por e-mail, e o acompanhamento era manual. Contratos ficavam parados por semanas porque ninguém percebia que o signatário nunca tinha aberto. Não havia diferença visível entre "não viu" e "viu e não quis assinar" — e essas duas situações pedem ações opostas.
Cada solicitação registra, por signatário, o instante da visualização e o da assinatura. Quem nunca visualizou recebe POST /requests/:id/resend com o e-mail do signatário. Quem recusou aparece com status: DECLINED e o motivo, quando o provedor o fornece.
flowchart LR
Fila["Fila de acompanhamento<br/>GET /requests"] --> Q{"estado do signatário"}
Q -->|"PENDING ou SENT — viewedAt vazio"| NV["Nunca abriu o documento"]
Q -->|"VIEWED — signedAt vazio"| VN["Abriu e não assinou"]
Q -->|DECLINED| RE["Recusou, com declineReason quando o provedor informa"]
Q -->|SIGNED| OK["Assinou"]
NV --> A1["Ação: reenviar<br/>POST /requests/:id/resend"]
VN --> A2["Ação: ligar para a pessoa<br/>reenviar não resolve"]
RE --> A3["Ação: tratar a objeção ou encerrar a operação"]
OK --> A4["Ação: nenhuma — aguardar os demais signatários"]A fila de acompanhamento passa a ser ordenável por estado real. De onde vem o estado depende do provedor: no ZapSign, do webhook (corrigido em 10/09/2026, §15) e de POST /requests/:id/refresh quando um evento se perde; no OpenSign local, da própria página do bloco, que grava viewedAt no primeiro acesso, publica esignature.signer.viewed e muda o signatário a cada passo. O motor local não tem webhook, e não precisa.
Caso 4 — A lei dispensou as duas testemunhas, sob uma condição técnica Referência de mercado
O art. 784, III do Código de Processo Civil exige, para que um documento particular seja título executivo extrajudicial, a assinatura do devedor e de duas testemunhas. Coletar duas testemunhas em contrato digital sempre foi o atrito mais absurdo do processo — pessoas que não têm relação com o negócio precisam assinar para o título valer.
A Lei nº 14.620, de 13 de julho de 2023, no art. 34, acrescentou o § 4º ao art. 784 do CPC: "Nos títulos executivos constituídos ou atestados por meio eletrônico, é admitida qualquer modalidade de assinatura eletrônica prevista em lei, dispensada a assinatura de testemunhas quando sua integridade for conferida por provedor de assinatura." Duas consequências: qualquer modalidade serve — inclusive a simples — e as testemunhas caem, mas apenas sob a condição de a integridade ser conferida pelo provedor de assinatura. A condição é técnica, verificável, e é exatamente o que separa um provedor sério de um gerador de PDF com uma imagem colada.
flowchart LR
Doc["Documento particular em meio eletrônico"] --> Q1{"É CCB?"}
Q1 -->|sim| CCB["Art. 28 da Lei 10.931/2004<br/>título executivo por lei própria<br/>enquadra no art. 784, XII do CPC"]
Q1 -->|não| Q2{"A integridade é conferida<br/>pelo provedor de assinatura?"}
CCB --> Ass["Basta a assinatura do emitente<br/>art. 29, VI e § 5º<br/>eletrônica, com identificação inequívoca"]
Q2 -->|sim| S4["Art. 784, § 4º do CPC<br/>qualquer modalidade de assinatura serve<br/>as duas testemunhas são dispensadas"]
Q2 -->|não| S3["Art. 784, III do CPC<br/>continua exigindo duas testemunhas"]
S4 --> Ev{"Quem guarda a evidência<br/>de integridade hoje?"}
Ev --> P["OpenSign: hash SHA-256, trilha com IP<br/>e certificado de conclusão"]
Ev --> B["Building block, com o motor local:<br/>hash do original e do PDF selado,<br/>IP por signatário, PDF e certificado arquivados"]O OpenSign produz as evidências que sustentam essa condição: hash SHA-256 do documento final, trilha com endereço IP e um certificado de conclusão. Com o motor local, o building block as captura quando o envelope conclui: grava o SHA-256 do PDF selado (documentHash) e o nível (signatureLevel: SIMPLE), guarda na evidência o hash do original, do PDF selado e do certificado, o IP e a hora de cada signatário, e arquiva o PDF selado e o certificado de conclusão no file-storage da organização. Publica esignature.request.evidence_captured.
O caminho legal está aberto e é textualmente ancorado, e a prova de integridade fica do nosso lado, não presa ao provedor. Se o motor operado pela plataforma se enquadra como "provedor de assinatura" do § 4º é ponto a confirmar com o jurídico — não afirme que a condição está cumprida. O que continua faltando está na §15: carimbo de tempo de terceiro (RFC 3161). O certificado de conclusão se baixa por GET /requests/:id/certificate.
Caso 5 — Abertura de conta de empresa confere o contrato social assinado Cenário ilustrativo
Um banco digital abre conta de pessoa jurídica. O cliente envia o contrato social, a procuração do representante e certidões, muitos já assinados com certificado ICP-Brasil ou pela assinatura gov.br.
Alguém abre cada PDF no validar.iti.gov.br, aceita os termos, espera, tira um print e anexa ao dossiê. O print não prova nada seis meses depois, e não há como saber, por consulta, quais documentos foram conferidos.
O documento vai ao file-storage; a esteira chama POST /verifications com o fileId (ou a fachada ESignatureVerificationFacade de dentro da plataforma). A resposta traz VALID, INVALID ou INDETERMINATE, o signatário com CPF/CNPJ mascarado e os motivos; a trilha de auditoria guarda o hash do arquivo e o relatório.
sequenceDiagram
autonumber
participant Est as Esteira de abertura
participant FS as File Storage
participant ES as E-Signature
participant V as Verificador de Conformidade
participant AT as Audit Trail
Est->>FS: guarda o contrato social
Est->>ES: POST /verifications com fileId
ES->>ES: confere tipo pelo conteúdo, tamanho e consentimento da organização
ES->>V: POST /report com signature_files[]
V-->>ES: Aprovado, Reprovado, Indeterminado ou Inválido
ES->>FS: cópia temporária, com prazo
ES->>AT: esignature.verification.completed com hash e relatório
ES-->>Est: VALID com signatário mascarado"Este contrato social foi conferido?" vira consulta por hash, e a prova sobrevive à cópia do arquivo. Ressalva honesta: VALID diz que a assinatura é íntegra e o certificado é reconhecido. Não diz que quem assinou tinha poderes (isso é o companies) nem que a pessoa é quem diz além do certificado (isso é o biometrics).
Caso 6 — Termo de cessão assinado na página do bloco, sem a mesa ver o link [Validado em staging, 17/10/2026]
Na antecipação de recebíveis da CBP, cada cessão termina num termo que o cedente precisa assinar antes de o dinheiro sair.
Com um provedor de nuvem, o link de assinatura passa pelo e-mail do provedor, com a marca dele, e o documento sai do nosso ambiente. E quem opera a mesa de crédito não deveria conseguir abrir o link do cliente.
O envelope é criado com provedor OPENSIGN (o motor local, §7). O signingUrl aponta para a página do bloco, com a marca do tenant; o cedente lê o PDF, recebe o código de 6 dígitos por e-mail, desenha ou digita a assinatura, e o motor sela o documento. O bloco arquiva o PDF selado e o certificado de conclusão no file-storage.

sequenceDiagram
autonumber
participant Mesa as Mesa de crédito
participant App as Aplicação da casa
participant ES as E-Signature
participant M as Motor OpenSign local
participant FS as File Storage
participant C as Cedente
App->>ES: POST /requests com o termo, o CPF e a aparência da casa
ES->>FS: guarda o original
ES->>M: cria o documento no motor
ES-->>App: signingUrl da página do bloco
App->>C: entrega o link ao cedente
Note over Mesa: a mesa acompanha a operação, mas não recebe o link
C->>ES: abre a página, lê o PDF e marca o aceite
C->>ES: pede o código, recebe por e-mail e confere
C->>ES: desenha ou digita e assina
ES->>M: aplica a assinatura e sela o PDF
ES->>FS: arquiva o PDF selado e o certificado de conclusão
ES-->>App: esignature.request.completed e evidence_captured
App->>App: fecha a cessão com o envelope e a hora do aceiteNa prova de 17/10/2026 em staging, com e-mail real:
| Passo | O que se viu |
|---|---|
| Código por e-mail | Chegou em 4 s |
| PDF selado | Com /ByteRange e o carimbo de cada signatário: nome, data, IP e hash do original |
| Certificado de conclusão | ~97 KB, arquivado no file-storage |
| Fechamento da cessão | Sozinho, 57 s depois da assinatura, com envelopeId e a hora do aceite gravados na operação |
| Link | A mesa não vê |
Os 57 s não são do bloco: são o tempo de a aplicação da casa perceber a conclusão e fechar a operação. Do lado do bloco, a assinatura, a selagem e o arquivamento acontecem na mesma chamada de "Assinar documento".
Caso 7 — Contrato no fim da esteira de crédito, com prova guardada pela operação Cenário ilustrativo
Uma financeira aprova a proposta, gera a CCB a partir de um modelo e precisa da assinatura do tomador antes de liberar o dinheiro.
O contrato é gerado num sistema, assinado em outro e guardado num terceiro. Meses depois, numa contestação, ninguém sabe dizer qual PDF foi assinado, por quem, de que IP e se o arquivo guardado é o mesmo.
A esteira usa um único businessId — o número da proposta — do começo ao fim: o document-template gera o PDF, o file-storage o guarda, o e-signature cria o envelope com fileId e devolve o link da página. Quando o tomador assina, o bloco grava a evidência no próprio envelope e arquiva o PDF selado e o certificado com o mesmo businessId.
flowchart LR
A["Proposta aprovada"] --> DT["document-template<br/>gera a CCB"]
DT --> FS["file-storage<br/>fileId"]
FS --> ES["e-signature<br/>POST /requests com fileId e businessId"]
ES --> P["Página hospedada<br/>aceite, código, assinatura"]
P --> EV["Evidência no envelope<br/>documentHash, signatureLevel, IP por signatário"]
P --> AR["file-storage<br/>PDF selado e certificado"]
EV --> L["Liberação do crédito"]"Qual contrato a proposta 481 assinou?" vira duas consultas: GET /requests?filter[businessId]=… para o envelope e a evidência, e o file-storage para o PDF selado. Para saber se um arquivo guardado é o assinado, compare o SHA-256 dele com o documentHash do envelope. A receita "Assinar um documento gerado pelo Document Template" (§11) tem os comandos.
Caso 8 — Devedor e avalista na página hospedada, em ordem Cenário ilustrativo
A mesma operação do Caso 1, agora com o motor local: a página de assinatura é do bloco, e o bloco não manda o link por e-mail.
Com dois links na mão, nada impede a aplicação de entregar os dois ao mesmo tempo, e o avalista pode abrir o dele antes de o devedor assinar.
O envelope é criado com order: 1 para o devedor e order: 2 para o avalista. Cada um recebe o seu signingUrl. Se o avalista tentar assinar antes, o bloco recusa no momento de aplicar a assinatura, com a mensagem "Aguarde a sua vez: outra pessoa precisa assinar antes." (OUT_OF_ORDER), sem perder o desenho nem o aceite. Quando o devedor assina, o envelope vai a PARTIALLY_SIGNED; quando o avalista assina, a COMPLETED, e a evidência é capturada.
sequenceDiagram
autonumber
participant Ava as Avalista — ordem 2
participant ES as E-Signature
participant Dev as Devedor — ordem 1
Ava->>ES: tenta assinar primeiro
ES-->>Ava: 409 OUT_OF_ORDER — aguarde a sua vez
Dev->>ES: assina
Note over ES: envelope em PARTIALLY_SIGNED
Ava->>ES: assina
Note over ES: envelope em COMPLETED, PDF selado e evidênciaA ordem não depende de a aplicação entregar os links na hora certa. Dois cuidados: a ordem só vale quando algum signatário tem order maior que 1, e duas pessoas não podem assinar o mesmo envelope no mesmo instante — a segunda recebe "Outra pessoa está assinando este documento. Tente de novo em instantes." e tenta de novo.
Mercado e diferenciais
negócioPanorama: três camadas, e nós não estamos em nenhuma delas
Panorama. O mercado de assinatura eletrônica tem três camadas. No topo, plataformas internacionais — DocuSign, Adobe Acrobat Sign, Dropbox Sign — que cobram por usuário emissor com franquia de envelopes e vendem alcance, integrações e certificado de conclusão. No meio, os brasileiros — Clicksign, D4Sign, ZapSign, Autentique — que cobram por volume de documentos, entendem o marco legal local e, em parte deles, suportam certificado ICP-Brasil. Embaixo, soluções abertas auto-hospedáveis, como o OpenSign.
Todos são provedores. O E-Signature da Catalisa não é: ele é a camada que fica entre a sua aplicação e o provedor, para que a escolha do provedor não seja uma decisão de arquitetura irreversível. A comparação abaixo é honesta sobre essa diferença de natureza.
flowchart TD
App["Sua aplicação"] --> Cat["Catalisa E-Signature<br/>camada de orquestração — não assina nada"]
Cat --> Int["Camada 1 — internacionais<br/>DocuSign · Adobe Acrobat Sign · Dropbox Sign<br/>cobram por usuário emissor, com franquia de envelopes"]
Cat --> Br["Camada 2 — brasileiros<br/>Clicksign · D4Sign · ZapSign · Autentique<br/>cobram por volume de documentos, marco legal local"]
Cat --> Open["Camada 3 — abertos e auto-hospedáveis<br/>OpenSign<br/>sem custo por documento, você opera a instância"]
Int -.->|não implementado| X1["§15"]
Br -.->|não implementado| X1
Open ==>|único implementado hoje| X2["§15"]O comparativo, critério a critério
| Critério | Catalisa E-Signature | DocuSign | Clicksign | D4Sign | ZapSign | Autentique | OpenSign |
|---|---|---|---|---|---|---|---|
| Natureza | Camada de orquestração | Provedor | Provedor | Provedor | Provedor | Provedor | Provedor auto-hospedável |
| Assina documentos | Não — delega ao provedor | Sim | Sim | Sim | Sim | Sim | Sim |
| Entrada publicada (2026-08-16) | Em definição | R$ 45/mês | R$ 39/mês | R$ 39,90/mês | Grátis até 3 docs; R$ 39,90/mês | Grátis até 10 docs; R$ 99/mês | Sem custo por documento |
| Preço de API público | — | R$ 2.560 a R$ 24.520/ano | Incluso desde o plano de entrada | Não publicado | A partir do plano intermediário | Tarifa por evento publicada em reais | — |
| Certificado ICP-Brasil | Depende do provedor | Sim, mas só nos planos sob cotação | Sim | Sim | É AC credenciada pelo ITI | Sim — A1, A3 e nuvem | Não |
| Nível da Lei 14.063 que declara produzir | O do provedor configurado | Não declara por plano | Alega cobrir os três | Não declara | Não declara | Declara avançada (art. 4º, II) | Não declara — o código indica simples |
| Troca de provedor sem reescrever | Sim, é o ponto | Não se aplica | Não se aplica | Não se aplica | Não se aplica | Não se aplica | Não se aplica |
| Credencial isolada por cliente | Sim, cifrada por organização | Você implementa | Você implementa | Você implementa | Você implementa | Você implementa | Você implementa |
| Estado por signatário | Sim, tabela própria | Sim | Sim | Sim | Sim | Sim | Sim |
| Documento fica na sua infraestrutura | Sim, se o provedor for auto-hospedado | Não | Não | Não | Não | Não | Sim |
| Assinatura de webhook verificável | Depende do provedor (§15) | Sim | Sim, HMAC | Não documentado | Sim | Sim | Não |
Preços consultados nas páginas oficiais em 2026-08-16: DocuSign, Clicksign, D4Sign, ZapSign e Autentique. Variam por faixa de volume e por negociação — confira na data da sua análise. O Dropbox Sign publica preço apenas em dólar e não localizamos nenhuma menção a ICP-Brasil nas páginas dele. A Adobe reconhece a raiz do ITI na sua lista de confiança, mas não publica preço de API nem documenta fluxo específico de ICP-Brasil. Onde escrevemos "não declara", significa que o fornecedor explica os níveis da lei mas não afirma qual deles produz.
Um detalhe que vale para quem compra
Um detalhe que vale para quem compra. Ao avaliar material jurídico de fornecedor, confira as citações. Verificando contra o texto do Planalto em 2026-08-16, encontramos duas imprecisões públicas: a Autentique cita "art. 4º, I" ao descrever a assinatura qualificada — no texto legal, o inciso I é a simples e a qualificada é o III —, e a D4Sign escreve "Lei 14.603/2020" onde a norma é a 14.063/2020. Não são erros graves, mas são o tipo de coisa que o jurídico do seu cliente vai notar, e é por isso que nesta documentação cada citação legal traz artigo e link.
Nossos diferenciais
Nossos diferenciais
- A escolha do provedor deixa de ser irreversível. A interface canônica tem oito métodos e todos os serviços falam com ela, nunca com o provedor. Isso é difícil de copiar não pela mecânica, mas porque exige ter resistido, desde o primeiro dia, à tentação de deixar o vocabulário do fornecedor vazar para dentro do domínio.
- A credencial é do tenant, cifrada, e nunca volta. Cada organização configura a própria conta no provedor, cifrada com AES-256-GCM. A função que monta a resposta simplesmente não inclui o campo de credenciais — não há caminho de serialização que vaze.
- Envelope e signatário têm estados independentes.
SignatureRequesttem oito estados;Signertem cinco. Isso permite o estado intermediárioPARTIALLY_SIGNED, que é onde a maioria dos contratos de crédito com avalista realmente vive. - O documento pode nunca sair da plataforma. Com
fileId, o arquivo vem do file-storage; com um provedor auto-hospedado, ele não sai da sua infraestrutura em momento algum. Em provedor de nuvem, isso é impossível por construção.
Quando escolher o concorrente
flowchart TD
Q1{"O ato exige assinatura qualificada<br/>com certificado ICP-Brasil?"}
Q1 -->|sim| C1["Contrate direto: Clicksign, D4Sign,<br/>ZapSign ou Autentique.<br/>A ZapSign é AC credenciada pelo ITI"]
Q1 -->|não| Q2{"Precisa de alcance internacional e<br/>certificado de conclusão em outra jurisdição?"}
Q2 -->|sim| C2["DocuSign"]
Q2 -->|não| Q3{"Quer começar amanhã,<br/>sem construir nada?"}
Q3 -->|sim| C3["Faixa gratuita da ZapSign ou do Autentique.<br/>Este building block sozinho não assina nada"]
Q3 -->|não| Q4{"Quantos contratos por mês?"}
Q4 -->|"meia dúzia"| C4["A camada de abstração é custo sem benefício"]
Q4 -->|"volume, com muitos clientes<br/>e um provedor por cliente"| C5["Catalisa E-Signature"]Quando escolher o concorrente. Se você precisa de assinatura qualificada com certificado ICP-Brasil — porque o ato exige, ou porque o seu jurídico exige —, contrate Clicksign, D4Sign, ZapSign ou Autentique diretamente: os quatro suportam certificado ICP-Brasil e o OpenSign não. A ZapSign, inclusive, é autoridade certificadora credenciada pelo ITI. Se o requisito é alcance internacional e certificado de conclusão que sobreviva a uma disputa em outra jurisdição, o DocuSign é a escolha estabelecida. Se você quer começar amanhã, com o menor esforço e sem construir nada, a faixa gratuita da ZapSign ou do Autentique resolve hoje, e este building block sozinho não assina nada. E se a sua operação envia meia dúzia de contratos por mês, a camada de abstração aqui é custo sem benefício.
O E-Signature ganha quando o problema é muitos clientes, cada um com o próprio provedor e a própria credencial, e uma integração que não pode ser refeita a cada renegociação de contrato — não quando o problema é assinar um documento.
Sobre a licença do OpenSign, e isto precisa ser dito
Sobre a licença do OpenSign, e isto precisa ser dito. O projeto se declara sob AGPL-3, mas o arquivo de licença tem uma exceção para o diretório customRoute, cuja licença remete a um arquivo que não existe naquele diretório — e é por isso que o GitHub classifica o repositório como NOASSERTION em vez de AGPL-3.0 (verificado em 2026-08-16). Some-se a isso que a própria AGPL-3 exige disponibilizar o código-fonte a quem interage com o software pela rede, o que é material para uma plataforma multi-tenant. Não use o OpenSign em produto comercial sem análise jurídica da licença. Registramos isso aqui porque é o tipo de risco que aparece tarde e caro.
Modelo de cobrança e ROI
negócioQuem cobra o quê nesta cadeia
flowchart LR
Cli["Cliente"] -->|"contrato Catalisa — precificação em definição"| Cat["Catalisa E-Signature<br/>orquestra"]
Cli -->|"contrato direto, sem intermediação da Catalisa"| Prov["Provedor de assinatura<br/>assina"]
Cat -.->|"usa a credencial do cliente"| Prov
Prov -->|"cobra por documento, por usuário<br/>ou só infraestrutura, se auto-hospedado"| CliPrecificação em definição
Precificação em definição. O E-Signature não tem preço fechado. Ele é a camada de orquestração de uma cadeia — geração, assinatura e leitura de documento — e a intenção é que acompanhe a contratação do conjunto. Não há valor a divulgar e este documento não estima nenhum.
O custo que não é nosso
O custo que não é nosso. O custo da assinatura em si é do provedor que você contratar, e vai direto para você. Essa separação é deliberada e é boa para o cliente: a Catalisa não intermedia a relação comercial com o provedor, não estende linha de crédito e não embute margem no preço por documento. Se você escolher um provedor auto-hospedado, esse custo é apenas infraestrutura.
O que dispara custo
O que dispara custo.
| Driver | Por quê |
|---|---|
| Solicitações de assinatura criadas | Cada uma envolve upload do documento ao provedor, criação de contatos e gravação de envelope, signatários e documentos |
| Número de signatários por solicitação | O provedor cria um contato e um conjunto de campos por signatário, e a maioria cobra por isso |
| Tamanho do documento | O arquivo é carregado em memória em base64 antes de subir ao provedor |
| Consultas de estado | Enquanto o webhook não estiver funcional (§15), acompanhar estado exige consulta ativa |
Comparação de custo em cenário nomeado
Comparação de custo — cenário nomeado: financeira que coleta assinatura em 400 contratos por mês, com dois signatários cada, e opera com três pessoas no time que dispara e acompanha.
| Catalisa + OpenSign auto-hospedado | DocuSign | Clicksign | ZapSign | Autentique | |
|---|---|---|---|---|---|
| Base de cálculo | Precificação em definição; sem custo por documento | Por usuário emissor, mais franquia de envio por API | Por faixa de documentos, com excedente | Por faixa, com faixa gratuita e recursos avulsos | Documentos ilimitados no plano profissional |
| Ordem de grandeza mensal do provedor | Só a infraestrutura da instância | Centenas de reais por usuário, mais contrato de API a partir de R$ 2.560/ano | Dezenas a centenas de reais, conforme a faixa | Dezenas de reais, mais avulsos por recurso | R$ 99/mês, mais eventos avulsos |
| Custo por documento excedente | Zero | Consumo de franquia | R$ 2,40 a R$ 6,90 | Conforme plano | Tarifa por evento publicada |
| ICP-Brasil disponível | Não | Sim, sob cotação | Sim | Sim | Sim |
| Você opera o provedor | Sim | Não | Não | Não | Não |
Preços dos fornecedores consultados em 2026-08-16 nas páginas citadas na §5. A coluna da Catalisa não é comparável linha a linha: o building block não substitui o provedor, ele o orquestra. Se você escolher um provedor comercial, o custo dele continua existindo.
ROI
ROI. A conta de guardanapo tem duas linhas.
| Linha da conta | O que se ganha | O que ressalvar |
|---|---|---|
| Tempo entre aprovar e liquidar | Dias viram horas; o ganho é proporcional ao ticket, não ao número de contratos | Depende de o acompanhamento funcionar — hoje o webhook não está funcional (§15) |
| Custo de troca de fornecedor | A troca vira configuração, e o poder de negociação deixa de ser todo do fornecedor | Valor arquitetural ainda não realizado: não existe uma segunda implementação de provedor (§15) |
A primeira é o tempo entre aprovar e liquidar. Numa operação de crédito, cada dia de contrato não assinado é capital parado e é probabilidade de desistência. Substituir e-mail com anexo por solicitação rastreável costuma cortar esse intervalo de dias para horas — e o ganho é proporcional ao ticket, não ao número de contratos.
A segunda é o custo de troca de fornecedor. Com integração específica, a alternativa a aceitar um reajuste é um projeto de meses; na prática, o fornecedor sabe disso e o poder de negociação é dele. Com a camada de abstração, a troca é uma configuração — desde que exista uma segunda implementação de provedor, que hoje não existe (§15). É um valor arquitetural real e ainda não realizado, e é assim que ele deve ser apresentado a cliente.
Arquitetura
As camadas e o caminho da requisição
flowchart TD
HTTP["HTTP — Bearer JWT emitido pelo IAM"]
subgraph App["Hono app · basePath /e-signature · applyCommonMiddleware"]
R1["/api/v1/esignature/provider-configs<br/>providerConfigRouter — 7 rotas"]
R2["/api/v1/esignature/requests<br/>signatureRequestRouter — 8 rotas"]
R3["/api/v1/esignature/webhooks<br/>webhookRouter — 1 rota, pública"]
R4["/health<br/>sonda pública"]
end
subgraph Svc["services/"]
SV1["ProviderConfigService<br/>CRUD da configuração e testar conexão"]
SV2["SignatureRequestService<br/>criar · cancelar · reenviar · baixar"]
SV3["WebhookHandlerService<br/>verificar → registrar → aplicar estado"]
end
subgraph Fab["providers/ · createESignatureProvider por providerType"]
P1["OPENSIGN — implementado<br/>OpenSignProvider sobre Parse REST"]
P2["DOCUSIGN — recusa com INTERNAL not yet implemented"]
P3["ADOBESIGN — idem"]
P4["ZAPSIGN — idem"]
end
Repo["repositories/ — 4, via Prisma<br/>PostgreSQL, schema esignature"]
Cripto["utils/crypto — AES-256-GCM<br/>ESIGNATURE_CREDENTIAL_MASTER_KEY<br/>formato iv:authTag:ciphertext"]
Bucket["S3 ou MinIO — file-storage"]
OS["Instância OpenSign<br/>Parse Server REST API"]
HTTP --> App
App -->|"Zod parse, ResultAsync e handleResult"| Svc
Svc --> Repo
Svc --> Cripto
Cripto -->|"decifra em memória"| Fab
Svc -->|"resolve fileId por URL assinada"| Bucket
Fab -->|HTTPS| OS
OS -->|"webhook do provedor"| R3Caminho de uma solicitação de assinatura
Caminho de uma solicitação de assinatura
flowchart TD
A["POST /requests<br/>title, fileId ou fileBase64, signers, widgets opcionais"] --> B{"configId informado?"}
B -->|sim| C["usa a configuração indicada"]
B -->|não| D["busca a padrão da organização<br/>isDefault e isActive"]
D --> E{"encontrou alguma?"}
E -->|não| F["404 ProviderConfig"]
E -->|sim| G
C --> G{"origem do arquivo"}
G -->|fileId| H["URL assinada no S3 → download → base64 em memória"]
G -->|fileBase64| I["usa direto"]
H --> J["decifra as credenciais com a chave mestra"]
I --> J
J --> K{"providerType implementado?"}
K -->|não| L["500 INTERNAL — not yet implemented"]
K -->|sim| M["provider.createSignatureRequest"]
M --> N["No OpenSign local: conta da organização no motor → upload do PDF<br/>→ um contato por signatário, por documento → um campo<br/>de assinatura por signatário (padrão: última página) → cria o documento"]
N --> O["Grava na mesma transação:<br/>SignatureRequest + Signer + SignatureDocument"]
O --> P["Publica esignature.request.created"]
P --> Q["201 com o envelope e os signatários"]O fluxo de assinatura ponta a ponta: criar, enviar, assinar, selar
O diagrama acima para na criação. Este continua a história até o documento selado voltar para você — e mostra, em cada troca, quem depende de quem.
sequenceDiagram
autonumber
participant App as Sua aplicação
participant ES as E-Signature
participant S3 as file-storage — S3 ou MinIO
participant Prov as Provedor de assinatura
participant Sig as Signatário
rect rgb(240, 245, 255)
Note over App,Prov: 1. Criar
App->>ES: POST /requests com fileId e signers
ES->>S3: URL assinada e download do arquivo
S3-->>ES: PDF convertido em base64 em memória
ES->>ES: decifra as credenciais do tenant em AES-256-GCM
ES->>Prov: cria o documento, os contatos e os campos de assinatura
Prov-->>ES: externalId, viewUrl e signingUrl por signatário
ES-->>App: 201 com o envelope gravado em DRAFT ou SENT
end
rect rgb(245, 250, 240)
Note over Prov,Sig: 2. Enviar ao signatário
Prov->>Sig: e-mail com o link individual de assinatura
Sig->>Prov: abre o documento
Prov->>ES: webhook viewed
ES->>ES: envelope de SENT ou DRAFT para VIEWED, signatário para VIEWED
end
rect rgb(255, 248, 240)
Note over Sig,ES: 3. Assinar
Sig->>Prov: assina
Prov->>ES: webhook signed
alt todos os signatários assinaram
ES->>ES: envelope para COMPLETED e completedAt preenchido
else ainda falta alguém
ES->>ES: envelope para PARTIALLY_SIGNED
end
end
rect rgb(250, 240, 245)
Note over Prov,App: 4. Selar e devolver
Prov->>Prov: sela o PDF com o certificado do servidor e calcula o hash SHA-256
App->>ES: GET /requests/:id/download
ES->>ES: recusa com VALIDATION se o envelope não estiver COMPLETED
ES->>Prov: pede a URL do documento assinado
Prov-->>ES: downloadUrl temporária
ES-->>App: downloadUrl e expiresAt — sem proxy do binário
endAtenção. Os passos 2, 3 e o webhook do passo 4 dependem da rota de webhook,
que não está funcional hoje (§15). Na prática, o envelope permanece no estado
gravado na criação até que alguém o atualize, e o selo e o hash do passo 4 ficam
apenas do lado do provedor (§14).
Decisões não óbvias
Decisões não óbvias.
- A credencial é cifrada por organização, não configurada por ambiente. É o que torna o building block multi-tenant de verdade: cada cliente conecta a própria conta no provedor. O
ESIGNATURE_CREDENTIAL_MASTER_KEYé apenas a chave de cifragem, comum ao serviço. O trade-off é que ela vira ativo crítico — vazá-la expõe as credenciais de todos os tenants —, e por isso é validada como 64 caracteres hexadecimais e deve ficar em SOPS. - A verificação da assinatura do webhook é fail-closed, mas o provedor não a oferece. Desde a correção do incidente em que todos os
verifyWebhookSignatureretornavamtrueincondicionalmente, um resultado inválido interrompe o processamento. O OpenSign, porém, não tem esquema de assinatura de webhook, e o provider registra isso explicitamente. O comportamento passa a depender dePROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT: comoff(padrão), o webhook é aceito e um aviso é registrado; comon, ele é recusado. Não há terceira opção enquanto o provedor não oferecer assinatura — a mitigação correta é lista de IPs permitidos na borda. - Criar a configuração não testa a conexão. O
ProviderConfigService.createcifra e grava sem chamar o provedor. Uma credencial errada, ou umproviderTypenão implementado, é aceita e só falha na primeira solicitação real. ExistePOST /provider-configs/:id/testexatamente para isso — use-o depois de criar, sempre. - Cancelar, no OpenSign local, é recusar e marcar revogado. O motor não tem estado de cancelamento; o provider grava
IsDeclined=trueeRevokedAtno documento (osignPdfdo motor recusa documento recusado), e o mapper lêRevokedAtcomoCANCELLED. Documento já concluído não é revogável (409); documento inexistente no motor conta como já cancelado. - O OpenSign local não reenvia nada. Ele não manda e-mail (SMTP desligado) e o signatário assina na página do bloco;
POST /requests/:id/resendresponde400para OpenSign. Reemitir o acesso do signatário é com a página de assinatura. - O download do OpenSign local vem do file-storage do bloco. As URLs do motor são internas, exigem o portão e expiram em minutos; por isso, ao concluir, o bloco arquiva o PDF selado e o certificado no file-storage (
signature_documents.signed_file_id/certificate_file_id) eGET /requests/:id/downloaddevolve a URL assinada dessa cópia. Para os outros provedores, segue devolvendo a URL do provedor. - O arquivo por
fileIdpassa inteiro pela memória. O serviço gera a URL assinada no S3, baixa e converte em base64 antes de subir ao provedor. Para contrato de poucas páginas é irrelevante; para documento grande, é o ponto de pressão de memória do serviço.
OpenSign local: o motor por trás da página de assinatura
O OpenSign roda sem app web, como motor (imagem docker/opensign do repositório do painel),
atrás de um portão: toda chamada leva o segredo do portão, X-Parse-Application-Id e
X-Parse-Master-Key; sem o portão, 403. O signatário assina numa página nossa; quem aplica a
assinatura é o SignatureApplierService (interface SignatureApplier, em
services/signature-applier.ts):
- recusa o que não pode ser assinado e publica
esignature.signature.refusedcom o motivo: imagem que não é PNG ou que declara no IHDR mais de 2000×1000 (IMAGE_TOO_LARGE, lido antes de qualquer decodificador), signatário que já assinou, envelope fechado, signatário fora da ordem (OUT_OF_ORDER, quando algum signatário temorder> 1), provedor sem a capacidade; - trava o envelope no Redis (
esignature:signing:<id>) só no trecho do motor (baixar → desenhar →signPdf): dois signatários ao mesmo tempo são serializados e nenhum sobrescreve o PDF do outro. A trava tem heartbeat, e liberar e estender comparam o token (Lua): quem perdeu a trava por TTL nunca apaga a de outro; - dentro da trava, relê o envelope e o signatário: se o envelope ficou
DECLINED,CANCELLED,EXPIREDouCOMPLETEDenquanto a chamada esperava, recusa com o motivo (REQUEST_DECLINED…);PARTIALLY_SIGNEDeCOMPLETEDsó são gravados a partir de um status aberto (update condicional) — uma recusa que chega durante a chamada ao motor nunca é sobrescrita; - o signatário passa a
SIGNING; o bloco baixa o PDF atual, desenha o PNG no campo dele com pdf-lib e carimba no rodapé nome, data (UTC), IP (validado) e o SHA-256 do original; chamafunctions/signPdfcomX-Signer-Ip(só um endereço IP literal — sem ele, a trilha gravaria o endereço do portão). Se osignPdffalhar ou estourar o tempo, o bloco não conclui "não assinou": relê o documento até ver a entradaSigneddo signatário ou o prazo vencer. Viu →SIGNED(reconciliado); confirmou que não → volta ao estado anterior; não conseguiu ler o motor → ficaSIGNING(503,SIGNATURE_UNCONFIRMED) e a próxima tentativa ou orefreshreconcilia; - no último signatário o motor sela o PDF (PKCS#7,
/ByteRange) e gera o certificado em seguida (assíncrono, ~2 s; o bloco espera atésettings.certificateTimeoutMs, padrão 30 s, teto 60 s). O bloco arquiva os dois no file-storage;COMPLETEDé reivindicado por update condicional (status != COMPLETED), entãoesignature.request.completedsai uma vez mesmo com a página e orefreshconcorrendo; a evidência — só depois que o certificado está arquivado — também é reivindicada e capturada uma vez, sobre os bytes já baixados: hash do original, do PDF selado e do certificado, o hash que o próprio motor gravou e o IP de cada signatário.
O motivo de cada recusa é estruturado. Todo erro do applySignature traz
appError.details.reason (tipo SignatureRefusalReason, em services/signature-applier.ts), para a
página mostrar a mensagem certa sem ler texto:
reason | Quando |
|---|---|
INVALID_IMAGE / IMAGE_TOO_LARGE | Não é PNG / IHDR acima de 2000×1000 ou mais de 1 MB |
REQUEST_NOT_FOUND / SIGNER_NOT_FOUND / SIGNER_NOT_IN_PROVIDER | Envelope ou signatário inexistente, ou sem referência no motor |
ALREADY_SIGNED / SIGNER_DECLINED | O signatário já assinou / recusou |
REQUEST_COMPLETED / REQUEST_CANCELLED / REQUEST_DECLINED / REQUEST_EXPIRED | Envelope fechado |
OUT_OF_ORDER | Envelope em ordem e alguém antes ainda não assinou |
BUSY | Outra assinatura do mesmo envelope em andamento — tente de novo em segundos |
PROVIDER_UNSUPPORTED / PROVIDER_UNAVAILABLE | A configuração não serve para assinar pela página |
PROVIDER_CONFLICT / PROVIDER_NOT_FOUND / PROVIDER_VALIDATION | O motor recusou |
SIGNATURE_UNCONFIRMED | Falha: o motor não pôde ser relido; o signatário fica SIGNING e a nova tentativa reconcilia |
ENGINE_FAILED | Falha: o motor ou o bloco falhou e o motor confirmou que não tem a assinatura |
SIGNING é um estado do signatário (Signer.status, enum SignerStatus): a assinatura foi
mandada ao motor e ainda não foi confirmada. A página trata como "processando"; uma nova chamada
do mesmo signatário é permitida e reconcilia.
Falha do motor publica esignature.signature.failed; falha ao arquivar,
esignature.request.archive_failed. O motor não tem webhook: POST /requests/:id/refresh relê o
documento e, se ele estiver concluído, arquiva e captura a evidência do mesmo jeito (idempotente).
COMPLETED vem só de IsCompleted=true — o motor não grava Status.
Limites. PDF de até 500 páginas e fileBase64 de até ~15 MB; download do motor cortado em
50 MB durante a leitura; campos de assinatura com largura e altura positivas, até 400×200 pontos e
dentro da página; e-mail repetido entre signatários é recusado na criação. Erro do motor nunca ecoa
o corpo dele: a mensagem traz só o status HTTP e o código do Parse.
Formato antigo da lista. Uma entrada host:porta sem esquema (o formato de antes) não casa com
motor nenhum: o boot loga um aviso nomeando as entradas e a correção (http://host:porta; com mTLS, use https://host:porta), e
POST /provider-configs/:id/test responde success: false com a mensagem e
code: ALLOWLIST_LEGACY_FORMAT (ou ENGINE_NOT_ALLOWED), em vez de um 400 seco.
O host do motor é lista fechada. OPENSIGN_ALLOWED_HOSTS diz onde o motor pode estar
(scheme://host:porta, ou hostname nu para https na porta padrão; http só com porta explícita);
uma configuração com baseUrl fora da lista é recusada, e os arquivos do motor são sempre baixados do
nosso baseUrl (o host que o motor devolve na URL é descartado).
Janela residual do SIGNING. O signPdf tem 30 s de tempo limite e a releitura depois dele, 45 s.
Se o motor gravar a assinatura depois desses ~75 s, o bloco já terá devolvido o signatário ao
estado anterior (ou deixado em SIGNING, se não conseguiu ler o motor). Não há dupla assinatura —
uma nova tentativa encontra a entrada Signed e reconcilia, e o refresh também —, mas até lá o
nosso banco mostra o signatário como não assinado. Um SIGNING preso volta a SENT no refresh (por update condicional: ainda SIGNING e com
updatedAt mais antigo que o limite, no próprio WHERE; se o motor disser DECLINED, vale o do motor)
só quando o motor responde sem a assinatura dele, ninguém segura a trava do envelope e ele está em
SIGNING há mais de 10 minutos. A evidência segue a mesma ideia: uma reivindicação com mais de
5 minutos e sem hash (réplica morta no meio da captura) pode ser reivindicada de novo.
Rotação do token do portão (gateToken). O token vale num lado só (o Caddy do motor aceita um
valor por vez), então a rotação tem uma janela curta: (1) gere o novo token e suba o motor com ele
(pelo roteiro de deploy do motor, no repo do painel); (2) o instalador do painel
reescreve as credentials de cada configuração OPENSIGN com o novo valor
(PATCH /provider-configs/:id, a cada instalação); (3) confira com POST /provider-configs/:id/test.
Assinaturas que caírem na janela recebem 403 → esignature.signature.failed, e o signatário tenta de
novo. Faça fora do horário de uso. A master key segue o mesmo caminho.
Uma conta por organização. Na primeira solicitação, o bloco cria (ou reencontra, pelo e-mail
esignature+<organizationId>@catalisa.io) o contracts_Users técnico da organização e guarda o
objectId em settings.extUserId da configuração. Esses dois campos (extUserId,
extUserOrganizationId) só o bloco grava: o que o cliente manda neles na criação ou na
atualização da configuração é ignorado, e todo documento lido do motor é conferido contra esse dono
(de outro dono → 404). Duas réplicas criando ao mesmo tempo convergem para o mais antigo. Os
contatos dos signatários são criados por documento, nunca reaproveitados por e-mail.
Monolito vs. standalone. O app.ts é montado no monolito em src/app.ts e responde em http://localhost:3000/e-signature. O main.ts sobe o mesmo app com Bun.serve na porta 3014 quando DEPLOYMENT_MODE=standalone, que é o modo usado em staging e produção. Não há diferença de comportamento entre os modos. O que muda é que, em standalone, applyCommonMiddleware é a única fonte de limite de corpo, CORS, cabeçalhos de segurança e limite de taxa.
Onde o motor roda: rede interna e TLS mútuo
O motor opensign-local é um serviço da plataforma, no projeto dos blocos, sem rota pública: o motor só é alcançável pela rede interna da plataforma e exige certificado de cliente emitido pela nossa CA mais um segredo de portão. A imagem e o roteiro de deploy do motor ficam no repositório do painel.
Dentro do container há quatro peças, e só uma escuta fora do loopback:
flowchart LR
B["bb-e-signature<br/>certificado de cliente"]
subgraph M["Container opensign-local"]
C["Caddy<br/>TLS 1.2/1.3, exige cert da nossa CA"]
G{"Segredo do portão<br/>confere?"}
O["OpenSign / Parse<br/>só loopback"]
D[("Mongo local<br/>volume persistente")]
end
B -->|"mTLS pela rede interna"| C
C --> G
G -->|"não: 403"| X["recusado"]
G -->|"sim"| O
O --> D- Caddy termina o TLS com
client_auth require_and_verifycontra a nossa CA. Sem certificado de cliente, o handshake falha antes de qualquer HTTP. - Portão. Mesmo com certificado, sem o segredo do portão a resposta é
403. - OpenSign (Parse) só no loopback e Mongo local (com journal) em volume persistente. A master key só é aceita do loopback (
masterKeyIps). O carimbo do PDF diz "Catalisa". - IP do signatário. O bloco manda
X-Signer-Ip; o Caddy o repassa comoX-Forwarded-For, e a trilha do motor grava o IP de quem assinou — não o do portão.
Por que TLS mútuo, e não lista de IPs. No runtime de containers da plataforma, toda conexão chega ao motor com a mesma origem, a do proxy de portas: uma allowlist por origem é impossível. "Sem domínio público" também não basta como tranca. O certificado de cliente mais o segredo do portão são a tranca.
PKI. O roteiro de emissão de TLS do motor (repo do painel) gera, por ambiente, uma CA EC P-256 própria, o certificado do servidor (SAN = host interno do motor) e o de cliente (CN=bb-e-signature, clientAuth). A chave da CA nunca sai da máquina do operador que emitiu os certificados. O script reemite o certificado de servidor quando o SAN muda e avisa vencimento em menos de 30 dias. O bloco recebe a CA e o par de cliente pelas três OPENSIGN_TLS_* (§13) e fixa a CA: o pool do sistema deixa de valer para o motor. O painel não precisa de nada disso — só o bloco fala com o motor.
Conferir assinatura de arquivo
flowchart TD
In["POST /verifications<br/>multipart file ou JSON fileId"] --> Sz{"tamanho e tipo pelo conteúdo"}
Sz -->|"fora"| Rf["recusa + esignature.verification.refused"]
Sz --> Dt{"assinatura destacada sem o conteúdo?"}
Dt -->|sim| Rf
Dt -->|não| Cs{"organização ligou o envio a terceiro?<br/>padrão da casa: desligado"}
Cs -->|não| Rf
Cs -->|sim| Id{"mesmo SHA-256 conferido na janela?"}
Id -->|sim| Ru["devolve a anterior + .reused"]
Id -->|não| Lk["trava por arquivo no Redis"]
Lk --> Pv["SignatureVerificationProvider<br/>ITI_VERIFIER: POST /report"]
Pv -->|"Aprovado"| V["VALID"]
Pv -->|"Reprovado ou Inválido"| I["INVALID"]
Pv -->|"Indeterminado, tempo, erro, fora do ar"| N["INDETERMINATE com motivo estável"]
V --> Sv["cópia temporária no file-storage<br/>linha em signature_verifications<br/>esignature.verification.completed na trilha"]
I --> Sv
N --> SvDecisões não óbvias da conferência.
- A interface de verificação é separada da de assinatura.
SignatureVerificationProvider(emverifiers/) não conhece envelope nem signatário;ESignatureProvidernão conhece conferência. Um driver local (cadeia ICP-Brasil validada por nós) entra declarandosendsFileToThirdParty = false. - O verificador é infraestrutura da plataforma, não credencial do tenant. Não há segredo a guardar por organização; o que é por organização é o consentimento de enviar o arquivo a ele.
- A prova mora na trilha, não na tabela. O id de recurso da linha é derivado do hash do arquivo (
fileResourceId), para que a prova por hash não dependa de nenhuma tabela do bloco. - Falha do provedor é resultado, não erro. Tempo esgotado ou verificador fora do ar concluem a conferência como
INDETERMINATE, gravada e auditada; só a recusa antes de chamar o provedor volta como erro HTTP.
Conceitos e modelo de dados
Glossário
| Termo | Significa |
|---|---|
| Solicitação de assinatura (envelope) | A unidade de trabalho: um documento, um conjunto de signatários e um estado. Corresponde ao modelo SignatureRequest. |
| Signatário | Uma pessoa que precisa assinar, com nome, e-mail, ordem e estado próprio. Corresponde ao modelo Signer. |
Ordem (order) | Inteiro a partir de 1. Quando algum signatário tem ordem maior que 1, a solicitação é criada no provedor em modo sequencial. |
Campo de assinatura (widget) | Onde, na página, o signatário assina ou preenche. Tipo (signature, text, date, checkbox), página e coordenadas. Sem widgets, o building block posiciona um campo de assinatura por signatário na primeira página. |
| Configuração de provedor | O provedor escolhido pela organização e suas credenciais cifradas. Uma delas é a padrão. |
externalId | O identificador do recurso no provedor. É por ele que o webhook reencontra a solicitação. Único em conjunto com a configuração. |
businessId | Identificador livre da operação de origem — proposta, contrato, pedido. É o campo de correlação com os outros building blocks. |
| Chave mestra de credenciais | ESIGNATURE_CREDENTIAL_MASTER_KEY. Chave AES-256-GCM de 32 bytes, informada como 64 caracteres hexadecimais, usada para cifrar as credenciais de todos os tenants. |
| Assinatura eletrônica simples | Na classificação da Lei nº 14.063/2020, o nível que permite identificar o signatário e anexar dados ao documento, sem exigir certificado. É o nível que o provedor implementado hoje entrega — ver §14. |
| OpenSign | Plataforma de assinatura de código aberto, auto-hospedável, construída sobre Parse Server. É o único provedor implementado. |
Modelo de dados — schema esignature no PostgreSQL. 5 modelos.
| Modelo Prisma | Tabela | Propósito | Campos-chave |
|---|---|---|---|
ESignatureProviderConfig | esignature_provider_configs | Provedor e credenciais da organização | Único (organizationId, name), providerType, credentials (cifrado), isDefault, isActive, settings, deletedAt |
SignatureRequest | signature_requests | O envelope | Único (configId, externalId), title, status, businessId, templateId, viewUrl, expiresAt, completedAt, deletedAt; evidência: documentHash, hashAlgorithm, signatureLevel (SIMPLE · ADVANCED · QUALIFIED, Lei 14.063), evidence (JSON do provedor: fonte, certificado, signatários com IP), evidenceCapturedAt |
Signer | signers | Um signatário do envelope | externalId, email, order, status, signingUrl, sentAt, viewedAt, signedAt, declinedAt, declineReason |
SignatureDocument | signature_documents | O arquivo vinculado ao envelope | externalId, fileId, originalUrl, signedUrl, signedUrlExpiresAt |
ESignatureWebhookEvent | esignature_webhook_events | Todo webhook recebido, cru | eventType, externalEventId, payload, processed, processedAt, error |
erDiagram
ORGANIZATION ||--o{ ESIGNATURE_PROVIDER_CONFIG : "configura"
ESIGNATURE_PROVIDER_CONFIG ||--o{ SIGNATURE_REQUEST : "atende"
ESIGNATURE_PROVIDER_CONFIG ||--o{ ESIGNATURE_WEBHOOK_EVENT : "recebe por"
SIGNATURE_REQUEST ||--o{ SIGNER : "tem, em cascata"
SIGNATURE_REQUEST ||--o{ SIGNATURE_DOCUMENT : "tem, em cascata"
SIGNATURE_REQUEST ||--o{ ESIGNATURE_WEBHOOK_EVENT : "é atualizada por"
ESIGNATURE_PROVIDER_CONFIG {
uuid id PK
uuid organization_id "isolamento do tenant"
string name "único junto com organization_id"
enum provider_type "OPENSIGN DOCUSIGN ADOBESIGN ZAPSIGN"
text credentials "cifrado em AES-256-GCM, nunca retornado"
boolean is_default
boolean is_active
jsonb settings
timestamp deleted_at "exclusão lógica"
}
SIGNATURE_REQUEST {
uuid id PK
uuid organization_id "isolamento do tenant"
uuid config_id FK
string external_id "id no provedor, único junto com config_id"
string title
text message
enum status "8 estados — ver máquina abaixo"
string business_id "correlação com a operação de origem"
string template_id "template do PROVEDOR, não do document-template"
string template_name
text view_url
timestamp expires_at
timestamp completed_at
timestamp deleted_at "exclusão lógica"
}
SIGNER {
uuid id PK
uuid request_id FK
string external_id "id do contato no provedor"
string name
string email "chave de correlação com os eventos do provedor"
int order "1 por padrão; maior que 1 ativa modo sequencial"
enum status "PENDING SENT VIEWED SIGNED DECLINED"
text signing_url "URL com poder — trate como segredo"
timestamp sent_at
timestamp viewed_at
timestamp signed_at
timestamp declined_at
text decline_reason
}
SIGNATURE_DOCUMENT {
uuid id PK
uuid request_id FK
string external_id
string name
uuid file_id "aponta para o file-storage"
text original_url
text signed_url
timestamp signed_url_expires_at
}
ESIGNATURE_WEBHOOK_EVENT {
uuid id PK
uuid organization_id
uuid config_id FK
uuid request_id FK "nulo quando o evento não casa com envelope"
string event_type "viewed signed completed declined"
string external_event_id
jsonb payload "corpo original, sempre gravado"
boolean processed
timestamp processed_at
text error "motivo da falha de processamento"
}Configurações, solicitações e eventos de webhook são isolados por organizationId. Signatários e documentos herdam o isolamento da solicitação e são removidos em cascata com ela.
Enumerações
| Enum | Valores |
|---|---|
ESignatureProviderType | OPENSIGN (implementado) · DOCUSIGN · ADOBESIGN · ZAPSIGN (declarados, recusam em execução — §15) |
SignatureRequestStatus | DRAFT · SENT · VIEWED · PARTIALLY_SIGNED · COMPLETED · DECLINED · EXPIRED · CANCELLED |
SignerStatus | PENDING · SENT · VIEWED · SIGNED · DECLINED |
São duas máquinas de estado diferentes — a do envelope e a do signatário — e confundi-las é a origem mais comum de bug de integração neste building block. O envelope responde "a operação acabou?"; o signatário responde "quem falta?".
Máquina de estados do envelope
Máquina de estados do envelope
stateDiagram-v2
direction TB
[*] --> DRAFT: POST /requests
DRAFT: DRAFT — inicial, gravado quando o provedor ainda não reportou envio
SENT: SENT — o provedor reportou o envio na criação
VIEWED: VIEWED — alguém abriu o documento
PARTIALLY_SIGNED: PARTIALLY_SIGNED — um assinou e ainda falta alguém
COMPLETED: COMPLETED — todos assinaram, completedAt preenchido
DECLINED: DECLINED — alguém recusou
CANCELLED: CANCELLED — cancelado pela API
EXPIRED: EXPIRED — declarado no enum e nunca gravado hoje, §15
DRAFT --> SENT: provedor reporta envio
DRAFT --> VIEWED: webhook viewed
SENT --> VIEWED: webhook viewed
VIEWED --> PARTIALLY_SIGNED: webhook signed, ainda falta signatário
VIEWED --> COMPLETED: webhook signed, todos assinaram
PARTIALLY_SIGNED --> PARTIALLY_SIGNED: webhook signed, ainda falta signatário
PARTIALLY_SIGNED --> COMPLETED: webhook signed, todos assinaram
SENT --> COMPLETED: webhook completed
VIEWED --> COMPLETED: webhook completed
DRAFT --> DECLINED: webhook declined
SENT --> DECLINED: webhook declined
VIEWED --> DECLINED: webhook declined
PARTIALLY_SIGNED --> DECLINED: webhook declined
DRAFT --> CANCELLED: POST /requests/:id/cancel
SENT --> CANCELLED: POST /requests/:id/cancel
VIEWED --> CANCELLED: POST /requests/:id/cancel
PARTIALLY_SIGNED --> CANCELLED: POST /requests/:id/cancel
DECLINED --> CANCELLED: POST /requests/:id/cancel
COMPLETED --> [*]
CANCELLED --> [*]
EXPIRED --> [*]
note right of COMPLETED
COMPLETED é condição para
GET /requests/:id/download
end note
note right of CANCELLED
Cancelar é bloqueado quando o
status já é COMPLETED ou CANCELLED:
o serviço responde VALIDATION
end noteTrês leituras que o diagrama não diz sozinho:
| Observação | Consequência prática |
|---|---|
DRAFT e SENT dependem do que o provedor reporta na criação | O estado inicial não é escolha sua |
VIEWED, PARTIALLY_SIGNED, COMPLETED e DECLINED chegam pelo webhook ou por POST /requests/:id/refresh, que reconsulta o provedor (§9) | Na prática, o estado gravado é o da criação até que alguém o atualize |
EXPIRED está no enum, é mapeado a partir do provedor, e nenhum caminho do código o persiste | Envelope vencido continua no último estado conhecido (§15) |
Máquina de estados do signatário
Máquina de estados do signatário
stateDiagram-v2
direction LR
[*] --> PENDING: criação do envelope
PENDING: PENDING — ainda sem URL de assinatura
SENT: SENT — sentAt preenchido, o provedor emitiu a URL de assinatura
VIEWED: VIEWED — viewedAt preenchido
SIGNED: SIGNED — signedAt preenchido
DECLINED: DECLINED — declinedAt preenchido
PENDING --> SENT: o provedor emite a URL de assinatura
PENDING --> VIEWED: webhook viewed com o e-mail do signatário
SENT --> VIEWED: webhook viewed com o e-mail do signatário
PENDING --> SIGNED: webhook signed com o e-mail do signatário
SENT --> SIGNED: webhook signed com o e-mail do signatário
VIEWED --> SIGNED: webhook signed com o e-mail do signatário
PENDING --> DECLINED: webhook declined com o e-mail do signatário
SENT --> DECLINED: webhook declined com o e-mail do signatário
VIEWED --> DECLINED: webhook declined com o e-mail do signatário
SIGNED --> [*]
DECLINED --> [*]Como as duas máquinas se conversam:
- O envelope vira
COMPLETEDquando todos os signatários estãoSIGNED. - Enquanto faltar um, o envelope fica
PARTIALLY_SIGNED. - A correspondência entre o webhook e o signatário é feita pelo e-mail — por isso dois signatários com o mesmo e-mail quebram o acompanhamento (§16).
- O
declineReasonexiste como coluna, mas o tratamento do webhookdeclinedgrava apenasstatusedeclinedAt; o motivo depende do provedor informá-lo por outro caminho.
Modelos da conferência de assinatura (mesmo schema esignature):
| Modelo Prisma | Tabela | Propósito | Campos-chave |
|---|---|---|---|
SignatureVerificationSettings | signature_verification_settings | Decisão da organização. Sem linha = padrão da casa | Único organizationId, thirdPartyEnabled (padrão false), fileRetentionDays (padrão 30), updatedBy |
SignatureVerification | signature_verifications | Uma conferência de um arquivo | fileHash e detachedHash (SHA-256), fileType (lido do conteúdo), status (VALID · INVALID · INDETERMINATE), reasonCodes, report (normalizado, mascarado), reportDigest, providerOutcome (ANSWERED · TIMEOUT · UNAVAILABLE · ERROR), fileId (cópia temporária), fileExpiresAt, filePurgedAt, businessId |
Referência da API
Prefixo HTTP: /e-signature. Em monolito, a base é http://localhost:3000. Em standalone, a porta é 3014; em staging, https://esignature.bb.stg.catalisa.app; em produção, https://esignature.bb.catalisa.app.
Atenção ao prefixo. O caminho real repete o nome do módulo, e com grafias diferentes: o basePath do app é /e-signature, com hífen, e os routers são montados em /api/v1/esignature, sem hífen. A rota completa é /e-signature/api/v1/esignature/.... Não é erro de digitação — copie do quadro abaixo em vez de deduzir.
15 das 16 rotas exigem authMiddleware (Bearer JWT do IAM), requirePermission e o middleware local requireOrganization, que devolve 403 quando o token não carrega organizationId. A exceção é a rota de webhook, que é pública por natureza — o provedor não tem token da plataforma. As rotas da página de assinatura hospedada (/e-signature/sign/*, quadro abaixo) também são públicas, e ficam fora dessa contagem: a credencial é o código opaco do link.
Página de assinatura hospedada — /e-signature/sign (desde 16/10/2026)
Com provedor OPENSIGN (self-hosted, o nosso motor), o signingUrl de cada signatário em POST /requests e GET /requests/:id é ${ESIGNATURE_PUBLIC_URL}/e-signature/sign/<código> — página no domínio do bloco, com a marca do tenant. O campo é o mesmo; o contrato do painel não muda. Sem ESIGNATURE_PUBLIC_URL, criar envelope OpenSign responde 503.
Rotas públicas (sem token: quem chega tem só o código opaco de 128 bits; no banco fica o SHA-256). Montadas antes do middleware global, com rate limit por IP (60/min), Cache-Control: no-store, nosniff, CSP com nonce e frame-ancestors pela allowlist settings.allowedEmbedHosts da configuração.
| Método | Rota | O que faz |
|---|---|---|
GET | /e-signature/sign/:code | A página: termo em PDF (pdf.js da mesma origem, sem iframe), nome e CPF mascarados, "li e concordo", código por e-mail, assinatura desenhada ou digitada. Estados finais: assinado, recusado, expirado, cancelado, inválido |
GET | /e-signature/sign/:code/state | Estado pela ótica do link, sem dado pessoal — e sem "conferido": a conferência só vale para quem a fez |
GET | /e-signature/sign/:code/document.pdf | O PDF do envelope, do storage do bloco (o original vai para lá na criação) |
POST | /e-signature/sign/:code/otp | Envia o código de 6 dígitos ao e-mail do signatário. Espera de 60 s entre envios, validade de 10 min, 10 envios na vida do link. O envio é reivindicado no banco (atualização condicional): pedidos paralelos não furam a espera nem o teto |
POST | /e-signature/sign/:code/verify | { otp } → { signToken, expiresAt }. Cada conferência gasta uma tentativa reivindicada no banco antes de comparar: 5 erros seguidos travam por 15 min e 15 tentativas na vida do link travam o link (LINK_LOCKED) até a casa reemitir. O signToken (30 min, uso único, do signatário que conferiu) é o que libera assinar ou recusar |
POST | /e-signature/sign/:code/sign | { accepted: true, method: 'drawn' | 'typed', image: 'data:image/png;base64,...' } (até 1 MB de corpo, 512 KB de PNG). Exige o signToken do /verify, que é consumido (uso único; volta a valer se o motor não aplicou por motivo passageiro). Quem aplica é o SignatureApplier do motor (sela o PDF, move o envelope a PARTIALLY_SIGNED/COMPLETED e publica esignature.signer.signed); a página grava ao lado a própria evidência (aceite, fator, hash da imagem e do documento) |
POST | /e-signature/sign/:code/decline | { reason, signToken } (3 a 500 caracteres, mesmo token do /verify). Sob o mesmo lock do applier (esignature:signing:<requestId>): recusar e assinar nunca correm juntos; signatário em SIGNING não recusa. Signatário e envelope vão a DECLINED |
Aparência: appearance do envelope (POST /requests) > settings.appearance da configuração > padrão Catalisa (mesma Appearance API do biometrics: cores, raio, fonte, logo, modo claro/escuro/auto, layout, textos, redirectUrl). signers[].cpf (opcional) só existe para a página mostrar ***.456.789-**: não vai ao provedor e o número inteiro não é gravado. Reenviar (POST /requests/:id/resend) emite link novo para quem ainda não assinou, mata o anterior e zera os tetos do código — é a única saída de um link travado; o painel entrega o signingUrl novo, que vem no GET /requests/:id (o bloco não manda e-mail com o link). Cancelar mata todos. O e-mail do código diz quem pediu a assinatura: settings.senderName da configuração (ou o nome dela). O mesmo nome vai, no OpenSign local, para a "Organização" do certificado de conclusão (desde 22/10/2026; §11, "O certificado de conclusão"). Logo e PDF saem pelo file-storage da organização do envelope. redirectUrl só aceita https://.
Recusas do motor (appError.details.reason do applier) viram mensagem em pt-BR sem perder o desenho nem o aceite: BUSY (outra pessoa assinando), OUT_OF_ORDER (aguarde a sua vez), REQUEST_EXPIRED, ALREADY_SIGNED, IMAGE_TOO_LARGE, PROVIDER_CONFLICT. A resposta traz reload: true só quando o estado do link mudou de verdade.
O caminho do signatário, na ordem em que ele vê:
- Aceite. Ele lê o PDF e marca "Li e concordo com os termos deste documento".
- Código. "Enviar código" manda os 6 dígitos ao e-mail dele, que a página mostra mascarado (
ma•••@example.com). O campo do código aparece com "Confirmar" e, abaixo, "Reenviar código em 60s". - Assinatura. Conferido o código, a página diz "Código confirmado." e libera "Desenhar" ou "Digitar". "Assinar documento" só fica ativo com a assinatura feita.
- Fim. "Documento assinado. Você já pode fechar esta página." É também o que um segundo acesso ao mesmo link mostra.

O PDF que sai do motor leva, no rodapé da última página, a assinatura desenhada e uma linha de carimbo por signatário (nome, data UTC, IP e SHA-256 do original), e é selado com PKCS#7 (/ByteRange).
Sem o documento, a página não abre o termo. GET /e-signature/sign/:code/document.pdf responde 503 com DOCUMENT_UNAVAILABLE quando o PDF não pôde ser lido. Cada falha é logada com onde e por quê e publica esignature.signer.document_unavailable (§13). A causa mais comum é MODULE_FILE_STORAGE_URL ausente ou sem o prefixo /file-storage.
Eventos (stream iam-events, actorType: customer, IP e user-agent): esignature.signer.page_viewed, .viewed (primeira vez), .link_expired, .link_revoked, .link_locked, .rate_limited (uma vez por janela), .otp_sent, .otp_refused, .otp_failed, .otp_wrong, .otp_expired, .otp_locked, .otp_verified, .terms_accepted, .sign_refused, .declined, .decline_refused e esignature.request.declined; a aplicação no motor publica esignature.signer.signed ou esignature.signature.refused|failed. Nenhum carrega o código, o OTP nem o CPF.
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /e-signature/api/v1/esignature/provider-configs | Cria configuração e cifra as credenciais. Responde 201 | ESIGNATURE_ADMIN |
GET | /e-signature/api/v1/esignature/provider-configs | Lista as configurações da organização | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/provider-configs/:id | Busca uma configuração (sem as credenciais) | ESIGNATURE_READ |
PATCH | /e-signature/api/v1/esignature/provider-configs/:id | Atualiza nome, credenciais, ajustes ou estado | ESIGNATURE_ADMIN |
DELETE | /e-signature/api/v1/esignature/provider-configs/:id | Exclusão lógica. Responde 204 | ESIGNATURE_ADMIN |
POST | /e-signature/api/v1/esignature/provider-configs/:id/test | Testa a conexão com o provedor | ESIGNATURE_ADMIN |
POST | /e-signature/api/v1/esignature/provider-configs/:id/set-default | Marca como padrão e desmarca as demais | ESIGNATURE_ADMIN |
Credenciais por provedor (cifradas em repouso): OPENSIGN → baseUrl, apiPrefix, appId, masterKey, gateToken; ZAPSIGN → apiToken e, opcionalmente, baseUrl (https://sandbox.api.zapsign.com.br para o sandbox; produção é o padrão). settings do ZapSign: webhookSecret (o segredo que a conta ZapSign envia no cabeçalho X-Webhook-Secret), lang, sendAutomaticEmail.
Solicitações de assinatura — /e-signature/api/v1/esignature/requests
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /e-signature/api/v1/esignature/requests | Cria a solicitação a partir de um arquivo. Responde 201 | ESIGNATURE_CREATE |
POST | /e-signature/api/v1/esignature/requests/from-template | Cria a partir de um template do provedor. Responde 201 | ESIGNATURE_CREATE |
GET | /e-signature/api/v1/esignature/requests | Lista solicitações, paginado | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/requests/:id | Busca a solicitação com os signatários | ESIGNATURE_READ |
POST | /e-signature/api/v1/esignature/requests/:id/cancel | Cancela a solicitação | ESIGNATURE_CREATE |
POST | /e-signature/api/v1/esignature/requests/:id/resend | Reenvia a todos ou a um signatário | ESIGNATURE_CREATE |
GET | /e-signature/api/v1/esignature/requests/:id/evidence | Lê a evidência já gravada, sem recapturar e sem chamar o provedor. meta.evidence e meta.capturedAt vêm null enquanto nada foi capturado. A evidência devolvida (aqui e no POST) não traz token de link de terceiro: o ZapSign grava só documentTokenRef/signers[].tokenRef (SHA-256 truncado), e tokens de evidência antiga são retirados da resposta | ESIGNATURE_READ |
POST | /e-signature/api/v1/esignature/requests/:id/evidence | Captura (ou recaptura) a evidência de um envelope COMPLETED: hash do documento assinado, nível legal, material do provedor. Provedor com getEvidence fornece; sem ele, o bloco baixa o PDF assinado e calcula o SHA-256. Publica esignature.request.evidence_captured; também roda sozinha quando o webhook conclui o envelope. A recaptura preserva signedFileId e certificateFileId (lidos dos documentos do envelope; um id conhecido nunca vira null) | ESIGNATURE_CREATE |
POST | /e-signature/api/v1/esignature/requests/:id/refresh | Reconsulta o provedor e concilia a cópia local: estado, conclusão, URL, validade e cada signatário (por id externo, depois por e-mail). meta.changed e meta.signersUpdated dizem o que mudou; publica esignature.request.completed quando a conciliação conclui | ESIGNATURE_CREATE |
GET | /e-signature/api/v1/esignature/requests/:id/download | URL do documento assinado. Exige COMPLETED | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/requests/:id/certificate | URL assinada do certificado de conclusão arquivado no file-storage (certificateFileId). Exige COMPLETED (400 antes disso); 404 se não há certificado arquivado. Só a cópia arquivada — não consulta o provedor | ESIGNATURE_READ |
DELETE | /e-signature/api/v1/esignature/requests/:id | Exclusão lógica. Responde 204 | ESIGNATURE_DELETE |
Filtros aceitos em GET /requests: filter[status] e filter[businessId]. Paginação por page[number] e page[size].
Resposta de GET /requests/:id/evidence (ilustrativa, resumida; envelope do OpenSign local):
{
"data": { "type": "signature-request", "id": "7e6f…", "attributes": { "status": "COMPLETED", "documentHash": "9b1f…c04e", "signatureLevel": "SIMPLE" } },
"links": { "self": "…" },
"meta": {
"evidence": {
"source": "provider",
"provider": "OPENSIGN",
"certificateSha256": "3a7d…91be",
"signedFileId": "c2b4…",
"certificateFileId": "e81a…",
"certificateUrl": null,
"signers": [{ "email": "ana@exemplo.com", "ipAddress": "203.0.113.10", "signedAt": "2026-10-17T14:02:09.000Z" }]
},
"capturedAt": "2026-10-17T14:02:11.000Z"
}
}{
"data": { "type": "signature-request", "id": "7e6f…", "attributes": { "status": "COMPLETED", "documentHash": "9b1f…c04e", "signatureLevel": "SIMPLE" } },
"links": { "self": "…" },
"meta": {
"evidence": {
"source": "provider",
"provider": "OPENSIGN",
"certificateSha256": "3a7d…91be",
"signedFileId": "c2b4…",
"certificateFileId": "e81a…",
"certificateUrl": null,
"signers": [{ "email": "ana@exemplo.com", "ipAddress": "203.0.113.10", "signedAt": "2026-10-17T14:02:09.000Z" }]
},
"capturedAt": "2026-10-17T14:02:11.000Z"
}
}Resposta de GET /requests/:id/certificate (mesmo formato do /download):
{ "downloadUrl": "https://…/certificado.pdf?assinatura=…", "expiresAt": "2026-10-17T15:02:11.000Z" }{ "downloadUrl": "https://…/certificado.pdf?assinatura=…", "expiresAt": "2026-10-17T15:02:11.000Z" }A URL expira; peça outra quando precisar. Por isso evidence.certificateUrl continua null: a evidência guarda o id do arquivo (certificateFileId), não um link que vence.
Webhook do provedor
| Método | Rota | Descrição | Autenticação |
|---|---|---|---|
POST | /e-signature/api/v1/esignature/webhooks/:configId | Recebe evento do provedor. Resolve a configuração pelo id (ativa, não excluída) e escopa tudo pela organização dela; corpo lido como bytes e entregue ao provedor para verificar a assinatura | Pública — sem JWT. Ver §14 e §15 |
Conferir assinatura de arquivo — /e-signature/api/v1/esignature/verifications
| Método | Rota | Descrição | Permissão |
|---|---|---|---|
POST | /e-signature/api/v1/esignature/verifications | Confere um arquivo. Multipart: file (o PDF/P7S/XML assinado), detachedFile (o conteúdo, se a assinatura for destacada), businessId — corpo total até 1 MB. JSON: { "fileId", "detachedFileId"?, "businessId"? } com arquivos já no file-storage da organização, até ESIGNATURE_VERIFICATION_MAX_BYTES. Responde 201 com meta.reused e meta.auditRecorded | ESIGNATURE_CREATE |
GET | /e-signature/api/v1/esignature/verifications | Lista, filtros filter[fileHash], filter[businessId], filter[status] | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/verifications/:id | Uma conferência | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/verifications/proof?fileHash= | Prova pela trilha: o arquivo com este SHA-256 foi conferido, quando, com que resultado; confere o digest do relatório e a linha local | ESIGNATURE_READ |
GET | /e-signature/api/v1/esignature/verification-settings | Configuração efetiva; source: DEFAULT = padrão da casa, não alterado | ESIGNATURE_READ |
PUT | /e-signature/api/v1/esignature/verification-settings | { "thirdPartyEnabled"?, "fileRetentionDays"? } (1–365). Publica esignature.verification-settings.changed | ESIGNATURE_ADMIN |
Nenhuma rota aceita organização como parâmetro. Resposta de POST (resumida):
{
"data": {
"type": "signature-verification",
"id": "5f0c…",
"attributes": {
"status": "VALID",
"reasonCodes": ["PROVIDER_APPROVED"],
"fileHash": "5b06c3e8…4f410",
"fileType": "PDF",
"report": {
"status": "VALID",
"signatureCount": 1,
"signatures": [{
"status": "VALID", "format": "PAdES", "signedAt": "2026-08-26T01:41:11.000Z", "policy": null,
"signer": { "name": "DIARIO OFICIAL DA UNIAO", "documents": [{ "type": "CPF", "masked": "***.456.789-**" }] },
"chain": [{ "subject": "CN=DIARIO OFICIAL DA UNIAO, …", "notAfter": "…", "expired": false, "revoked": false }]
}],
"provider": { "type": "ITI_VERIFIER", "software": "Verificador de Conformidade", "version": "2.32.1" }
},
"file": { "retained": true, "expiresAt": "2026-10-31T12:00:00.000Z", "purgedAt": null }
},
"meta": { "reused": false, "auditRecorded": true }
}
}{
"data": {
"type": "signature-verification",
"id": "5f0c…",
"attributes": {
"status": "VALID",
"reasonCodes": ["PROVIDER_APPROVED"],
"fileHash": "5b06c3e8…4f410",
"fileType": "PDF",
"report": {
"status": "VALID",
"signatureCount": 1,
"signatures": [{
"status": "VALID", "format": "PAdES", "signedAt": "2026-08-26T01:41:11.000Z", "policy": null,
"signer": { "name": "DIARIO OFICIAL DA UNIAO", "documents": [{ "type": "CPF", "masked": "***.456.789-**" }] },
"chain": [{ "subject": "CN=DIARIO OFICIAL DA UNIAO, …", "notAfter": "…", "expired": false, "revoked": false }]
}],
"provider": { "type": "ITI_VERIFIER", "software": "Verificador de Conformidade", "version": "2.32.1" }
},
"file": { "retained": true, "expiresAt": "2026-10-31T12:00:00.000Z", "purgedAt": null }
},
"meta": { "reused": false, "auditRecorded": true }
}
}Recusas (nada é enviado; cada uma publica esignature.verification.refused com o código e loga):
| Status | details.code | Quando |
|---|---|---|
403 | THIRD_PARTY_DISABLED | A organização não ligou o envio a terceiro (padrão da casa) |
503 | — (PROVIDER_NOT_CONFIGURED no evento) | ESIGNATURE_ITI_VERIFIER_URL ausente no ambiente |
413 | FILE_TOO_LARGE | Acima de ESIGNATURE_VERIFICATION_MAX_BYTES |
400 | FILE_EMPTY, UNSUPPORTED_FILE_TYPE, DETACHED_CONTENT_REQUIRED, FILE_UNREADABLE | Arquivo vazio; não é PDF/P7S/XML assinado pelo conteúdo; P7S/XML destacado sem o conteúdo |
404 | — (FILE_NOT_FOUND) | fileId inexistente ou de outra organização |
409 | — (VERIFICATION_IN_PROGRESS) | O mesmo arquivo está sendo conferido agora e a outra chamada não terminou a tempo |
O mapeamento completo do resultado do verificador para status e reasonCodes está em docs/signature-verification.md.
Saúde
| Método | Rota | Descrição |
|---|---|---|
GET | /e-signature/health | Sonda de disponibilidade. Pública, não contabilizada nas 16 rotas |
POST /e-signature/api/v1/esignature/provider-configs
Cria a configuração e cifra as credenciais antes de gravar. O corpo aceita tanto o envelope JSON:API (data.attributes) quanto o objeto direto.
Request
{
"name": "OpenSign Produção",
"providerType": "OPENSIGN",
"credentials": {
"baseUrl": "https://<host-interno-do-motor>:8090",
"appId": "opensign",
"apiPrefix": "/api/app",
"masterKey": "<master key do motor>",
"gateToken": "<segredo do portão do motor>"
},
"isDefault": true,
"isActive": true
}{
"name": "OpenSign Produção",
"providerType": "OPENSIGN",
"credentials": {
"baseUrl": "https://<host-interno-do-motor>:8090",
"appId": "opensign",
"apiPrefix": "/api/app",
"masterKey": "<master key do motor>",
"gateToken": "<segredo do portão do motor>"
},
"isDefault": true,
"isActive": true
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string (1–100) | Sim | Nome da configuração. Único por organização |
providerType | OPENSIGN | DOCUSIGN | ADOBESIGN | ZAPSIGN | Sim | Só OPENSIGN funciona hoje (§15) |
credentials | objeto de textos | Sim | Cifrado antes de gravar. As chaves dependem do provedor |
isDefault | booleano | Não | Sem valor, a primeira configuração da organização vira a padrão |
isActive | booleano | Não | Padrão true |
settings | objeto | Não | Ajustes específicos do provedor |
Credenciais do OpenSign
| Chave | Obrigatória | Descrição |
|---|---|---|
baseUrl | Sim | Host de malha do motor, em https (com mTLS, http é recusado) |
masterKey | Sim | Master key do motor (ele só a aceita vinda de dentro do container, isto é, pelo portão) |
gateToken | Sim | Segredo do portão do motor. Sem ele, o motor responde 403 a tudo |
appId | Não | Identificador da aplicação Parse. Padrão opensign |
apiPrefix | Não | Padrão /api/app (o portão monta o Parse em /api/app) |
Faltando baseUrl, masterKey ou gateToken, toda operação responde 400 VALIDATION.
settings.extUserId / settings.extUserOrganizationId são gravados pelo bloco (conta técnica da
organização no motor); não precisam vir na criação.
Resposta 201 — devolve a configuração sem o campo credentials. O segredo não volta em nenhuma rota, nunca.
Erros
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | Corpo reprovado no Zod, ou providerType fora do enum |
403 | — | Sem ESIGNATURE_ADMIN, ou token sem organizationId |
409 | CONFLICT | Já existe configuração com esse nome na organização |
500 | INTERNAL | ESIGNATURE_CREDENTIAL_MASTER_KEY ausente ou malformada — a cifragem falha |
A criação não testa a conexão. Chame
POST /:id/testlogo em seguida; sem isso, uma credencial errada só aparece na primeira solicitação real.
POST /e-signature/api/v1/esignature/requests
Cria a solicitação e a envia ao provedor.
Request
{
"title": "CCB - Proposta 2026-000481",
"message": "Por favor, assine a cédula de crédito.",
"fileId": "8f2c1a90-0000-0000-0000-000000000000",
"businessId": "proposta-2026-000481",
"expiresInDays": 15,
"signers": [
{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 },
{ "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2 }
],
"widgets": [
{ "type": "signature", "page": 3, "x": 100, "y": 620, "width": 150, "height": 50, "required": true }
]
}{
"title": "CCB - Proposta 2026-000481",
"message": "Por favor, assine a cédula de crédito.",
"fileId": "8f2c1a90-0000-0000-0000-000000000000",
"businessId": "proposta-2026-000481",
"expiresInDays": 15,
"signers": [
{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 },
{ "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2 }
],
"widgets": [
{ "type": "signature", "page": 3, "x": 100, "y": 620, "width": 150, "height": 50, "required": true }
]
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string (1–255) | Sim | Título do envelope |
message | string (máx. 2000) | Não | Mensagem aos signatários |
configId | UUID | Não | Configuração a usar. Omitido, usa a padrão da organização |
fileId | UUID | Um dos dois | Arquivo já guardado no file-storage |
fileBase64 | string | Um dos dois | Arquivo em base64. Exige fileName |
fileName | string (máx. 255) | Com fileBase64 | Nome do arquivo, usado para deduzir o tipo |
signers | lista, mínimo 1 | Sim | Cada item com name, email e order opcional |
widgets | lista | Não | Campos de assinatura. Sem eles, um campo por signatário na primeira página |
businessId | string (máx. 100) | Não | Identificador da operação de origem |
expiresInDays | inteiro 1–365 | Não | No OpenSign, vira TimeToCompleteDays; padrão do provedor é 15 |
Resposta 201
{
"data": {
"type": "signature-request",
"id": "3c8a1e77-0000-0000-0000-000000000000",
"links": { "self": "/api/v1/esignature/requests/3c8a1e77-0000-0000-0000-000000000000" },
"attributes": {
"title": "CCB - Proposta 2026-000481",
"status": "DRAFT",
"businessId": "proposta-2026-000481",
"expiresAt": "2026-08-31T00:00:00.000Z",
"createdAt": "2026-08-16T14:03:11.000Z"
},
"relationships": {
"signers": {
"data": [
{ "type": "signer", "id": "a1...", "attributes": { "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1, "status": "SENT", "signingUrl": "https://..." } },
{ "type": "signer", "id": "b2...", "attributes": { "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2, "status": "PENDING" } }
]
}
}
}
}{
"data": {
"type": "signature-request",
"id": "3c8a1e77-0000-0000-0000-000000000000",
"links": { "self": "/api/v1/esignature/requests/3c8a1e77-0000-0000-0000-000000000000" },
"attributes": {
"title": "CCB - Proposta 2026-000481",
"status": "DRAFT",
"businessId": "proposta-2026-000481",
"expiresAt": "2026-08-31T00:00:00.000Z",
"createdAt": "2026-08-16T14:03:11.000Z"
},
"relationships": {
"signers": {
"data": [
{ "type": "signer", "id": "a1...", "attributes": { "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1, "status": "SENT", "signingUrl": "https://..." } },
{ "type": "signer", "id": "b2...", "attributes": { "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2, "status": "PENDING" } }
]
}
}
}
}O signingUrl de cada signatário é a URL individual de assinatura. Trate-a como segredo: quem tem o link consegue assinar.
Erros
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | Nenhum ou os dois de fileId/fileBase64; fileBase64 sem fileName; lista de signatários vazia |
404 | NOT_FOUND | configId inexistente, ou a organização não tem configuração padrão ativa |
413 | — | Corpo acima de 1 MB — o teto prático de fileBase64 (§15) |
500 | INTERNAL | providerType declarado mas não implementado; falha ao baixar o arquivo do S3; erro do provedor |
GET /e-signature/api/v1/esignature/requests/:id
Devolve o envelope com os signatários aninhados. É a rota de acompanhamento.
Resposta 200 — mesmo formato da criação, com os estados e carimbos atualizados. Cada signatário traz status, sentAt, viewedAt, signedAt, declinedAt e declineReason.
Enquanto o webhook não estiver funcional (§15), estes campos refletem o que o provedor reportou no momento da criação. Não existe rota que force a releitura do estado no provedor — ver §15.
POST /e-signature/api/v1/esignature/requests/:id/cancel
Cancela a solicitação no provedor e grava CANCELLED.
Erros
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | Cannot cancel request with status COMPLETED ou CANCELLED |
404 | NOT_FOUND | Solicitação inexistente, excluída ou de outra organização |
No OpenSign local, o cancelamento recusa o documento no motor e o marca revogado (RevokedAt); o signPdf do motor deixa de aceitar assinatura nele. Documento que o motor não conhece conta como já cancelado.
POST /e-signature/api/v1/esignature/requests/:id/resend
Request (corpo opcional)
{ "signerEmail": "maria@exemplo.com.br" }{ "signerEmail": "maria@exemplo.com.br" }Sem signerEmail, reenvia a todos. Com ele, o signatário precisa existir no envelope — caso contrário, 404.
Resposta 200
{ "message": "Signature request resent successfully" }{ "message": "Signature request resent successfully" }A mensagem confirma que a chamada ao provedor não falhou. Ela não confirma que um e-mail saiu. No OpenSign local a rota responde
400: o motor não manda e-mail, e o acesso do signatário se reemite pela página de assinatura (§7).
GET /e-signature/api/v1/esignature/requests/:id/download
Resposta 200
{
"downloadUrl": "https://<file-storage>/...",
"expiresAt": "2026-08-16T15:03:11.000Z"
}{
"downloadUrl": "https://<file-storage>/...",
"expiresAt": "2026-08-16T15:03:11.000Z"
}Erros
| Status | Código | Quando |
|---|---|---|
400 | VALIDATION | Document is not yet completed and signed — a solicitação não está COMPLETED |
404 | NOT_FOUND | Solicitação inexistente, ou o provedor não expôs documento assinado |
A URL é do provedor e o serviço não faz proxy do binário. O expiresAt é uma hora por padrão quando o provedor não informa validade — é uma estimativa nossa, não uma garantia dele. Baixe e guarde no file-storage em vez de reter a URL.
POST /e-signature/api/v1/esignature/webhooks/:configId
Rota pública, chamada pelo provedor. O :configId no caminho identifica a configuração e, por ela, a organização.
O fluxo é: verificar a assinatura do webhook → registrar o evento cru em esignature_webhook_events → aplicar a mudança de estado no envelope e no signatário → marcar o evento como processado. Falha no processamento é gravada no campo error do evento, e o evento permanece registrado.
flowchart TD
W["POST /webhooks/:configId<br/>chamada pelo provedor, sem JWT"] --> V{"assinatura do webhook verificável?"}
V -->|"não, e enforcement = off (padrão)"| Log["aceita e registra aviso no log"]
V -->|"não, e enforcement = on"| Rec["recusa o evento"]
V -->|sim| Log
Log --> G["grava o evento cru em esignature_webhook_events<br/>payload com o corpo original"]
G --> T{"eventType"}
T -->|viewed| E1["envelope de SENT ou DRAFT para VIEWED<br/>signatário para VIEWED, por e-mail"]
T -->|signed| E2["signatário para SIGNED<br/>envelope para COMPLETED ou PARTIALLY_SIGNED"]
T -->|completed| E3["envelope para COMPLETED e completedAt"]
T -->|declined| E4["signatário e envelope para DECLINED"]
T -->|"qualquer outro tipo"| E5["registrado e ignorado"]
E1 --> M["marca o evento como processed"]
E2 --> M
E3 --> M
E4 --> M
E5 --> M
M -.->|"se algo falhar"| Err["grava o motivo em error<br/>e mantém o evento registrado"]Eventos tratados: viewed, signed, completed, declined. Outros tipos são registrados e ignorados.
Esta rota não está funcional hoje — ver §15. Não a inclua no seu desenho de integração antes de confirmar o estado dela.
Início rápido
De ponta a ponta com a página hospedada: do envelope criado no motor OpenSign local ao PDF selado no file-storage. Comandos escritos para staging; não executados nesta redação — os valores das respostas são ilustrativos. O caminho foi provado de ponta a ponta em staging em 17/10/2026, com e-mail real (§4, Caso 6).
Antes de começar. O serviço do bloco precisa de ESIGNATURE_PUBLIC_URL (sem ela, criar envelope OpenSign responde 503), MODULE_FILE_STORAGE_URL com o prefixo /file-storage, OPENSIGN_ALLOWED_HOSTS, as três OPENSIGN_TLS_* e o SMTP_* do código por e-mail (§13). Em staging e em produção isso já está no ar; numa instalação nova, é o primeiro lugar a conferir.
flowchart LR
P1["1. Autenticar"] --> P2["2. Configurar o motor"]
P2 --> P3["3. Testar a conexão"]
P3 -->|"success: false"| Pare["Pare aqui.<br/>A criação não valida credencial"]
P3 -->|"success: true"| P4["4. Criar o envelope"]
P4 --> P5["5. Entregar o signingUrl"]
P5 --> P6["6. O signatário assina na página"]
P6 --> P7["7. Eventos"]
P7 --> P8["8. Evidência e PDF selado"]1. Autenticar no IAM
TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "SEU_EMAIL",
"password": "SUA_SENHA",
"organizationId": "ID_DA_SUA_ORGANIZACAO"
}' | jq -r .accessToken)
BASE=https://esignature.bb.stg.catalisa.app/e-signature/api/v1/esignatureTOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
-H "Content-Type: application/json" \
-d '{
"email": "SEU_EMAIL",
"password": "SUA_SENHA",
"organizationId": "ID_DA_SUA_ORGANIZACAO"
}' | jq -r .accessToken)
BASE=https://esignature.bb.stg.catalisa.app/e-signature/api/v1/esignature2. Configurar o motor OpenSign local como provedor
CFG=$(curl -s -X POST "$BASE/provider-configs" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Assinatura da casa",
"providerType": "OPENSIGN",
"credentials": {
"baseUrl": "https://opensign-local.exemplo.internal:8090",
"apiPrefix": "/api/app",
"appId": "opensign",
"masterKey": "SUBSTITUA_PELA_MASTER_KEY_DO_MOTOR",
"gateToken": "SUBSTITUA_PELO_TOKEN_DO_PORTAO"
},
"settings": {
"senderName": "Financeira Exemplo",
"appearance": { "mode": "auto" }
},
"isDefault": true
}')
CFG_ID=$(echo "$CFG" | jq -r '.data.id')
echo "$CFG" | jq '.data.attributes'CFG=$(curl -s -X POST "$BASE/provider-configs" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Assinatura da casa",
"providerType": "OPENSIGN",
"credentials": {
"baseUrl": "https://opensign-local.exemplo.internal:8090",
"apiPrefix": "/api/app",
"appId": "opensign",
"masterKey": "SUBSTITUA_PELA_MASTER_KEY_DO_MOTOR",
"gateToken": "SUBSTITUA_PELO_TOKEN_DO_PORTAO"
},
"settings": {
"senderName": "Financeira Exemplo",
"appearance": { "mode": "auto" }
},
"isDefault": true
}')
CFG_ID=$(echo "$CFG" | jq -r '.data.id')
echo "$CFG" | jq '.data.attributes'A resposta traz name, providerType, isDefault e isActive — e nenhum vestígio das credenciais. É o comportamento esperado. O baseUrl precisa estar em OPENSIGN_ALLOWED_HOSTS, senão a configuração é recusada com 400. senderName é quem aparece no e-mail do código ("quem pediu a assinatura") e, no OpenSign local, na "Organização" do certificado de conclusão. Use o nome da casa, não um nome técnico: sem senderName vale o name da configuração, e é ele que o signatário lê.
3. Testar a conexão antes de qualquer outra coisa
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" \
-H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST "$BASE/provider-configs/$CFG_ID/test" \
-H "Authorization: Bearer $TOKEN" | jq{ "success": true, "message": "Connection successful" }{ "success": true, "message": "Connection successful" }Se voltar success: false ou um erro, pare aqui. A criação não valida credencial, e seguir adiante só adia a descoberta do problema. Erro de TLS aqui quase sempre é material OPENSIGN_TLS_* faltando ou trocado no serviço (§13).
4. Criar o envelope
REQ=$(curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Termo de cessão de recebíveis",
"fileBase64": "'"$(base64 -w0 termo.pdf)"'",
"fileName": "termo.pdf",
"businessId": "cessao-2026-000123",
"expiresInDays": 7,
"signers": [
{ "name": "Maria da Silva Souza", "email": "maria@exemplo.com.br", "cpf": "123.456.789-09", "order": 1 }
]
}')
REQ_ID=$(echo "$REQ" | jq -r '.data.id')
echo "$REQ" | jq '[.data.relationships.signers.data[].attributes | {email, status, signingUrl}]'REQ=$(curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Termo de cessão de recebíveis",
"fileBase64": "'"$(base64 -w0 termo.pdf)"'",
"fileName": "termo.pdf",
"businessId": "cessao-2026-000123",
"expiresInDays": 7,
"signers": [
{ "name": "Maria da Silva Souza", "email": "maria@exemplo.com.br", "cpf": "123.456.789-09", "order": 1 }
]
}')
REQ_ID=$(echo "$REQ" | jq -r '.data.id')
echo "$REQ" | jq '[.data.relationships.signers.data[].attributes | {email, status, signingUrl}]'Resposta prevista (ilustrativa):
[
{
"email": "maria@exemplo.com.br",
"status": "SENT",
"signingUrl": "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>"
}
][
{
"email": "maria@exemplo.com.br",
"status": "SENT",
"signingUrl": "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>"
}
]Três coisas acontecem nesta chamada: o original vai para o file-storage da organização, o documento é criado no motor, e cada signatário ganha um código opaco de 128 bits — no banco fica o SHA-256 dele e uma cópia cifrada, só para a API remontar o signingUrl. O cpf é opcional e só existe para a página mostrar ***.456.789-**: não vai ao motor e o número inteiro não é gravado. Sem expiresInDays, o link vale ESIGNATURE_SIGN_LINK_TTL_DAYS (30 dias por padrão).
5. Entregar o signingUrl ao signatário
O bloco não manda e-mail com o link — quem entrega é a sua aplicação: por e-mail próprio, WhatsApp ou na tela do cliente. Trate o link como segredo: ele não basta para assinar (falta o código), mas basta para pedir o código ao e-mail do signatário e para ler o documento. Não o grave em log nem em tíquete.
6. O signatário assina na página
O que ele vê, na ordem, e o que a página chama por trás:
| Passo | Na tela | Rota pública |
|---|---|---|
| Abrir | O termo em PDF, o nome e o CPF mascarados, o aceite e "Enviar código" | GET /e-signature/sign/:code e GET …/document.pdf |
| Aceitar | "Li e concordo com os termos deste documento" | — (vai junto da assinatura) |
| Código | "Enviar código" manda 6 dígitos ao e-mail, mostrado mascarado (ma•••@example.com); vale 10 min | POST …/otp |
| Conferir | "Confirmar" troca o código por um signToken de 30 min, de uso único | POST …/verify |
| Assinar | "Desenhar" ou "Digitar"; "Assinar documento" só acende com tudo feito | POST …/sign |
| Fim | "Documento assinado. Você já pode fechar esta página." | — |


Na chamada de "Assinar documento", o bloco aplica a assinatura no motor, que sela o PDF (PKCS#7, /ByteRange) com a imagem e uma linha de carimbo por signatário — nome, data UTC, IP e SHA-256 do original. Sendo o último signatário, na mesma chamada o bloco baixa o PDF selado e o certificado de conclusão, arquiva os dois no file-storage, move o envelope a COMPLETED e captura a evidência.
Para conferir o estado pelo lado do link, sem dado pessoal:
curl -s "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>/state" | jqcurl -s "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>/state" | jq7. Acompanhar pelos eventos
Cada passo deixa evento no stream iam-events, com IP e user-agent e sem o código, o OTP nem o CPF. No caminho feliz de um signatário só, na ordem:
esignature.signer.page_viewed
esignature.signer.viewed (só no primeiro acesso)
esignature.signer.otp_sent
esignature.signer.otp_verified
esignature.signer.terms_accepted
esignature.signer.signed
esignature.request.completed
esignature.request.evidence_capturedesignature.signer.page_viewed
esignature.signer.viewed (só no primeiro acesso)
esignature.signer.otp_sent
esignature.signer.otp_verified
esignature.signer.terms_accepted
esignature.signer.signed
esignature.request.completed
esignature.request.evidence_capturedÉ esignature.request.completed que a sua aplicação escuta para seguir a operação — foi assim que a cessão do Caso 6 fechou sozinha. Se o arquivamento falhar, sai esignature.request.archive_failed, e POST /requests/:id/refresh tenta de novo.
8. Conferir a evidência e baixar o PDF selado
curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
| jq '.data.attributes | {status, documentHash, hashAlgorithm, signatureLevel, evidenceCapturedAt}'curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
| jq '.data.attributes | {status, documentHash, hashAlgorithm, signatureLevel, evidenceCapturedAt}'Resposta prevista (ilustrativa):
{
"status": "COMPLETED",
"documentHash": "9b1f…c04e",
"hashAlgorithm": "sha256",
"signatureLevel": "SIMPLE",
"evidenceCapturedAt": "2026-10-17T14:02:11.000Z"
}{
"status": "COMPLETED",
"documentHash": "9b1f…c04e",
"hashAlgorithm": "sha256",
"signatureLevel": "SIMPLE",
"evidenceCapturedAt": "2026-10-17T14:02:11.000Z"
}documentHash é o SHA-256 do PDF selado. A evidência completa — hash do original, do PDF selado e do certificado, digitallySealed, IP e hora de cada signatário, e os ids dos arquivos arquivados (signedFileId, certificateFileId) — vem em meta.evidence, só leitura:
curl -s "$BASE/requests/$REQ_ID/evidence" -H "Authorization: Bearer $TOKEN" | jq '.meta.evidence'curl -s "$BASE/requests/$REQ_ID/evidence" -H "Authorization: Bearer $TOKEN" | jq '.meta.evidence'E as URLs do PDF assinado e do certificado de conclusão, por GET /requests/:id/download e GET /requests/:id/certificate (as duas só com COMPLETED; a URL expira, peça de novo quando precisar):
curl -s "$BASE/requests/$REQ_ID/certificate" -H "Authorization: Bearer $TOKEN" | jq -r '.downloadUrl'curl -s "$BASE/requests/$REQ_ID/certificate" -H "Authorization: Bearer $TOKEN" | jq -r '.downloadUrl'O
termo.pdfprecisa caber no limite de 1 MB do corpo da requisição, o que na prática significa um PDF de até cerca de 750 KB depois da codificação em base64. Para arquivos maiores, guarde no file-storage e usefileId(§11). Credenciais de staging conforme AMBIENTES.md.
Receitas
Assinar um documento gerado pelo Document Template
A cadeia completa: gerar a CCB, guardar o PDF e mandar assinar. São três building blocks e um único fio ligando os três — o businessId.
flowchart LR
DT["document-template<br/>renderiza a CCB da versão publicada"] -->|"PDF em base64"| FS["file-storage<br/>guarda o arquivo e devolve fileId"]
FS -->|fileId| ES["e-signature<br/>cria o envelope e os signatários"]
ES -->|"signingUrl por signatário"| P["provedor de assinatura"]
BID["businessId = proposta-2026-000481"] -.-> DT
BID -.-> ES1. Gerar o documento — ver o README do document-template.
PDF_B64=$(curl -s -X POST \
"https://document-template.bb.stg.catalisa.app/document-templates/api/v1/document-templates/$TPL_ID/render/pdf" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"variables": { ... }, "businessId":"proposta-2026-000481"}' \
| jq -r '.data.attributes.pdfBase64')PDF_B64=$(curl -s -X POST \
"https://document-template.bb.stg.catalisa.app/document-templates/api/v1/document-templates/$TPL_ID/render/pdf" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"variables": { ... }, "businessId":"proposta-2026-000481"}' \
| jq -r '.data.attributes.pdfBase64')O retorno é o PDF em base64. Confira que a variável não ficou vazia antes de seguir — a rota de PDF do document-template não está configurada em staging nem em produção hoje.
2. Guardar no file-storage e obter um fileId
FILE_ID=$(curl -s -X POST https://storage.bb.stg.catalisa.app/file-storage/api/v1/files \
-H "Authorization: Bearer $TOKEN" -F "file=@ccb.pdf" | jq -r '.data.id')
echo "$FILE_ID"FILE_ID=$(curl -s -X POST https://storage.bb.stg.catalisa.app/file-storage/api/v1/files \
-H "Authorization: Bearer $TOKEN" -F "file=@ccb.pdf" | jq -r '.data.id')
echo "$FILE_ID"Resposta prevista: um UUID, que é o que o e-signature aceita em fileId.
8f2c1a90-0000-0000-0000-0000000000008f2c1a90-0000-0000-0000-0000000000003. Mandar assinar, correlacionando pelo mesmo businessId
curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "CCB - Proposta 2026-000481",
"fileId": "'"$FILE_ID"'",
"businessId": "proposta-2026-000481",
"signers": [{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }]
}' | jq '.data.id'curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "CCB - Proposta 2026-000481",
"fileId": "'"$FILE_ID"'",
"businessId": "proposta-2026-000481",
"signers": [{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }]
}' | jq '.data.id'Resposta prevista: o identificador da solicitação de assinatura, que você guarda junto da sua operação.
3c8a1e77-0000-0000-0000-0000000000003c8a1e77-0000-0000-0000-000000000000Armadilhas.
- Use o mesmo
businessIdnos três building blocks. É ele que permite reconstruir a operação depois. - A rota de PDF do document-template não está configurada em staging nem em produção hoje. Verifique antes de montar esse fluxo.
- Prefira
fileIdafileBase64sempre que o arquivo já estiver na plataforma: evita o teto de 1 MB do corpo e evita trafegar o contrato duas vezes. - Guarde o identificador da solicitação de assinatura junto da sua operação. Sem ele, reencontrar o envelope depende de varrer a lista por
businessId.
Coletar assinatura de dois signatários em ordem
curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Contrato com avalista",
"fileId": "'"$FILE_ID"'",
"signers": [
{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 },
{ "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2 }
]
}' | jqcurl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Contrato com avalista",
"fileId": "'"$FILE_ID"'",
"signers": [
{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 },
{ "name": "João Souza", "email": "joao@exemplo.com.br", "order": 2 }
]
}' | jqArmadilhas.
- A ordem sequencial só é ativada quando algum signatário tem
ordermaior que 1. Com todos em 1 — ou semorder—, o envio é simultâneo. - O
emailé a chave de correlação com os eventos do provedor. Dois signatários com o mesmo e-mail quebram o acompanhamento: o estado será aplicado ao primeiro que a consulta encontrar. - No OpenSign local, o contato de cada signatário é criado por documento (nunca reaproveitado por e-mail).
- Sem
widgets, o OpenSign local põe um campo de assinatura por signatário na última página, em linhas de três acima do rodapé, e o rodapé leva uma linha de carimbo por signatário.
Posicionar campos de assinatura em página específica
{
"widgets": [
{ "type": "signature", "page": 8, "x": 90, "y": 610, "width": 180, "height": 55, "required": true },
{ "type": "date", "page": 8, "x": 300, "y": 610, "width": 120, "height": 30 },
{ "type": "checkbox", "page": 8, "x": 90, "y": 680, "label": "Li e concordo" }
]
}{
"widgets": [
{ "type": "signature", "page": 8, "x": 90, "y": 610, "width": 180, "height": 55, "required": true },
{ "type": "date", "page": 8, "x": 300, "y": 610, "width": 120, "height": 30 },
{ "type": "checkbox", "page": 8, "x": 90, "y": 680, "label": "Li e concordo" }
]
}Armadilhas.
- No OpenSign local, as coordenadas são pontos do PDF com origem no canto superior esquerdo da página (
ycresce para baixo); o bloco converte ao desenhar. - No OpenSign local,
signerIdé o e-mail do signatário. SemsignerId, o campo só vale quando há um signatário; com vários, quem não tem campo próprio recebe o padrão da última página. - No OpenSign local só os campos
signaturesão desenhados (a imagem da assinatura);text,dateecheckboxsão ignorados — data e IP vão no carimbo do rodapé.
Trocar a configuração padrão de provedor
Objetivo. Passar a usar uma nova conta no provedor sem interromper os envelopes em aberto.
flowchart LR
A["1. Criar a nova configuração<br/>POST /provider-configs"] --> B["2. Testar ANTES de promover<br/>POST /provider-configs/:id/test"]
B -->|"success: false"| Pare["Pare. Corrija a credencial<br/>e teste de novo"]
B -->|"success: true"| C["3. Promover<br/>POST /provider-configs/:id/set-default"]
C --> D["A antiga é desmarcada na mesma transação"]
D --> E["Envelopes já criados continuam na configuração antiga<br/>— o configId está gravado no envelope"]1. Criar a nova configuração
NEW_CFG=$(curl -s -X POST "$BASE/provider-configs" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"OpenSign Novo","providerType":"OPENSIGN","credentials":{ ... }}')
NEW_ID=$(echo "$NEW_CFG" | jq -r '.data.id')NEW_CFG=$(curl -s -X POST "$BASE/provider-configs" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"OpenSign Novo","providerType":"OPENSIGN","credentials":{ ... }}')
NEW_ID=$(echo "$NEW_CFG" | jq -r '.data.id')2. Testar ANTES de promover
curl -s -X POST "$BASE/provider-configs/$NEW_ID/test" -H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST "$BASE/provider-configs/$NEW_ID/test" -H "Authorization: Bearer $TOKEN" | jq{ "success": true, "message": "Connection successful" }{ "success": true, "message": "Connection successful" }3. Promover
curl -s -X POST "$BASE/provider-configs/$NEW_ID/set-default" -H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST "$BASE/provider-configs/$NEW_ID/set-default" -H "Authorization: Bearer $TOKEN" | jqA resposta traz a configuração com isDefault: true. As demais foram desmarcadas na mesma transação.
Armadilhas.
set-defaultdesmarca todas as outras na mesma transação. Não há janela com duas padrões, nem com nenhuma.- As solicitações já criadas continuam vinculadas à configuração antiga — o
configIdé gravado no envelope. Não exclua a configuração antiga enquanto houver envelope em aberto nela: cancelar, reenviar e baixar dependem dela. - Excluir a configuração é exclusão lógica. Os envelopes continuam apontando para a linha, e as operações continuam funcionando — mas a configuração some da listagem, o que confunde quem for investigar depois.
Diagnosticar uma solicitação que não sai
Objetivo. Separar problema de configuração, de credencial, de tamanho de arquivo e de provedor não implementado, na ordem que resolve mais rápido.
1. Listar as configurações da organização e ver qual é a padrão ativa
curl -s "$BASE/provider-configs" -H "Authorization: Bearer $TOKEN" \
| jq '[.data[] | {id, name: .attributes.name, tipo: .attributes.providerType,
padrao: .attributes.isDefault, ativa: .attributes.isActive}]'curl -s "$BASE/provider-configs" -H "Authorization: Bearer $TOKEN" \
| jq '[.data[] | {id, name: .attributes.name, tipo: .attributes.providerType,
padrao: .attributes.isDefault, ativa: .attributes.isActive}]'Resposta prevista — é aqui que se descobre que não há nenhuma com padrao: true e ativa: true:
[
{ "id": "…", "name": "OpenSign Homologação", "tipo": "OPENSIGN", "padrao": true, "ativa": true }
][
{ "id": "…", "name": "OpenSign Homologação", "tipo": "OPENSIGN", "padrao": true, "ativa": true }
]2. Exercitar a credencial contra o provedor
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jqcurl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jq{ "success": true, "message": "Connection successful" }{ "success": true, "message": "Connection successful" }3. Cruzar o sintoma com a causa
flowchart TD
S{"Qual foi o sintoma?"}
S -->|"404 ProviderConfig na criação"| C1["Nenhuma configuração isDefault e isActive<br/>→ rode set-default numa configuração ativa"]
S -->|"500 com not yet implemented"| C2["providerType DOCUSIGN ou ADOBESIGN<br/>→ só OpenSign e ZapSign funcionam, §15"]
S -->|"500 INTERNAL ao criar configuração"| C3["ESIGNATURE_CREDENTIAL_MASTER_KEY ausente<br/>ou fora do formato de 64 hexadecimais"]
S -->|"401 ou 403 vindos do provedor"| C4["Credencial errada ou expirada<br/>→ o teste do passo 2 isola isso"]
S -->|413| C5["Corpo acima de 1 MB<br/>→ use fileId em vez de fileBase64"]
S -->|"estado nunca sai de DRAFT ou SENT"| C6["ZapSign: webhook não chegou<br/>OpenSign local: ninguém assinou ainda<br/>→ POST /requests/:id/refresh"]Ordem de diagnóstico, da causa mais comum para a mais rara:
| Sintoma | Causa provável | O que fazer |
|---|---|---|
404 ProviderConfig na criação | Nenhuma configuração com isDefault e isActive | Rode set-default numa configuração ativa |
500 com "not yet implemented" | providerType DOCUSIGN ou ADOBESIGN | Só OpenSign e ZapSign funcionam (§15) |
500 INTERNAL ao criar configuração | ESIGNATURE_CREDENTIAL_MASTER_KEY ausente ou fora do formato | 64 caracteres hexadecimais; verifique o ambiente |
401 ou 403 vindos do provedor | Credencial errada ou expirada | POST /:id/test isola isso em uma chamada |
413 | Corpo acima de 1 MB | Use fileId em vez de fileBase64 |
Estado nunca muda de DRAFT/SENT | ZapSign: o webhook não chegou ou não foi configurado. OpenSign local: não há webhook; o estado muda quando o signatário age na página | POST /requests/:id/refresh reconsulta o provedor e concilia; no OpenSign local, olhe a trilha do signatário (page_viewed, otp_sent…) |
Personalizar a aparência da página, por configuração e por envelope
Objetivo. Pôr a marca da casa na página de assinatura — e, quando preciso, uma aparência diferente para um envelope só.
A página usa a mesma Appearance API do biometrics, em três camadas. Vale a mais específica, campo a campo; uma camada inválida é ignorada:
flowchart LR
E["appearance do envelope<br/>POST /requests"] --> R["Aparência da página"]
C["settings.appearance da configuração<br/>PATCH /provider-configs/:id"] --> R
P["Padrão Catalisa"] --> R
E -. "vence" .-> C
C -. "vence" .-> P1. Para todos os envelopes da organização, grave na configuração
curl -s -X PATCH "$BASE/provider-configs/$CFG_ID" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"settings": {
"senderName": "Financeira Exemplo",
"appearance": {
"mode": "auto",
"colors": { "primary": "#734B9C" },
"radius": 12,
"font": { "family": "inter" },
"logoFileId": "'"$LOGO_FILE_ID"'"
}
}
}'curl -s -X PATCH "$BASE/provider-configs/$CFG_ID" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"settings": {
"senderName": "Financeira Exemplo",
"appearance": {
"mode": "auto",
"colors": { "primary": "#734B9C" },
"radius": 12,
"font": { "family": "inter" },
"logoFileId": "'"$LOGO_FILE_ID"'"
}
}
}'O
PATCHsubstitui o objetosettingsinteiro (sóextUserIdeextUserOrganizationId, que são do bloco, são preservados). Leia a configuração antes e mande de volta o que já existe —allowedEmbedHosts,certificateTimeoutMs— junto com a mudança.
2. Para um envelope só, mande appearance na criação
curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Aditivo contratual",
"fileId": "'"$FILE_ID"'",
"signers": [{ "name": "Maria da Silva Souza", "email": "maria@exemplo.com.br" }],
"appearance": {
"mode": "dark",
"texts": { "pt-BR": { "heading": "Assine o aditivo", "done": "Pronto. O aditivo está assinado." } },
"redirectUrl": "https://app.exemplo.com.br/operacoes/123"
}
}'curl -s -X POST "$BASE/requests" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "Aditivo contratual",
"fileId": "'"$FILE_ID"'",
"signers": [{ "name": "Maria da Silva Souza", "email": "maria@exemplo.com.br" }],
"appearance": {
"mode": "dark",
"texts": { "pt-BR": { "heading": "Assine o aditivo", "done": "Pronto. O aditivo está assinado." } },
"redirectUrl": "https://app.exemplo.com.br/operacoes/123"
}
}'O que cada campo aceita:
| Campo | Valores |
|---|---|
mode | light, dark ou auto (segue o sistema do signatário) |
colors | primary, background, surface, text, danger, em hex de 6 dígitos |
radius | 0 a 32 |
font.family | system, inter, roboto, open-sans, lato, montserrat, source-sans |
logoFileId | UUID de um arquivo no file-storage da organização do envelope |
layout | card, fullscreen ou minimal |
texts | Por idioma (pt) ou locale (pt-BR): heading, intro, consent, done, declined, expired, invalid, cancelled, até 300 caracteres cada |
poweredBy | true ou false |
redirectUrl | Para onde a página vai depois de assinar. Só https:// |
Armadilhas.
- No envelope, a aparência é validada na criação: campo desconhecido ou valor fora da lista responde
400. Na configuração, não: umasettings.appearanceinválida é ignorada inteira na hora de montar a página, sem erro. Depois de gravar, abra um link de teste e confira. senderNamemora emsettings, não emappearance— é o nome no e-mail do código, não na página.

Reemitir um link travado
Objetivo. Devolver ao signatário um caminho para assinar quando o link dele travou.
Sintoma. A página diz "Por segurança, este link foi bloqueado. Peça um novo a quem enviou o documento." e a trilha tem esignature.signer.link_locked, com reason:
reason | O que aconteceu |
|---|---|
send_limit | O link gastou os 10 envios de código da vida dele |
attempt_limit | O link gastou as 15 conferências de código da vida dele |
Cinco erros seguidos de código travam por 15 minutos e destravam sozinhos (OTP_LOCKED); isso não precisa de reemissão. O travamento do link, sim — e reemitir é a única saída.
1. Reemitir o link de quem ainda não assinou
curl -s -X POST "$BASE/requests/$REQ_ID/resend" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "signerEmail": "maria@exemplo.com.br" }'curl -s -X POST "$BASE/requests/$REQ_ID/resend" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "signerEmail": "maria@exemplo.com.br" }'Sem signerEmail, vale para todos os signatários que ainda não assinaram nem recusaram. O link antigo morre na hora (esignature.signer.link_revoked, reason: resend), e o novo nasce com os tetos zerados e a validade do envelope (ou, sem ela, ESIGNATURE_SIGN_LINK_TTL_DAYS).
2. Pegar o link novo e entregar
curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
| jq -r '.data.relationships.signers.data[].attributes | select(.email=="maria@exemplo.com.br") | .signingUrl'curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
| jq -r '.data.relationships.signers.data[].attributes | select(.email=="maria@exemplo.com.br") | .signingUrl'Armadilhas.
- O bloco não manda o link novo por e-mail: com o OpenSign local, "reenviar" é emitir link novo. Entregar é com a sua aplicação.
- Antes de reemitir, olhe a trilha: dezenas de
otp_wrongvindas de um IP que não é o do cliente sugerem que o link vazou. Nesse caso, confirme o e-mail do signatário antes de entregar o novo. - Signatário que já assinou não ganha link novo: a página dele continua mostrando "Documento assinado".
Diagnosticar "documento indisponível"
Sintoma. A página abre sem o termo, e GET /e-signature/sign/:code/document.pdf responde 503 com DOCUMENT_UNAVAILABLE.
1. Ache o evento. Cada falha publica esignature.signer.document_unavailable na trilha, com o requestId e o signerId, e loga "documento do envelope indisponível para a página" com os mesmos campos. Nenhum dos dois leva dado do documento nem a URL.
2. Leia source e reason:
source · reason | Causa provável | O que fazer |
|---|---|---|
file-storage · download_url_refused (com code) | O file-storage não deu o endereço do arquivo. O mais comum: MODULE_FILE_STORAGE_URL ausente ou sem o prefixo /file-storage | Corrija a variável do serviço (§13) e reinicie. O boot acusa a variável ausente (erro) ou sem prefixo (aviso) |
file-storage ou engine · http_error (com status) | O endereço veio, mas o download falhou | O status é o que a origem (file-storage ou motor) respondeu ao download |
file-storage ou engine · unreachable (com err) | A origem do PDF não respondeu | Confira se o file-storage (ou o motor, quando source é engine) está no ar e alcançável pelo serviço |
engine · no_url | O envelope foi criado sem o original no file-storage, e o motor não deu endereço | Envelope criado com o file-storage desligado: reemita o envelope (§15) |
none · no_document | O envelope não tem documento | Envelope inconsistente: cancele e crie de novo |
3. Confirme pela página. Nos casos do file-storage, depois da correção, abra o link de novo: o termo aparece sem reemitir o link, porque o original já estava guardado e o código não mudou.
flowchart TD
S["503 DOCUMENT_UNAVAILABLE"] --> E["evento esignature.signer.document_unavailable"]
E --> Q{"source"}
Q -->|file-storage| F{"reason"}
F -->|download_url_refused| V["MODULE_FILE_STORAGE_URL<br/>ausente ou sem /file-storage"]
F -->|"http_error ou unreachable"| B["file-storage fora do ar<br/>ou arquivo apagado"]
Q -->|engine| G{"reason"}
G -->|no_url| R["original nunca foi guardado<br/>reemitir o envelope"]
G -->|"http_error ou unreachable"| M["motor fora do ar<br/>ou sem o documento"]
Q -->|"none · no_document"| N["envelope sem documento<br/>cancelar e recriar"]Trocar o PFX autoassinado por um certificado ICP-Brasil, sem código
Objetivo. Fazer o motor selar os PDFs com um certificado da casa emitido na ICP-Brasil (um e-CNPJ do tipo A1, que vem como arquivo PKCS#12), no lugar do PFX autoassinado de hoje.
O que muda e o que não muda. Muda o selo: um validador passa a reconhecer a cadeia do certificado que selou o PDF, em vez de acusar um certificado fora de cadeia confiável. Não muda o nível do signatário: o par de chaves continua sendo do operador do motor, não da pessoa que assinou, e o envelope continua com signatureLevel: SIMPLE (§14). Não muda o bloco: nenhuma variável do bb-e-signature, nenhuma configuração de provedor, nenhum envelope.
1. Obter o certificado. Um e-CNPJ A1 da empresa que opera o motor, como arquivo .pfx com a senha.
2. Trocar no motor. O motor recebe o certificado de selagem como PKCS#12 em base64 e a senha dele. Troque o PFX e a senha nos segredos que o roteiro de deploy do motor (repo do painel) lê, e reimplante o motor. O TLS mútuo entre o bloco e o motor é outro material e não é afetado.
3. Provar. Assine um envelope de teste até o fim e confira o PDF selado num validador — ou pela receita abaixo, se a organização tiver a conferência ligada.
Armadilhas.
- PDFs selados antes da troca continuam com o selo antigo. A troca não reprocessa nada.
- O certificado A1 vence (em geral em um ano). Anote o vencimento e troque antes, pelo mesmo roteiro.
- Não descreva a troca como "assinatura qualificada" em material comercial. É um selo ICP-Brasil do operador sobre uma assinatura simples.
O certificado de conclusão
O problema. Até 22/10/2026 o certificado de conclusão do OpenSign local saía em inglês ("Certificate of Completion"), com datas no fuso do usuário técnico e a "Organization" em branco. O originador era o usuário técnico do motor, com nome de uuid (Catalisa e-signature <uuid>), um e-mail técnico (esignature+<uuid>@catalisa.io) e o IP interno do runtime (172.17.0.1). É a prova que a mesa abre e que vai para uma disputa.
A solução. O motor usa o nosso modelo do certificado: docker/opensign/GenerateCertificate.js, no repositório do painel, que substitui o do OpenSign. O Dockerfile fixa o sha256 do original, e se o OpenSign mudar o arquivo o build para. O bloco manda o nome da casa ao motor (SenderName do documento) na criação do envelope.
| Campo | O que sai |
|---|---|
| Título e rótulos | pt-BR: "Certificado de conclusão", "Resumo", "ID do documento", "Nome do documento", "Hash do documento (SHA-256)", "Organização", "Enviado em", "Concluído em", "Signatários" |
| Datas | dd/MM/aaaa HH:mm:ss (horário de Brasília), seja qual for o fuso do usuário técnico |
| Organização | settings.senderName da configuração, senão o name dela (a mesma regra do e-mail do código) |
| Enviado em | a criação do envelope (o bloco cria e envia no mesmo ato) |
| Concluído em | a última assinatura |
| Originador | "Assinatura Catalisa", sem e-mail e sem IP |
| Cada signatário | nome, e-mail, visualizado em, assinado em, endereço IP e a imagem da assinatura: é a prova, e fica |
Texto longo encolhe até 10 pt e depois quebra a linha. Nome e e-mail de signatário nunca são cortados na borda.
Para conferir. Baixe o certificado de um envelope concluído (GET /requests/:id/certificate) e compare o SHA-256 do arquivo com o certificateSha256 da evidência (GET /requests/:id/evidence).
Certificados já emitidos não mudam: o PDF é gerado e arquivado na conclusão. Envelopes criados antes do bloco 0cda9ceb (staging e produção em 22/10/2026) não têm SenderName e saem com "Organização" em branco.
Prova em produção (22/10/2026): PJ real na credito-demo, motor
2fabe86f+ bloco0cda9ceb. Certificado de 93.774 B, em pt-BR, com o hash conferindo com a evidência.
Conferir a assinatura de um arquivo pelo verificador
Objetivo. Saber se um PDF, P7S ou XML que chegou de fora foi assinado com certificado reconhecido e não mudou desde então.
1. Ligar o envio a terceiro (uma vez por organização, papel ESIGNATURE_ADMIN)
curl -s -X PUT "$BASE/verification-settings" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "thirdPartyEnabled": true, "fileRetentionDays": 30 }' | jqcurl -s -X PUT "$BASE/verification-settings" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "thirdPartyEnabled": true, "fileRetentionDays": 30 }' | jqComeça desligado (source: DEFAULT) porque o arquivo vai ao Verificador de Conformidade. Sem isso, a conferência responde 403 THIRD_PARTY_DISABLED.
2. Conferir
curl -s -X POST "$BASE/verifications" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@contrato-social.pdf" -F "businessId=abertura-2026-0042" \
| jq '.data.attributes | {status, reasonCodes, fileHash, signatarios: [.report.signatures[].signer]}'curl -s -X POST "$BASE/verifications" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@contrato-social.pdf" -F "businessId=abertura-2026-0042" \
| jq '.data.attributes | {status, reasonCodes, fileHash, signatarios: [.report.signatures[].signer]}'Arquivo acima de 1 MB vai primeiro ao file-storage e entra por { "fileId": "…" } em JSON (até 10 MB). P7S ou XML com assinatura destacada pedem também o conteúdo (detachedFile ou detachedFileId).
3. Ler o resultado
status | Leitura |
|---|---|
VALID | Assinado com certificado reconhecido (ICP-Brasil, gov.br, Mercosul, AATL) e íntegro |
INVALID | Reprovado pelo verificador (por exemplo HASH_FAILURE: o arquivo mudou depois de assinado), sem assinatura (NO_SIGNATURE) ou assinado fora de raiz reconhecida (UNTRUSTED_ANCHOR) |
INDETERMINATE | Não deu para concluir — certificado vencido sem carimbo de tempo, por exemplo, ou o verificador não respondeu (PROVIDER_TIMEOUT, PROVIDER_UNAVAILABLE, PROVIDER_ERROR; esses não ficam em cache, chame de novo) |
4. Provar depois, sem o arquivo
HASH=$(sha256sum contrato-social.pdf | cut -d' ' -f1)
curl -s "$BASE/verifications/proof?fileHash=$HASH" -H "Authorization: Bearer $TOKEN" | jqHASH=$(sha256sum contrato-social.pdf | cut -d' ' -f1)
curl -s "$BASE/verifications/proof?fileHash=$HASH" -H "Authorization: Bearer $TOKEN" | jqArmadilhas.
- Ainda não há instância de produção do verificador (§15); em homologação usamos o servidor do LabSEC/UFSC.
- Um PDF selado pelo nosso motor com o PFX autoassinado não sai
VALID: o certificado não está numa raiz reconhecida. Isso não diz nada sobre a integridade dele — para o que o nosso motor selou, a prova é odocumentHashdo envelope. VALIDnão diz que quem assinou tinha poderes (companies) nem que é quem diz ser além do certificado (biometrics).
Integração com outros building blocks
O E-Signature é o elo do meio da cadeia de documentos da Catalisa. O document-template gera; o E-Signature coleta a assinatura; o data-extraction lê o documento que volta.
| Building block | Como se relaciona | Obrigatório |
|---|---|---|
| IAM | Emite o token e define o organizationId que isola configurações e envelopes | Sim |
| File Storage | Origem do documento a assinar (fileId) e destino do assinado | Não |
| Document Template | Gera o documento que será assinado | Não |
| Data Extraction | Lê o documento assinado ou o comprovante devolvido pelo cliente | Não |
| Webhooks Engine | Entrega os eventos esignature.* a sistemas externos do cliente | Não |
| Audit Trail | Registra quem criou, cancelou e baixou envelope | Não |
| Decision Platform | Orquestra a esteira que decide, gera o contrato e pede a assinatura | Não |
| Customers | Fornece nome e e-mail dos signatários | Não |
A cadeia de documentos, ponta a ponta
flowchart TD
BID["businessId = proposta-2026-000481<br/>o fio que liga os três"]
DT["Document Template<br/>gera a CCB da versão publicada"]
FS["File Storage<br/>guarda o PDF"]
ES["E-Signature<br/>cria o envelope e os signatários"]
PROV["Provedor de assinatura<br/>OpenSign"]
WH["Webhooks Engine<br/>avisa o sistema do cliente"]
AT["Audit Trail<br/>quem fez o quê"]
DT -->|PDF| FS
FS -->|fileId| ES
ES -->|"URL por signatário"| PROV
ES -->|"eventos esignature.*"| WH
PROV -->|"webhook do provedor"| ES
ES --> AT
BID -.-> DT
BID -.-> ESE na volta, quando o cliente devolve um documento ou manda um comprovante:
flowchart LR
FS2["File Storage<br/>documento recebido"] -->|fileId| DE["Data Extraction<br/>lê e devolve JSON"]
DE -->|"dados estruturados"| Est["de volta à esteira"]Este diagrama é o argumento comercial da Catalisa nesta família: gerar, assinar e ler são o mesmo problema visto de três ângulos. Quem monta essa cadeia com três fornecedores diferentes gasta a maior parte do esforço em amarrar identidade, isolamento por cliente e correlação entre eles — e depois descobre que o relatório "quais operações estão com contrato pendente" exige juntar três bases que não se conhecem.
Aqui as três peças já compartilham o token do IAM, o organizationId do tenant e o businessId da operação. O businessId é o fio: o mesmo identificador de proposta vai no documento gerado, na solicitação de assinatura e na extração do comprovante. Responder "o que já aconteceu com esta operação" é filtrar por um campo em três serviços, e não um projeto de integração.
Vale registrar a fronteira com honestidade: a cadeia está desenhada e as peças se encaixam pelo businessId, mas o encadeamento não é automático — não há orquestração pronta que gere, guarde e envie para assinar em uma chamada. Quem monta o fluxo é a sua aplicação, ou o decision-platform.
Conferência de assinatura, de dentro da plataforma. Um bloco que recebe documento assinado usa a fachada ESignatureVerificationFacade (src/shared/facades/esignature-verification.facade.ts): verifyFile({ organizationId, fileId, detachedFileId?, businessId? }) e getProof({ organizationId, fileHash }), local no monolito e HTTP no standalone. A conferência depende do file-storage (entrada por fileId e cópia temporária) e do audit-trail (a prova). Ela completa o companies (quem tem poderes) e o biometrics (quem é a pessoa) — não os substitui.
Configuração e operação
Variáveis de ambiente
| Variável | Descrição | Obrigatória | Padrão |
|---|---|---|---|
ESIGNATURE_CREDENTIAL_MASTER_KEY | Chave AES-256-GCM para cifrar credenciais de provedor. Exatamente 64 caracteres hexadecimais (32 bytes). Gere com openssl rand -hex 32 | Sim, para usar o módulo | — |
DATABASE_URL | PostgreSQL. O building block usa o schema esignature | Sim | — |
REDIS_URL | Redis, usado pelo limite de taxa e pelo publicador de eventos | Sim | — |
JWT_SECRET | Segredo HS256 compartilhado com o IAM. Mínimo 44 caracteres | Sim | — |
S3_* | Endpoint, credenciais e bucket, para resolver fileId | Sim, se usar fileId | — |
MODULE_FILE_STORAGE_URL | Endereço do bloco file-storage com o prefixo do módulo: http://<host-interno-do-file-storage>:3000/file-storage. Sem o /file-storage no fim, toda chamada dá 404. É por ele que o original do envelope é guardado, a página lê o PDF e o PDF selado e o certificado são arquivados. Ausente: a página responde 503 DOCUMENT_UNAVAILABLE e nada é arquivado. O boot (standalone) acusa no log a variável ausente (erro) ou sem o prefixo (aviso) | Sim, para OpenSign local | — |
OPENSIGN_ALLOWED_HOSTS | Onde o motor OpenSign local pode estar (vírgula). Entrada scheme://host:porta libera exatamente esse esquema, host e porta (IPv6 entre colchetes: http://[::1]:18190); hostname nu libera só https na porta padrão; http só com entrada explícita com porta (staging e produção: https://<host-interno-do-motor>:8090; com as OPENSIGN_TLS_* ligadas, http é recusado). A master key e o token do portão só vão para essas origens. Sem a variável, toda configuração OPENSIGN é recusada (400) | Para usar OpenSign | — |
OPENSIGN_TLS_CA_PEM_B64 | CA (PEM em base64) que assinou o certificado do motor. O provider fixa essa CA, não a do sistema. Vem do roteiro de emissão de TLS do motor (repo do painel) | Para o motor com mTLS | — |
OPENSIGN_TLS_CLIENT_CERT_PEM_B64 | Certificado de cliente do bloco (CN=bb-e-signature, clientAuth), PEM em base64. Vai em toda chamada ao motor (REST, upload e download); sem ele o motor recusa o handshake TLS | Para o motor com mTLS | — |
OPENSIGN_TLS_CLIENT_KEY_PEM_B64 | Chave do certificado de cliente, PEM em base64. As três vêm juntas ou nenhuma: conjunto parcial derruba toda configuração OPENSIGN (erro no boot e em cada chamada), nunca fala sem certificado. Com elas, baseUrl http é recusado (ENGINE_TLS_REQUIRES_HTTPS). São do serviço, nunca da ProviderConfig da casa | Para o motor com mTLS | — |
PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT | off aceita webhook não verificável com aviso; on recusa | Não | off |
DEPLOYMENT_MODE | monolith ou standalone | Não | monolith |
PORT | Porta em standalone | Não | 3000 (a topologia expõe 3014) |
ESIGNATURE_ITI_VERIFIER_URL | URL de uma instância do Verificador de Conformidade (/report é acrescentado). Sem padrão: os termos do ITI proíbem apontar para o domínio do ITI. Homologação: https://pbad.labsec.ufsc.br/verifier-hom | Para conferir assinatura | — (sem ela, PROVIDER_NOT_CONFIGURED) |
ESIGNATURE_ITI_VERIFIER_TIMEOUT_MS | Tempo limite de uma chamada; passou, INDETERMINATE / PROVIDER_TIMEOUT | Não | 30000 |
ESIGNATURE_VERIFICATION_MAX_BYTES | Teto do arquivo conferido | Não | 10485760 (10 MB) |
ESIGNATURE_VERIFICATION_IDEMPOTENCY_HOURS | Janela em que o mesmo SHA-256 reaproveita a conferência respondida pelo verificador. 0 desliga | Não | 24 |
ESIGNATURE_VERIFICATION_PURGE_ENABLED | Limpeza da cópia temporária vencida (só em standalone, main.ts). Ligada por padrão: a prova está na trilha | Não | true |
ESIGNATURE_VERIFICATION_PURGE_INTERVAL_HOURS | Intervalo da limpeza | Não | 6 |
ESIGNATURE_PUBLIC_URL | Origem pública do bloco (ex.: https://esignature.bb.catalisa.app). Compõe o signingUrl da página hospedada | Sim, para envelope OpenSign | — (sem ela, 503 ao criar) |
ESIGNATURE_SIGN_LINK_TTL_DAYS | Validade do link quando o envelope não tem expiresInDays | Não | 30 |
SMTP_HOST / SMTP_PORT | SMTP do código de 6 dígitos (o SMTP da casa, TLS implícito na 465) | Sim, em produção | — / 465 |
SMTP_USER / SMTP_PASS | Credencial SMTP | Se o servidor exigir | — |
SMTP_FROM | Remetente | Não | no-reply@catalisa.io |
A chave mestra é lida direto de
process.envno momento da cifragem, e não no boot. Consequência prática: o serviço sobe normalmente sem ela e só falha na primeira operação que precise cifrar ou decifrar, comINTERNAL. Confira a presença dela no deploy; não confie na subida limpa como sinal.
Deploy: migrations do schema esignature
20261017120000_esignature_archived_filescria duas colunas emsignature_documents; o verificador de objetos do Launch (scripts/launch/lib.sh,objetos_do_sql) as enxerga e confere.20261017125000_esignature_signer_signingsó fazALTER TYPE … ADD VALUE IF NOT EXISTS 'SIGNING'. O verificador não enxergaADD VALUE, então o preflight a mostra como "indeterminada" — e oscripts/launch/1-migrar.sha aplica sozinho (db execute+resolve). Como o catálogo de objetos não cobre o enum, confira depois do deploy empg_enum:SELECT e.enumlabel FROM pg_enum e JOIN pg_type t ON t.oid = e.enumtypid JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname = 'esignature' AND t.typname = 'SignerStatus' AND e.enumlabel = 'SIGNING';Uma linha = aplicada. Nenhuma = o bloco não consegue gravar
SIGNINGe a assinatura pela página falha.Migration mergeada nunca se edita — nem comentário: o checksum muda e o ledger dos ambientes que já a aplicaram passa a divergir. Correção vira migration nova.
Dependências de infraestrutura
| Dependência | Para quê |
|---|---|
| PostgreSQL | Schema esignature — configurações, envelopes, signatários, documentos e eventos |
| Redis | Limite de taxa e publicação de eventos |
| S3 ou MinIO | Resolver fileId em conteúdo, via URL assinada |
| Bloco file-storage | Guardar o original do envelope, servir o PDF à página e arquivar o PDF selado e o certificado (MODULE_FILE_STORAGE_URL) |
| IAM | Verificação do token; o organizationId vem do claim assinado |
| Instância do provedor | O motor opensign-local, alcançável pela malha com TLS mútuo (§7) |
Limites e quotas
| Limite | Valor | Onde |
|---|---|---|
| Corpo da requisição | 1 MB | applyCommonMiddleware — é o teto prático de fileBase64 |
| Espera por chamada ao OpenSign | 30 segundos | Cliente HTTP do provider |
| Upload ao OpenSign | 100 MB | Limite do cliente de upload, inalcançável pelo teto de 1 MB da API |
title | 255 caracteres | Zod |
message | 2.000 caracteres | Zod |
expiresInDays | 1 a 365 | Zod |
| Signatários | mínimo 1, sem teto declarado | Zod |
| Limite de taxa global | 10.000 requisições por minuto por IP, quando ligado | RATE_LIMIT_GLOBAL_MAX |
| Arquivo conferido | 10 MB por padrão; por multipart, o corpo inteiro cabe em 1 MB | ESIGNATURE_VERIFICATION_MAX_BYTES, applyCommonMiddleware |
| Chamada ao verificador | 30 s por padrão | ESIGNATURE_ITI_VERIFIER_TIMEOUT_MS |
| Retenção da cópia do arquivo | 1 a 365 dias por organização; padrão da casa 30 | PUT /verification-settings |
Eventos publicados
| Evento | Quando |
|---|---|
esignature.request.created | Solicitação criada, por qualquer das duas rotas de criação |
esignature.request.cancelled | Cancelamento concluído |
esignature.request.completed | Webhook completed processado; no OpenSign local, último signatário na página do bloco ou refresh que achou o documento concluído |
esignature.request.declined | Webhook declined processado |
esignature.signer.viewed | Webhook viewed processado |
esignature.signer.signed | Webhook signed processado; no OpenSign local, assinatura aplicada pela página do bloco (com IP e agente do signatário) |
esignature.request.signed | OpenSign local: uma assinatura aplicada e ainda faltam outras (PARTIALLY_SIGNED) |
esignature.signature.refused | OpenSign local: assinatura recusada antes do motor, com reason (INVALID_IMAGE, IMAGE_TOO_LARGE, ALREADY_SIGNED, OUT_OF_ORDER, REQUEST_CANCELLED, BUSY…) |
esignature.signature.failed | OpenSign local: o motor ou o bloco falhou ao aplicar a assinatura, com code |
esignature.request.archive_failed | OpenSign local: concluído, mas o PDF selado ou o certificado não foi arquivado (stage); o refresh tenta de novo |
esignature.signer.document_unavailable | A página de assinatura não conseguiu ler o PDF do envelope. Leva source (file-storage, engine, ou none quando o envelope não tem documento) e reason (no_document, download_url_refused com code, no_url, http_error com status, unreachable com err (o nome do erro)). Nenhum dado do documento nem a URL |
esignature.verification.completed | Conferência concluída — inclusive INDETERMINATE por tempo ou erro do provedor. Leva fileHash, status, reasonCodes, report (mascarado) e reportDigest. É a prova permanente: fixada na poda do audit-trail |
esignature.verification.reused | A janela de idempotência devolveu uma conferência anterior |
esignature.verification.refused | Recusa antes de chamar o provedor, com code |
esignature.verification.file_purged / .file_purge_failed | A cópia temporária saiu (ou não saiu) do file-storage |
esignature.verification-settings.changed / .refused | Admin mudou (ou tentou mudar com valor inválido) o envio a terceiro ou a retenção, com antes/depois |
Os eventos de webhook dependem do provedor (§15). esignature.request.viewed existe no catálogo de tipos mas não é publicado por nenhum caminho de código.
Catálogo de erros
O envelope de erro é { "error": "<código>", "message": "<texto>", "details": <opcional> }.
| Status | Código | Significa | O que fazer |
|---|---|---|---|
400 | VALIDATION | Corpo reprovado, origem de arquivo ambígua, estado incompatível com a operação | Leia a message |
401 | — | Token ausente, inválido ou expirado | Renove no IAM |
403 | — | Falta a permissão exigida, ou o token não carrega organizationId | Confira o papel e a organização |
404 | NOT_FOUND | Configuração, solicitação ou signatário inexistente, excluído, ou de outra organização | Confira o identificador. "De outra organização" e "inexistente" são a mesma resposta, de propósito |
409 | CONFLICT | Nome de configuração repetido na organização | Escolha outro |
413 | — | Corpo acima de 1 MB | Use fileId |
429 | — | Limite de taxa estourado | Aplique recuo exponencial |
500 | INTERNAL | Provedor não implementado; chave mestra ausente; falha ao baixar do S3; erro do provedor | Verifique a message e os logs |
Erros vindos do provedor são traduzidos: 404 vira NOT_FOUND, 401 vira UNAUTHORIZED, 403 vira FORBIDDEN, 400 e 422 viram VALIDATION, 409 vira CONFLICT, e o resto vira INTERNAL com o contexto na mensagem.
Observabilidade.
GET /e-signature/healthresponde a sonda de disponibilidade. É a rota usada pelohealthcheckda pilha.POST /provider-configs/:id/testé a sonda que importa de verdade: ela exercita a credencial contra o provedor. Rode-a periodicamente — credencial expirada é a falha mais comum e a mais silenciosa.- Todo webhook recebido é gravado em
esignature_webhook_events, processado ou não, com o corpo original empayloade o motivo da falha emerror. É a melhor fonte para investigar divergência de estado. Não há rota que a exponha (§15); o acesso é por consulta ao banco. - Assinatura de webhook não verificada gera aviso no log com o nome do provedor e o motivo.
Segurança e compliance
Isolamento entre tenants
Isolamento entre tenants. O organizationId vem do claim assinado do JWT e nunca do corpo. As quinze rotas autenticadas passam pelo middleware local requireOrganization, que devolve 403 quando o claim está ausente. Toda consulta de repositório inclui organizationId na cláusula WHERE, junto com deletedAt: null. Um envelope de outra organização responde 404, não 403: a distinção permitiria descobrir a existência do recurso.
A rota de webhook é a única exceção, e por construção: o provedor não tem token da plataforma. Ela deriva a organização a partir do :configId do caminho, e não de nada que o chamador afirme sobre si. Essa rota deve ficar atrás de lista de IPs permitidos na borda — ver a §15 sobre o estado atual dela.
Como as credenciais do provedor são protegidas
Como as credenciais do provedor são protegidas. Esta é a parte que a ESIGNATURE_CREDENTIAL_MASTER_KEY resolve.
sequenceDiagram
autonumber
participant Cli as Cliente
participant ES as E-Signature
participant PG as PostgreSQL
participant Prov as Provedor
Cli->>ES: POST /provider-configs com credentials em claro
ES->>ES: serializa em JSON
ES->>ES: sorteia um IV de 12 bytes
ES->>ES: cifra em AES-256-GCM com a chave mestra do serviço
ES->>PG: grava no formato iv:authTag:ciphertext, tudo em hexadecimal
ES-->>Cli: 201 SEM o campo credentials — não existe caminho que o exponha
Note over ES,Prov: mais tarde, em cada operação real
ES->>PG: lê o valor cifrado
ES->>ES: decifra em memória — GCM detecta qualquer alteração do texto cifrado
ES->>Prov: usa a credencial e a descartaO que você envia em credentials — a URL da instância, a chave mestra do Parse Server ou o token de sessão — é serializado em JSON e cifrado com AES-256-GCM antes de tocar o banco. O vetor de inicialização tem 12 bytes e é sorteado a cada operação; a etiqueta de autenticação tem 16 bytes. O valor gravado tem o formato iv:authTag:ciphertext, todos em hexadecimal, e o modo GCM garante que qualquer alteração do texto cifrado seja detectada na decifragem em vez de produzir lixo silencioso.
A chave mestra é validada como exatamente 64 caracteres hexadecimais — 32 bytes, o tamanho de uma chave de 256 bits. Ela é do serviço, não do tenant: uma única chave cifra as credenciais de todas as organizações. Isso a torna um ativo crítico, e a consequência operacional é direta: guarde-a em SOPS, nunca em .env versionado, e trate um vazamento dela como comprometimento das credenciais de todos os clientes. Não há rotação de chave implementada — trocar a chave hoje inutiliza todas as credenciais já gravadas.
O campo cifrado nunca volta em nenhuma resposta. A função que monta o corpo de resposta da configuração simplesmente não inclui credentials, então não existe caminho de serialização que o exponha, nem por acidente. Também não há rota que devolva as credenciais em claro para conferência — se você precisa saber qual credencial está gravada, a resposta é rotacioná-la.
Qual nível de assinatura este building block produz
Qual nível de assinatura este building block produz. A resposta honesta começa por uma distinção: o building block não produz assinatura nenhuma. Ele orquestra o provedor configurado, e o nível é o que aquele provedor entrega.
Com o único provedor implementado hoje — o OpenSign auto-hospedado —, o nível produzido é assinatura eletrônica simples. Essa conclusão não vem do material de divulgação do projeto, que não se pronuncia sobre conformidade legal; ela vem da leitura do código de assinatura dele, e a razão é específica: o certificado usado para selar o PDF é do operador do servidor, não do signatário. É um selo de servidor, o mesmo para todos os documentos daquela instalação.
Isso importa porque a lei exige o contrário para os níveis superiores. O art. 6º, parágrafo único da MP nº 2.200-2/2001 determina que "o par de chaves criptográficas será gerado sempre pelo próprio titular e sua chave privada de assinatura será de seu exclusivo controle, uso e conhecimento". E o art. 4º, II, "b" da Lei nº 14.063/2020 exige, para a assinatura avançada, que o signatário opere sob controle exclusivo dos dados de criação. Um selo de servidor não atende nenhum dos dois — mesmo que o operador instale um certificado ICP-Brasil na instalação. Vale dizer isso com todas as letras porque é uma confusão comum e cara.
flowchart TD
Q["De quem é a chave privada que sela o documento?"] --> S["Do operador do servidor<br/>selo de servidor, o mesmo para todos os documentos"]
Q --> T["Do próprio signatário, sob controle exclusivo dele"]
S --> N1["Nível I — assinatura simples<br/>é o que o OpenSign entrega hoje"]
T --> N2["Nível II — avançada<br/>art. 4º, II, b da Lei 14.063/2020"]
T --> N3["Nível III — qualificada<br/>certificado ICP-Brasil, MP 2.200-2, art. 10, § 1º"]
S -.->|"instalar um certificado ICP-Brasil no servidor NÃO muda isso"| N1
MP["MP 2.200-2/2001, art. 6º, parágrafo único:<br/>a chave privada é de controle exclusivo do titular"] -.-> TOs três níveis, com o texto da lei
Os três níveis, com o texto da lei
O art. 4º da Lei nº 14.063/2020 classifica:
| Nível | Definição legal, resumida | O OpenSign atende? |
|---|---|---|
| I — simples | Permite identificar o signatário e anexa ou associa dados a outros dados eletrônicos do signatário | Sim |
| II — avançada | Usa certificado não-ICP ou outro meio de comprovação, admitido pelas partes, com associação unívoca ao signatário, dados sob controle exclusivo dele e detecção de qualquer modificação posterior | Não — falta o controle exclusivo e falta a validação de identidade que o Decreto nº 10.543/2020, art. 5º, II exige |
| III — qualificada | Usa certificado digital nos termos do art. 10, § 1º da MP nº 2.200-2 — ou seja, ICP-Brasil | Não |
Uma nuance de escopo que quase todo material de mercado erra
Uma nuance de escopo que quase todo material de mercado erra. A Lei nº 14.063/2020 rege, pelo art. 1º, assinaturas "em interações com entes públicos, em atos de pessoas jurídicas e em questões de saúde" — e o art. 2º, parágrafo único exclui expressamente processos judiciais e a interação entre particulares. A classificação em três níveis virou a referência técnica de fato do setor inteiro, e é assim que a usamos aqui, mas ela não rege, por si, um contrato privado entre duas empresas. Esse contrato segue a MP nº 2.200-2 e o Código Civil.
O que sustenta a assinatura simples, e qual é o preço dela
O que sustenta a assinatura simples, e qual é o preço dela. O art. 10 da MP nº 2.200-2 tem dois parágrafos que precisam ser lidos juntos:
- O § 1º dá aos documentos assinados com certificação da ICP-Brasil presunção legal de veracidade em relação aos signatários.
- O § 2º ressalva que a MP "não obsta a utilização de outro meio de comprovação da autoria e integridade de documentos em forma eletrônica, inclusive os que utilizem certificados não emitidos pela ICP-Brasil, desde que admitido pelas partes como válido ou aceito pela pessoa a quem for oposto o documento".
| Com certificação ICP-Brasil (§ 1º) | Sem ICP-Brasil, meio aceito pelas partes (§ 2º) | |
|---|---|---|
| Efeito legal | Presunção de veracidade em relação aos signatários | Válido entre as partes que o admitiram |
| Quem tem o ônus da prova | Quem contesta precisa desconstituir | Quem invoca precisa provar autoria e integridade |
| É o que este building block entrega hoje? | Não | Sim |
A diferença entre os dois é o ônus da prova. Com ICP-Brasil, presume-se verdadeiro e cabe a quem contesta desconstituir. Sem ICP-Brasil, quem invoca o documento precisa provar autoria e integridade. Por isso o material comercial da Catalisa não pode dizer que a assinatura simples "tem a mesma validade jurídica". A formulação correta é: é juridicamente válida entre as partes que a admitiram, com ônus probatório distinto.
O ativo legal que muda a conversa: o art. 784, § 4º do CPC
O ativo legal que muda a conversa: o art. 784, § 4º do CPC. A Lei nº 14.620/2023, art. 34, acrescentou ao Código de Processo Civil:
"§ 4º Nos títulos executivos constituídos ou atestados por meio eletrônico, é admitida qualquer modalidade de assinatura eletrônica prevista em lei, dispensada a assinatura de testemunhas quando sua integridade for conferida por provedor de assinatura."
Ou seja: assinatura simples serve para constituir título executivo eletrônico, e as duas testemunhas do art. 784, III caem — desde que a integridade seja conferida pelo provedor de assinatura. Essa condição é técnica e é onde o produto precisa entregar: hash do documento, trilha e detecção de adulteração.
E a CCB, especificamente
E a CCB, especificamente. A Cédula de Crédito Bancário não precisa de testemunhas nem de assinatura qualificada. Ela é título executivo por força de lei própria — art. 28 da Lei nº 10.931/2004 —, enquadrando-se no art. 784, XII do CPC ("os demais títulos aos quais, por disposição expressa, a lei atribuir força executiva"), e não no inciso III, que é o das testemunhas. O art. 29, VI exige apenas a assinatura do emitente, e o § 5º do mesmo artigo, incluído pela Lei nº 13.986/2020, admite que ela seja eletrônica "desde que garantida a identificação inequívoca de seu signatário". A Lei nº 13.986/2020 também acrescentou o art. 27-A, que autoriza a emissão da CCB sob forma escritural.
A trilha da assinatura, e o que este building block preserva hoje
A trilha da assinatura, e o que este building block preserva hoje. Até setembro de 2026 a trilha probatória ficava só no provedor. Com a captura de evidência (POST /requests/:id/evidence, automática na conclusão) e com o motor local e a página hospedada (outubro de 2026), o bloco passou a guardar a prova do lado dele.
flowchart LR
subgraph Op["Trilha operacional"]
O1["quem foi convidado: nome e e-mail"]
O2["a ordem exigida entre os signatários"]
O3["quando cada um recebeu, viu, assinou ou recusou"]
O4["cada passo na página: código, aceite, recusa"]
end
subgraph Pr["Trilha probatória"]
P1["SHA-256 do original e do PDF selado"]
P2["IP e hora de cada signatário"]
P3["PDF selado e certificado de conclusão no file-storage"]
P4["evidência da página: aceite, fator, hash da imagem e do documento"]
end
Op --> Uso["acompanhamento e auditoria interna"]
Pr --> Prova["prova de integridade — art. 784, § 4º do CPC"]| O que o building block guarda | Onde |
|---|---|
| Quem foi convidado a assinar — nome e e-mail | signers |
| A ordem exigida entre os signatários | signers.order |
| Quando cada um recebeu, visualizou, assinou ou recusou | signers.sentAt, viewedAt, signedAt, declinedAt |
| O motivo da recusa | signers.declineReason |
| SHA-256 do PDF assinado e nível da assinatura | signature_requests.documentHash, hashAlgorithm, signatureLevel |
| Hash do original, do PDF selado e do certificado; IP e hora de cada signatário; ids dos arquivos arquivados | signature_requests.evidence |
| O PDF selado e o certificado de conclusão | file-storage da organização (signedFileId, certificateFileId) |
| Cada passo na página hospedada, com IP e user-agent | Eventos esignature.signer.* no stream iam-events |
| Todo evento recebido de provedor com webhook, com o corpo original | esignature_webhook_events.payload |
| Evidência | Com o OpenSign local, o building block captura? |
|---|---|
| Hash SHA-256 do documento assinado | Sim — documentHash, conferido contra o hash que o motor informa (engineHashMatches) |
| Hash do original | Sim — na evidência e no carimbo do rodapé do PDF |
| IP de cada signatário | Sim — a página repassa o IP de quem assinou ao motor; vai para o carimbo e para a evidência |
| Certificado de conclusão | Sim — arquivado no file-storage; a URL ainda não vem na evidência (§15) |
| Segundo fator | Sim — código de 6 dígitos por e-mail, feito pela página do bloco (factor: email_otp) |
| Carimbo de tempo confiável (RFC 3161) | Não — os horários são do relógio do servidor, sem terceiro de confiança |
A leitura prática: com o OpenSign local, a prova de integridade fica do lado do bloco, verificável sem recorrer ao provedor: compare o SHA-256 de um arquivo com o documentHash do envelope. Isso não quer dizer que a condição do art. 784, § 4º esteja cumprida: se o motor operado pela plataforma se enquadra como "provedor de assinatura" do § 4º é ponto a confirmar com o jurídico. O que continua faltando, de todo modo, é o carimbo de tempo de terceiro. Com o ZapSign, a evidência vem do provedor e é gravada no envelope do mesmo jeito.
O que dizer e o que não dizer a um cliente
O que dizer e o que não dizer a um cliente
| Situação | A assinatura simples basta? |
|---|---|
| Contrato entre partes privadas que aceitaram o meio eletrônico | Em geral sim, com base no art. 10, § 2º da MP nº 2.200-2 — com ônus probatório de quem invoca o documento |
| Constituir título executivo eletrônico | Sim, pelo art. 784, § 4º do CPC — desde que a integridade seja conferida pelo provedor |
| Emitir CCB | Sim — a lei não exige testemunha nem ICP-Brasil, apenas identificação inequívoca do signatário |
| Emissão de nota fiscal eletrônica, salvo pessoa física e MEI | Não — o art. 5º, § 2º, III da Lei nº 14.063 exige qualificada |
| Ato de transferência e registro de bem imóvel | Não, em regra — o art. 5º, § 2º, IV exige qualificada. A Lei nº 14.382/2022 abriu caminho para a avançada em registros públicos, condicionado a ato do CNJ |
| Receituário de medicamento sob controle especial e atestado médico | Não — o art. 13 da Lei nº 14.063 exige qualificada |
| Ato em que a autoria pode ser contestada em juízo | Depende inteiramente da robustez da prova que o provedor produz |
Se o seu caso exige assinatura avançada ou qualificada, o caminho é contratar um provedor que a ofereça — e hoje isso significa não usar este building block, porque nenhum provedor com suporte a ICP-Brasil está implementado (§15). Nunca afirme a cliente que este building block confere validade jurídica. Ele confere rastreabilidade operacional; a validade decorre do provedor, do meio aceito pelas partes e do ato praticado. Consulte o jurídico antes de usá-lo em ato de maior exigência.
Nota de método: as citações desta seção foram conferidas contra o texto das normas em 2026-08-16. Circula no mercado jurisprudência do STJ sobre contrato eletrônico como título executivo sem testemunhas; não conseguimos verificar nenhum acórdão em fonte primária e por isso não citamos nenhum. Não use precedente de segunda mão em material comercial.
O motor de produção: PFX autoassinado e TLS mútuo
Decisão do dono (19/10/2026): em produção, o motor sela os PDFs com um PFX autoassinado nosso. O nível é o simples, com o segundo fator por código no e-mail feito pela página do bloco. Trocar por um e-CNPJ ICP-Brasil da casa é só trocar o PFX do motor (pelo roteiro de deploy do motor, no repo do painel), sem mudar código. Vale a ressalva da seção acima: um certificado ICP-Brasil no servidor muda o selo, não o nível do signatário — o par de chaves continua sendo do operador.
A tranca do motor é o TLS mútuo (§7). Os negativos foram provados no Bun real do serviço bb-e-signature, em staging (17/10) e em produção (19/10):
| Tentativa | Resultado |
|---|---|
| Cliente certo, CA fixada | 200 |
| Sem fixar a CA (pool do sistema) | UNABLE_TO_VERIFY_LEAF_SIGNATURE |
| CA de outro emissor fixada | UNABLE_TO_VERIFY_LEAF_SIGNATURE |
| Certificado de cliente de outra CA | ECONNRESET (o motor recusa o handshake) |
| Host pelo IP (SAN errado) | ERR_TLS_CERT_ALTNAME_INVALID |
Em staging, a prova do motor pela malha cobriu também o lado HTTP: HTTP puro → 400; sem certificado → CERTIFICATE_REQUIRED; certificado sem portão → 403; certificado e portão → 200 em TLS 1.3.
Dados pessoais, exclusão lógica e superfície de exposição
Dados pessoais. O building block guarda nome e e-mail de cada signatário, o título do documento e o vínculo com a operação. O conteúdo do documento não é armazenado aqui — ele fica no file-storage e no provedor. E-mail e nome são dados pessoais sob a LGPD. O envio ao provedor é uma operação de tratamento por operador: se o provedor for de nuvem, e especialmente se estiver no exterior, isso exige base legal, contrato de operador e atenção às regras de transferência internacional. Com provedor auto-hospedado, esse trânsito não existe.
Exclusão lógica. Configurações e solicitações usam deletedAt. Excluir não apaga signatários, documentos nem eventos de webhook — o histórico sobrevive à remoção, que é o que auditoria exige. Atender a pedido de eliminação da LGPD exige expurgo manual (§15).
Superfície de exposição. O signingUrl de cada signatário e o downloadUrl do documento assinado são URLs com poder: a primeira permite assinar, a segunda permite ler o contrato assinado. Elas aparecem em respostas da API e não devem ir para log de aplicação, para sistema de tíquete nem para mensagem de chat. A evidência devolvida pela API não traz token de link de terceiro (o token do documento e dos signatários do ZapSign é guardado só como referência SHA-256 truncada, e o que já estava gravado sai filtrado).
Conferência de assinatura: consentimento, retenção e o que ela prova
- Enviar o arquivo a um terceiro é decisão da organização, e começa desligado. Sem linha em
signature_verification_settings, a resposta dizsource: DEFAULT— padrão da casa, não alterado. Ligar e desligar exigemESIGNATURE_ADMINe deixam antes/depois na trilha. - O arquivo é guardado temporariamente; o hash, para sempre. A cópia vai ao file-storage da organização com prazo (
fileRetentionDays, padrão 30 dias) e é apagada pela limpeza automática. O SHA-256 e o relatório normalizado vão para a trilha (esignature.verification.completed), encadeada e ancorada peloaudit-trail, e a poda de retenção da trilha mantém a linha mais recente de cada arquivo.GET /verifications/proofprova a conferência pela trilha, sem o arquivo. - CPF e CNPJ não aparecem em claro em lugar nenhum: o verificador é chamado no modo mascarado, o mapper mascara de novo (inclusive o CPF/CNPJ que o certificado ICP-Brasil carrega no nome), o serviço varre o relatório antes de gravar e o log não recebe relatório.
- O que
VALIDprova: que o arquivo foi assinado com certificado reconhecido (ICP-Brasil, gov.br, Mercosul, AATL) e não mudou desde então. Não prova identidade além do certificado, não confere documento nem rosto, não diz se o signatário tinha poderes e não lê o conteúdo. Detalhe em docs/signature-verification.md. - Dependência de um software governamental. O Verificador é do ITI, mantido pelo LabSEC/UFSC, gratuito e sem garantia de disponibilidade ("indisponibilidades poderão ocorrer sem aviso prévio"). Os termos proíbem integrar apontando para o domínio do ITI: em produção, a instância tem de ser nossa (ou contratada).
Limitações conhecidas
| Limitação | Impacto | Situação |
|---|---|---|
| DocuSign e Adobe Sign só existem no enum | São aceitos na criação da configuração e falham com 500 na primeira operação. OpenSign (self-hosted, nível simples) e ZapSign (desde 10/09/2026; níveis simples, avançado e qualificado por signatário) são os provedores que funcionam | Conhecido |
| ZapSign: sem posicionamento de campos, sem reenvio, sem template pela API | widgets são ignorados (o signatário assina no fluxo do ZapSign), resend responde 400 (compartilhe signers[].signingUrl) e from-template responde 400. O ZapSign não assina webhooks: a verificação é pelo cabeçalho X-Webhook-Secret com o segredo em settings.webhookSecret, registrado no webhook da conta ZapSign (POST /api/v1/user/company/webhook/ com headers); sem segredo configurado, vale a política PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT | Por design / Conhecido |
A rota de webhook respondia 404 a todo evento (corrigido em 10/09/2026) | Resolvia a configuração com organização vazia. Agora resolve pelo id (findByIdForWebhook) e escopa pela organização da configuração; o corpo chega ao provedor como bytes (rawBody) para verificação de assinatura. Continua valendo: OpenSign não assina webhooks | Corrigido |
| Não havia rota para reconsultar o estado no provedor (corrigido em 10/09/2026) | POST /requests/:id/refresh chama getSignatureRequest e concilia estado, conclusão e signatários. Serve quando o webhook foi perdido ou nunca configurado | Corrigido |
| O OpenSign local não tem webhook | O motor não envia evento nenhum; webhook para uma configuração OpenSign responde 400. O estado vem da página de assinatura do bloco e de POST /requests/:id/refresh | Por design |
| Nenhum provedor com ICP-Brasil | O nível de assinatura obtido hoje é o simples. Atos que exijam assinatura qualificada não são atendidos (§14) | Depende de implementar um provedor que suporte |
| OpenSign local: nível simples | O motor sela o PDF com o certificado da instância (em staging e em produção, PFX autoassinado), não com ICP-Brasil: signatureLevel = SIMPLE. A evidência guarda o hash do original, do PDF selado e do certificado de conclusão, e o IP de cada signatário | Por design |
| OpenSign local: o motor não autentica o signatário | IsEnableOTP=false: quem autentica o signatário é a página de assinatura do bloco, pelo código de acesso. O applySignature confia que quem o chama já fez isso | Por design |
| Produção sela com PFX autoassinado | Decisão do dono em 19/10/2026: nível simples + código por e-mail. Quem conferir o PDF selado num validador verá um certificado fora de cadeia confiável | Por decisão; troca por e-CNPJ ICP-Brasil = trocar o PFX do motor, sem código |
| Certificado de conclusão: o que já foi emitido não muda | O modelo pt-BR vale para envelopes concluídos a partir de 22/10/2026. Os anteriores ficam em inglês. "Organização" depende de settings.senderName da configuração; as configurações criadas pelo instalador do painel antes da correção dele mostram o nome técnico até a reinstalação (§11, "O certificado de conclusão") | Por design |
| A evidência não traz a URL do certificado | evidence.certificateUrl fica null no OpenSign local de propósito: a URL assinada expira e não serve como registro. A evidência guarda certificateFileId, e o certificado se baixa por GET /requests/:id/certificate (desde 22/10/2026), que assina uma URL nova a cada chamada. Antes disso não havia rota, e a recaptura (POST /requests/:id/evidence) perdia signedFileId/certificateFileId — também corrigido | Por design |
| Envelope criado com o file-storage desligado não guarda o original | Sem MODULE_FILE_STORAGE_URL na criação, o original não vai para o file-storage e a página não mostra o PDF (DOCUMENT_UNAVAILABLE). Aconteceu só em staging, antes de 17/10/2026; reemitir o envelope resolve | Conhecido |
| Código só por e-mail | O segundo fator da página hospedada é e-mail (SMTP). WhatsApp entra como outra implementação de OtpSender | Roadmap |
| O nível de assinatura não é modelado | Não há campo que registre qual nível da Lei nº 14.063 foi produzido em cada documento. O produto não consegue declarar nem auditar isso por solicitação | Roadmap |
| O OpenSign não emite carimbo de tempo confiável | Os horários da trilha são do relógio do servidor, sem autoridade de carimbo de tempo (RFC 3161). Para prova de anterioridade, isso é fraco | Limitação do provedor |
| A licença do OpenSign não é AGPL-3 pura | O arquivo de licença abre exceção para um diretório cujo termo de licença não existe no repositório, e o GitHub classifica o projeto como NOASSERTION. Somado à cláusula de rede da AGPL-3, exige análise jurídica antes de uso comercial | Pendente de avaliação jurídica |
| Corpo limitado a 1 MB | fileBase64 só comporta arquivo de cerca de 750 KB depois da codificação. O cliente do provedor aceita 100 MB, limite inalcançável pela API. Use fileId | Por design do middleware comum; ajustável na infraestrutura |
| Criar configuração não valida credencial | Uma credencial errada, ou um providerType não implementado, é aceita e só falha depois. Sempre chame POST /:id/test | Por design; o teste existe para isso |
EXPIRED nunca é gravado | O estado existe no enum e é mapeado a partir do provedor, mas nenhum caminho do código o persiste. Envelope vencido continua no último estado conhecido | Roadmap |
| OpenSign local: reenviar não manda e-mail | POST /requests/:id/resend emite um link novo para quem ainda não assinou e mata o anterior, mas o bloco não envia nada: a aplicação entrega o signingUrl novo (§11, "Reemitir um link travado") | Por design |
OpenSign local: sem from-template | Sem o app web não há template no motor; POST /requests/from-template responde 400. Gere o PDF (por exemplo no document-template) e crie a solicitação a partir do arquivo | Por design |
| Sem rota para ler os eventos de webhook | esignature_webhook_events é gravada mas não exposta. Investigar divergência exige consulta ao banco | Roadmap |
| Sem rotação da chave mestra | Trocar ESIGNATURE_CREDENTIAL_MASTER_KEY inutiliza todas as credenciais já cifradas. Não há procedimento de recifragem | Roadmap |
Permissões só no papel ADMIN | ESIGNATURE_ADMIN não está atribuída a nenhum papel intermediário no catálogo padrão do IAM. O papel DOCUMENT_OPERATOR recebe CREATE, READ e DELETE, mas não ADMIN — ou seja, ele não consegue configurar provedor | Configuração pendente no IAM |
| Sem retenção nem expurgo automatizado | Nome e e-mail de signatário ficam indefinidamente. Atender pedido de eliminação da LGPD é processo manual | Roadmap |
| Conferência: não há instância de produção do verificador | O ITI não oferece API de produção para integração e proíbe apontar para o domínio dele; o antigo verificador.staging.iti.br responde 301. Em homologação usamos o servidor do LabSEC/UFSC; produção exige subir o .war do verificador (decisão em aberto) | Pendente de infraestrutura |
| Conferência: multipart limitado a 1 MB | O corpo passa pelo limite comum. Arquivo maior entra por fileId (até 10 MB) | Por design do middleware comum |
| Conferência: o resultado envelhece | Um VALID de hoje pode ser INDETERMINATE amanhã (certificado vence sem carimbo de tempo). A janela de idempotência (24 h) devolve o resultado anterior; para reconferir antes, use ESIGNATURE_VERIFICATION_IDEMPOTENCY_HOURS menor | Por design |
| Conferência: sem comparação com o CPF esperado | O relatório traz o documento mascarado; o bloco ainda não responde "assinou quem eu esperava?" | Roadmap |
| Conferência: sem tela | Só API e fachada; nenhuma tela do app, do desktop ou do backoffice mostra a conferência ainda | Roadmap |
| Conferência: purga só em standalone | A limpeza da cópia temporária sobe no main.ts do bloco, como nos outros blocos; no monolito não roda | Por design |
Perguntas frequentes
Qual nível de assinatura eu obtenho com este building block?
Depende do provedor da configuração. Com o OpenSign local (o motor da página hospedada), assinatura eletrônica simples, com segundo fator por código no e-mail — o envelope grava signatureLevel: SIMPLE. O motivo é técnico: o certificado que sela o PDF é do operador do motor, não do signatário, e tanto o art. 6º, parágrafo único da MP nº 2.200-2/2001 quanto o art. 4º, II, "b" da Lei nº 14.063/2020 exigem que os dados de criação da assinatura estejam sob controle exclusivo do signatário para caracterizar nível superior. Com o ZapSign, o nível vem do provedor por signatário (simples, avançado ou qualificado, conforme o modo de autenticação usado), e o envelope fica com o mais fraco deles. Leia a §14 inteira antes de responder a um cliente, e envolva o jurídico se o ato for de maior exigência.
A assinatura feita na página hospedada tem validade jurídica?
Sim, como assinatura eletrônica simples — e é preciso dizer exatamente isso, sem arredondar. A base é o art. 10, § 2º da MP nº 2.200-2/2001: meio de comprovação de autoria e integridade fora da ICP-Brasil vale "desde que admitido pelas partes como válido ou aceito pela pessoa a quem for oposto o documento". A diferença para a ICP-Brasil é o ônus da prova: sem a presunção do § 1º, quem invoca o documento precisa provar autoria e integridade. Para isso o bloco guarda o aceite, o código conferido no e-mail do signatário, o IP e a hora de cada um, o hash do original e do PDF selado e o certificado de conclusão (§14).
O código por e-mail fortalece a prova de autoria, mas não muda o nível que o bloco registra: no OpenSign local o envelope continua SIMPLE. Há quem classifique a assinatura com código por e-mail como avançada pela Lei nº 14.063/2020 — o mapper do ZapSign, por exemplo, lê assim o que o provedor informa —, mas lembre do escopo dessa lei (§14: ela rege interações com entes públicos, atos de pessoas jurídicas e saúde, e exclui a interação entre particulares). Não prometa "avançada" a cliente sem o jurídico.
O que muda se o motor passar a selar com um certificado ICP-Brasil?
Muda o selo, não o nível. Com um e-CNPJ ICP-Brasil da casa no motor, um validador reconhece a cadeia do certificado que selou o PDF, em vez de acusar um certificado fora de raiz reconhecida — o documento fica mais fácil de conferir por terceiros. Mas o par de chaves continua sendo do operador, não do signatário, então a assinatura de cada pessoa continua simples e o envelope continua SIMPLE. A troca é só do certificado do motor, sem código (§11, "Trocar o PFX autoassinado por um certificado ICP-Brasil"). Assinatura qualificada de verdade exige o certificado do próprio signatário — hoje, só por um provedor que a ofereça.
Assinatura simples serve para um contrato virar título executivo?
Sim, e este é o ponto legal mais forte do produto. O art. 784, § 4º do CPC, incluído pela Lei nº 14.620/2023, admite qualquer modalidade de assinatura eletrônica para títulos executivos constituídos por meio eletrônico, e dispensa as duas testemunhas quando a integridade for conferida por provedor de assinatura. A condição é técnica, e com o OpenSign local a prova fica do lado do bloco: o SHA-256 do PDF selado (documentHash), o hash do original, o IP de cada signatário e o certificado de conclusão arquivado no file-storage (§14). Mas não afirme que a condição está cumprida: se o motor operado pela plataforma se enquadra como "provedor de assinatura" do § 4º é ponto a confirmar com o jurídico. O que ainda falta, de todo modo, é carimbo de tempo de terceiro (RFC 3161): os horários são do relógio do servidor.
Preciso de duas testemunhas na CCB?
Não. A CCB é título executivo por força do art. 28 da Lei nº 10.931/2004, enquadrando-se no art. 784, XII do CPC — não no inciso III, que é o dispositivo das testemunhas. O art. 29, VI exige apenas a assinatura do emitente e, se houver, do garantidor, e o § 5º admite que ela seja eletrônica desde que garantida a identificação inequívoca do signatário.
Vocês suportam DocuSign?
Não hoje. O tipo existe no schema e a configuração é aceita, mas a primeira operação real falha com "not yet implemented". A camada de abstração está pronta — uma implementação nova é uma classe que atende oito métodos —, e é isso que está pronto. A capacidade, não. Não anuncie multi-provedor como disponível.
Por que a rota é /e-signature/api/v1/esignature/...?
Porque o basePath do app usa hífen e o ponto de montagem dos routers não usa. É feio e é real. Copie do §9.
O status da minha solicitação não muda. O que houve?
Depende do provedor. No OpenSign local não há webhook: o estado muda quando o signatário age na página. Se nada mudou, olhe a trilha do signatário — sem esignature.signer.page_viewed, ele nunca abriu o link (confira se a sua aplicação entregou o signingUrl); com otp_sent e sem otp_verified, o código não chegou ou não foi digitado (veja a pergunta sobre o e-mail). No ZapSign, o estado vem do webhook; se ele se perdeu ou nunca foi configurado, POST /requests/:id/refresh reconsulta o provedor e concilia.
Onde ficam as credenciais do provedor?
Cifradas em AES-256-GCM na coluna credentials, com a chave ESIGNATURE_CREDENTIAL_MASTER_KEY. Elas não voltam em nenhuma resposta e não há rota que as devolva em claro. Se você precisa saber o que está gravado, o caminho é rotacionar. A chave mestra é do serviço e cifra as credenciais de todos os tenants — guarde-a em SOPS.
Posso usar fileBase64 para um contrato de 5 MB?
Não. O corpo da requisição é limitado a 1 MB, o que dá cerca de 750 KB de arquivo depois da codificação em base64. Guarde o arquivo no file-storage e use fileId — é o caminho recomendado de qualquer forma, porque evita trafegar o contrato duas vezes.
Como garanto que o documento assinado é o mesmo que enviei?
Pelo hash. Com o OpenSign local, a evidência do envelope guarda o SHA-256 do original que você enviou e o do PDF selado (documentHash), e o carimbo no rodapé do PDF selado repete o hash do original. Para conferir um arquivo guardado, calcule o SHA-256 dele e compare com o documentHash. O selo PKCS#7 (/ByteRange) também acusa qualquer alteração depois da assinatura num leitor de PDF.
O signatário precisa se autenticar de alguma forma além do link?
Com o OpenSign local, sim: o link sozinho não assina. A página exige o código de 6 dígitos enviado ao e-mail do signatário (válido por 10 minutos), e só o signToken da conferência libera assinar ou recusar. Quem receber o link encaminhado consegue ler o documento e pedir um código — mas o código vai para o e-mail do signatário, não para quem abriu. Ainda assim, trate o signingUrl como segredo. Com o ZapSign, a autenticação é a do fluxo do provedor.
Qual a diferença entre o template daqui e o do Document Template?
São coisas diferentes com o mesmo nome. POST /requests/from-template usa um template cadastrado na instância do provedor de assinatura. O document-template é um building block separado que gera o documento antes de ele chegar aqui. O fluxo normal é: o document-template gera o PDF, você o guarda no file-storage, e o e-signature o envia por fileId.
O que acontece se eu excluir uma configuração com envelopes em aberto?
A exclusão é lógica, então a linha continua no banco e os envelopes continuam funcionando — cancelar, reenviar e baixar seguem operando. O efeito é que a configuração some da listagem, o que atrapalha quem for investigar depois. Evite excluir antes de encerrar os envelopes.
Preciso de uma instância OpenSign própria?
Para a página hospedada, o bloco fala com um motor OpenSign local — na plataforma Catalisa ele já está no ar em staging e em produção, atrás de TLS mútuo (§7). Isso tem um lado bom que vale explicitar no comercial: com ele, o contrato nunca sai da nossa infraestrutura, o que elimina uma transferência de dado pessoal a terceiro. A alternativa sem motor é o ZapSign, de nuvem, com o fluxo e a marca do provedor.
O que o signatário vê?
Uma página no domínio do bloco, com a marca da casa: o título do documento, o nome e o CPF mascarados (***.456.789-**), o termo em PDF (lido na própria página, com "Baixar o PDF"), "Li e concordo com os termos deste documento", o envio e a conferência do código, e o campo para desenhar ou digitar a assinatura. "Não vou assinar" recusa, com um motivo de 3 a 500 caracteres, depois de conferir o código. O e-mail do código diz quem pediu a assinatura (settings.senderName). Os estados finais têm tela própria: assinado, recusado, expirado, cancelado e link inválido. As telas estão na galeria do topo desta página e na §10.
E se o e-mail com o código não chega?
Primeiro, a caixa de spam: o remetente é o SMTP_FROM do serviço (por padrão no-reply@catalisa.io). "Enviar código" pode ser pedido de novo depois de 60 s, até 10 vezes na vida do link — no décimo primeiro, o link trava e só reemitindo (§11). Na trilha:
| Evento | Leitura |
|---|---|
esignature.signer.otp_sent | O bloco entregou o e-mail ao servidor de envio (o endereço vai mascarado no evento). Se não chegou, o problema está depois: spam, caixa cheia ou endereço errado |
esignature.signer.otp_failed com send_failed | O servidor de envio recusou. A página diz "Não foi possível enviar o código agora. Tente de novo em instantes." |
esignature.signer.otp_failed com channel_not_configured | Produção sem SMTP_HOST: nenhum código sai. Corrija o serviço (§13) |
esignature.signer.otp_refused com resend_wait | Pediu de novo antes dos 60 s |
Se o endereço do signatário está errado, não há como trocá-lo no envelope: cancele e crie outro com o e-mail certo. Hoje o código só vai por e-mail; WhatsApp está no roadmap (§15).
Como ficam os dados pessoais (LGPD)? O CPF é guardado?
O CPF inteiro, não. signers[].cpf é opcional, só serve para a página mostrar ***.456.789-**, não vai ao motor e é gravado já mascarado. O bloco guarda nome e e-mail do signatário, o título do documento e, nos eventos da página, IP e user-agent — todos dados pessoais. O código do link fica como hash (e cifrado, para a API remontar o signingUrl); o código do e-mail, só como hash. Nenhum evento carrega o código, o OTP nem o CPF, e o único evento que cita o e-mail (otp_sent) o traz mascarado. O documento fica no file-storage da organização, e com o motor local não sai da nossa infraestrutura. O que falta: não há expurgo automático, e um pedido de eliminação é processo manual (§15).
Dois signatários podem ter o mesmo e-mail?
Tecnicamente o schema não impede, mas não faça isso. A correlação entre os eventos do provedor e o signatário é feita pelo e-mail — com e-mails repetidos, a atualização de estado vai para o primeiro registro encontrado e o acompanhamento fica errado sem avisar.
O bloco confere assinatura ICP-Brasil de um arquivo que eu recebi?
Sim, desde 01/10/2026: POST /verifications com o PDF, P7S ou XML. Antes, um admin da organização precisa ligar o envio a terceiro (PUT /verification-settings), porque o arquivo vai ao Verificador de Conformidade. O resultado é VALID, INVALID ou INDETERMINATE, nunca "provavelmente válido".
Por que deu INDETERMINATE num documento que abre normal no validar.iti.gov.br?
Os motivos mais comuns: certificado vencido sem carimbo de tempo (OUT_OF_BOUNDS_NO_POE), PDF sem controle de atualização incremental, ou o verificador não respondeu (PROVIDER_TIMEOUT, PROVIDER_UNAVAILABLE, PROVIDER_ERROR). Os dois últimos não ficam em cache: chame de novo.
Depois que a cópia do arquivo expira, ainda consigo provar que conferimos?
Sim. Calcule o SHA-256 do arquivo e chame GET /verifications/proof?fileHash=. A resposta vem da trilha de auditoria, com data, resultado, relatório e a posição na cadeia; a integridade da cadeia é verificável pela rota /verify do audit-trail.
Isso substitui a biometria ou a análise de poderes?
Não. A conferência diz que o arquivo foi assinado com certificado reconhecido e não mudou. Quem é a pessoa é o biometrics; se ela podia assinar pela empresa é o companies.
Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md