Catalisa.Building Blocks
Catálogo/Documentos/E-Signature

E-Signature

Beta

Coleta de assinatura eletrônica em documento, com trilha de eventos por signatário

24
Endpoints
7
Entidades
3
Provedores
Tenant
Escopo
3014
Porta
2026-01
Desde

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.

Para quem é
  • 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
Substitui
  • 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
O que não é
  • 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
O que dá para fazer

34 endpoints em 5 recursos.

Explorar a API →

Telas

o que o usuário vê

Toque numa tela para ampliar.

Página de assinatura
Página de assinaturaO link do signatário abre no domínio do bloco, com a marca do tenant. O termo em PDF, o nome e o CPF mascarados, o aceite, o código por e-mail e o campo de assinatura, numa página só. Dados fictícios.
Página de assinatura
Página de assinaturaO link do signatário abre no domínio do bloco, com a marca do tenant. O termo em PDF, o nome e o CPF mascarados, o aceite, o código por e-mail e o campo de assinatura, numa página só. Dados fictícios.
Assinatura digitada no celular
Assinatura digitada no celularA mesma página no celular, no modo escuro, com a assinatura digitada. Dados fictícios.
Código confirmado no celular
Código confirmado no celularNo celular, depois de conferir o código de 6 dígitos, a página libera desenhar ou digitar a assinatura. Dados fictícios.
Primeiro acesso no celular
Primeiro acesso no celularO que o signatário vê ao abrir o link no celular, antes do código. "Assinar documento" só acende depois do aceite, do código conferido e da assinatura feita. Dados fictícios.
Documento assinado
Documento assinadoO estado final, que é também o que um segundo acesso ao mesmo link mostra.
Documento assinado
Documento assinadoO estado final, que é também o que um segundo acesso ao mesmo link mostra.
01

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.

AtributoValor
Identificadore-signature
CategoriaDocumentos
EscopoTenant (exige organizationId no token em todas as rotas, exceto a de webhook)
Porta (standalone)3014
Path alias@e-signature
Prefixo HTTP/e-signature
StatusBeta desde 2026-01
Depende dePostgreSQL (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õesESIGNATURE_ADMIN, ESIGNATURE_CREATE, ESIGNATURE_READ, ESIGNATURE_DELETE

02

O problema

negócio

O 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.


03

Proposta de valor

negócio
AntesDepois
O código chama a API de um provedor específicoO provedor é uma configuração por organização, cifrada no banco
Uma conta do provedor compartilhada por todos os clientesCada organização configura a própria credencial, isolada e rotacionável
"Está enviado" é tudo que você sabeEstado por signatário: pendente, enviado, visualizado, assinado, recusado
Contrato circula como anexo de e-mailO arquivo vem do file-storage por identificador e não trafega a cada chamada
Trocar de fornecedor é reescrever a integraçãoA 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.


04

Casos de uso reais

negócio

Caso 1 — Uma financeira coleta assinatura de devedor e avalista em ordem Cenário ilustrativo

Contexto

Financeira de crédito pessoal com garantia de terceiro. Cada operação exige a assinatura do devedor e, depois dela, a do avalista.

A dor

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.

A solução com o BB

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ário
O resultado

A 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

Contexto

Plataforma B2B que atende dezenas de empresas clientes, cada uma com preferência e contrato próprios com fornecedores de assinatura.

A dor

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.

A solução com o BB

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)"]
O resultado

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

Contexto

Operação de originação com cerca de 400 contratos por mês e três pessoas acompanhando o retorno das assinaturas.

A dor

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.

A solução com o BB

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"]
O resultado

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

Contexto

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 dor

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"]
A solução

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 resultado

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

Contexto

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.

A dor

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.

A solução com o BB

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
O resultado

"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).

Contexto

Na antecipação de recebíveis da CBP, cada cessão termina num termo que o cedente precisa assinar antes de o dinheiro sair.

A dor

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.

A solução com o BB

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.

Página de assinatura aberta pelo cedente: o PDF, o aceite, o código por e-mail e o campo de assinatura
Página de assinatura aberta pelo cedente: o PDF, o aceite, o código por e-mail e o campo de assinatura

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 aceite
O resultado

Na prova de 17/10/2026 em staging, com e-mail real:

PassoO que se viu
Código por e-mailChegou em 4 s
PDF seladoCom /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ãoSozinho, 57 s depois da assinatura, com envelopeId e a hora do aceite gravados na operação
LinkA 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

Contexto

Uma financeira aprova a proposta, gera a CCB a partir de um modelo e precisa da assinatura do tomador antes de liberar o dinheiro.

A dor

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 solução com o BB

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"]
O resultado

"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

Contexto

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.

A dor

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.

A solução com o BB

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ência
O resultado

A 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.


05

Mercado e diferenciais

negócio

Panorama: 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érioCatalisa E-SignatureDocuSignClicksignD4SignZapSignAutentiqueOpenSign
NaturezaCamada de orquestraçãoProvedorProvedorProvedorProvedorProvedorProvedor auto-hospedável
Assina documentosNão — delega ao provedorSimSimSimSimSimSim
Entrada publicada (2026-08-16)Em definiçãoR$ 45/mêsR$ 39/mêsR$ 39,90/mêsGrátis até 3 docs; R$ 39,90/mêsGrátis até 10 docs; R$ 99/mêsSem custo por documento
Preço de API público—R$ 2.560 a R$ 24.520/anoIncluso desde o plano de entradaNão publicadoA partir do plano intermediárioTarifa por evento publicada em reais—
Certificado ICP-BrasilDepende do provedorSim, mas só nos planos sob cotaçãoSimSimÉ AC credenciada pelo ITISim — A1, A3 e nuvemNão
Nível da Lei 14.063 que declara produzirO do provedor configuradoNão declara por planoAlega cobrir os trêsNão declaraNão declaraDeclara avançada (art. 4º, II)Não declara — o código indica simples
Troca de provedor sem reescreverSim, é o pontoNão se aplicaNão se aplicaNão se aplicaNão se aplicaNão se aplicaNão se aplica
Credencial isolada por clienteSim, cifrada por organizaçãoVocê implementaVocê implementaVocê implementaVocê implementaVocê implementaVocê implementa
Estado por signatárioSim, tabela própriaSimSimSimSimSimSim
Documento fica na sua infraestruturaSim, se o provedor for auto-hospedadoNãoNãoNãoNãoNãoSim
Assinatura de webhook verificávelDepende do provedor (§15)SimSim, HMACNão documentadoSimSimNã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

  1. 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.
  2. 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.
  3. Envelope e signatário têm estados independentes. SignatureRequest tem oito estados; Signer tem cinco. Isso permite o estado intermediário PARTIALLY_SIGNED, que é onde a maioria dos contratos de crédito com avalista realmente vive.
  4. 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.


06

Modelo de cobrança e ROI

negócio

Quem 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"| Cli

Precificaçã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.

DriverPor quê
Solicitações de assinatura criadasCada 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çãoO provedor cria um contato e um conjunto de campos por signatário, e a maioria cobra por isso
Tamanho do documentoO arquivo é carregado em memória em base64 antes de subir ao provedor
Consultas de estadoEnquanto 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-hospedadoDocuSignClicksignZapSignAutentique
Base de cálculoPrecificação em definição; sem custo por documentoPor usuário emissor, mais franquia de envio por APIPor faixa de documentos, com excedentePor faixa, com faixa gratuita e recursos avulsosDocumentos ilimitados no plano profissional
Ordem de grandeza mensal do provedorSó a infraestrutura da instânciaCentenas de reais por usuário, mais contrato de API a partir de R$ 2.560/anoDezenas a centenas de reais, conforme a faixaDezenas de reais, mais avulsos por recursoR$ 99/mês, mais eventos avulsos
Custo por documento excedenteZeroConsumo de franquiaR$ 2,40 a R$ 6,90Conforme planoTarifa por evento publicada
ICP-Brasil disponívelNãoSim, sob cotaçãoSimSimSim
Você opera o provedorSimNãoNãoNãoNã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 contaO que se ganhaO que ressalvar
Tempo entre aprovar e liquidarDias viram horas; o ganho é proporcional ao ticket, não ao número de contratosDepende de o acompanhamento funcionar — hoje o webhook não está funcional (§15)
Custo de troca de fornecedorA troca vira configuração, e o poder de negociação deixa de ser todo do fornecedorValor 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.


07

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"| R3

Caminho 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
    end

Atençã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 verifyWebhookSignature retornavam true incondicionalmente, 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 de PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENT: com off (padrão), o webhook é aceito e um aviso é registrado; com on, 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.create cifra e grava sem chamar o provedor. Uma credencial errada, ou um providerType não implementado, é aceita e só falha na primeira solicitação real. Existe POST /provider-configs/:id/test exatamente 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=true e RevokedAt no documento (o signPdf do motor recusa documento recusado), e o mapper lê RevokedAt como CANCELLED. 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/resend responde 400 para 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) e GET /requests/:id/download devolve a URL assinada dessa cópia. Para os outros provedores, segue devolvendo a URL do provedor.
  • O arquivo por fileId passa 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):

  1. recusa o que não pode ser assinado e publica esignature.signature.refused com 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 tem order > 1), provedor sem a capacidade;
  2. 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;
  3. dentro da trava, relê o envelope e o signatário: se o envelope ficou DECLINED, CANCELLED, EXPIRED ou COMPLETED enquanto a chamada esperava, recusa com o motivo (REQUEST_DECLINED…); PARTIALLY_SIGNED e COMPLETED só são gravados a partir de um status aberto (update condicional) — uma recusa que chega durante a chamada ao motor nunca é sobrescrita;
  4. 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; chama functions/signPdf com X-Signer-Ip (só um endereço IP literal — sem ele, a trilha gravaria o endereço do portão). Se o signPdf falhar ou estourar o tempo, o bloco não conclui "não assinou": relê o documento até ver a entrada Signed do signatário ou o prazo vencer. Viu → SIGNED (reconciliado); confirmou que não → volta ao estado anterior; não conseguiu ler o motor → fica SIGNING (503, SIGNATURE_UNCONFIRMED) e a próxima tentativa ou o refresh reconcilia;
  5. 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ão esignature.request.completed sai uma vez mesmo com a página e o refresh concorrendo; 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:

reasonQuando
INVALID_IMAGE / IMAGE_TOO_LARGENão é PNG / IHDR acima de 2000×1000 ou mais de 1 MB
REQUEST_NOT_FOUND / SIGNER_NOT_FOUND / SIGNER_NOT_IN_PROVIDEREnvelope ou signatário inexistente, ou sem referência no motor
ALREADY_SIGNED / SIGNER_DECLINEDO signatário já assinou / recusou
REQUEST_COMPLETED / REQUEST_CANCELLED / REQUEST_DECLINED / REQUEST_EXPIREDEnvelope fechado
OUT_OF_ORDEREnvelope em ordem e alguém antes ainda não assinou
BUSYOutra assinatura do mesmo envelope em andamento — tente de novo em segundos
PROVIDER_UNSUPPORTED / PROVIDER_UNAVAILABLEA configuração não serve para assinar pela página
PROVIDER_CONFLICT / PROVIDER_NOT_FOUND / PROVIDER_VALIDATIONO motor recusou
SIGNATURE_UNCONFIRMEDFalha: o motor não pôde ser relido; o signatário fica SIGNING e a nova tentativa reconcilia
ENGINE_FAILEDFalha: 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_verify contra 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 como X-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 --> Sv

Decisões não óbvias da conferência.

  • A interface de verificação é separada da de assinatura. SignatureVerificationProvider (em verifiers/) não conhece envelope nem signatário; ESignatureProvider não conhece conferência. Um driver local (cadeia ICP-Brasil validada por nós) entra declarando sendsFileToThirdParty = 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.

08

Conceitos e modelo de dados

Glossário

TermoSignifica
Solicitação de assinatura (envelope)A unidade de trabalho: um documento, um conjunto de signatários e um estado. Corresponde ao modelo SignatureRequest.
SignatárioUma 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 provedorO provedor escolhido pela organização e suas credenciais cifradas. Uma delas é a padrão.
externalIdO identificador do recurso no provedor. É por ele que o webhook reencontra a solicitação. Único em conjunto com a configuração.
businessIdIdentificador livre da operação de origem — proposta, contrato, pedido. É o campo de correlação com os outros building blocks.
Chave mestra de credenciaisESIGNATURE_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 simplesNa 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.
OpenSignPlataforma 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 PrismaTabelaPropósitoCampos-chave
ESignatureProviderConfigesignature_provider_configsProvedor e credenciais da organizaçãoÚnico (organizationId, name), providerType, credentials (cifrado), isDefault, isActive, settings, deletedAt
SignatureRequestsignature_requestsO 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
SignersignersUm signatário do envelopeexternalId, email, order, status, signingUrl, sentAt, viewedAt, signedAt, declinedAt, declineReason
SignatureDocumentsignature_documentsO arquivo vinculado ao envelopeexternalId, fileId, originalUrl, signedUrl, signedUrlExpiresAt
ESignatureWebhookEventesignature_webhook_eventsTodo webhook recebido, crueventType, 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

EnumValores
ESignatureProviderTypeOPENSIGN (implementado) · DOCUSIGN · ADOBESIGN · ZAPSIGN (declarados, recusam em execução — §15)
SignatureRequestStatusDRAFT · SENT · VIEWED · PARTIALLY_SIGNED · COMPLETED · DECLINED · EXPIRED · CANCELLED
SignerStatusPENDING · 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 note

Três leituras que o diagrama não diz sozinho:

ObservaçãoConsequência prática
DRAFT e SENT dependem do que o provedor reporta na criaçãoO 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 persisteEnvelope 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 COMPLETED quando todos os signatários estão SIGNED.
  • 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 declineReason existe como coluna, mas o tratamento do webhook declined grava apenas status e declinedAt; o motivo depende do provedor informá-lo por outro caminho.

Modelos da conferência de assinatura (mesmo schema esignature):

Modelo PrismaTabelaPropósitoCampos-chave
SignatureVerificationSettingssignature_verification_settingsDecisão da organização. Sem linha = padrão da casaÚnico organizationId, thirdPartyEnabled (padrão false), fileRetentionDays (padrão 30), updatedBy
SignatureVerificationsignature_verificationsUma conferência de um arquivofileHash 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

09

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étodoRotaO que faz
GET/e-signature/sign/:codeA 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/stateEstado 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.pdfO PDF do envelope, do storage do bloco (o original vai para lá na criação)
POST/e-signature/sign/:code/otpEnvia 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ê:

  1. Aceite. Ele lê o PDF e marca "Li e concordo com os termos deste documento".
  2. 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".
  3. 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.
  4. Fim. "Documento assinado. Você já pode fechar esta página." É também o que um segundo acesso ao mesmo link mostra.

Estado final, que é também o que um segundo acesso ao mesmo link mostra
Estado final, que é 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étodoRotaDescriçãoPermissão
POST/e-signature/api/v1/esignature/provider-configsCria configuração e cifra as credenciais. Responde 201ESIGNATURE_ADMIN
GET/e-signature/api/v1/esignature/provider-configsLista as configurações da organizaçãoESIGNATURE_READ
GET/e-signature/api/v1/esignature/provider-configs/:idBusca uma configuração (sem as credenciais)ESIGNATURE_READ
PATCH/e-signature/api/v1/esignature/provider-configs/:idAtualiza nome, credenciais, ajustes ou estadoESIGNATURE_ADMIN
DELETE/e-signature/api/v1/esignature/provider-configs/:idExclusão lógica. Responde 204ESIGNATURE_ADMIN
POST/e-signature/api/v1/esignature/provider-configs/:id/testTesta a conexão com o provedorESIGNATURE_ADMIN
POST/e-signature/api/v1/esignature/provider-configs/:id/set-defaultMarca como padrão e desmarca as demaisESIGNATURE_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étodoRotaDescriçãoPermissão
POST/e-signature/api/v1/esignature/requestsCria a solicitação a partir de um arquivo. Responde 201ESIGNATURE_CREATE
POST/e-signature/api/v1/esignature/requests/from-templateCria a partir de um template do provedor. Responde 201ESIGNATURE_CREATE
GET/e-signature/api/v1/esignature/requestsLista solicitações, paginadoESIGNATURE_READ
GET/e-signature/api/v1/esignature/requests/:idBusca a solicitação com os signatáriosESIGNATURE_READ
POST/e-signature/api/v1/esignature/requests/:id/cancelCancela a solicitaçãoESIGNATURE_CREATE
POST/e-signature/api/v1/esignature/requests/:id/resendReenvia a todos ou a um signatárioESIGNATURE_CREATE
GET/e-signature/api/v1/esignature/requests/:id/evidenceLê 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 respostaESIGNATURE_READ
POST/e-signature/api/v1/esignature/requests/:id/evidenceCaptura (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/refreshReconsulta 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 concluiESIGNATURE_CREATE
GET/e-signature/api/v1/esignature/requests/:id/downloadURL do documento assinado. Exige COMPLETEDESIGNATURE_READ
GET/e-signature/api/v1/esignature/requests/:id/certificateURL 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 provedorESIGNATURE_READ
DELETE/e-signature/api/v1/esignature/requests/:idExclusão lógica. Responde 204ESIGNATURE_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):

json
{
  "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):

json
{ "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étodoRotaDescriçãoAutenticação
POST/e-signature/api/v1/esignature/webhooks/:configIdRecebe 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 assinaturaPública — sem JWT. Ver §14 e §15

Conferir assinatura de arquivo — /e-signature/api/v1/esignature/verifications

MétodoRotaDescriçãoPermissão
POST/e-signature/api/v1/esignature/verificationsConfere 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.auditRecordedESIGNATURE_CREATE
GET/e-signature/api/v1/esignature/verificationsLista, filtros filter[fileHash], filter[businessId], filter[status]ESIGNATURE_READ
GET/e-signature/api/v1/esignature/verifications/:idUma conferênciaESIGNATURE_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 localESIGNATURE_READ
GET/e-signature/api/v1/esignature/verification-settingsConfiguração efetiva; source: DEFAULT = padrão da casa, não alteradoESIGNATURE_READ
PUT/e-signature/api/v1/esignature/verification-settings{ "thirdPartyEnabled"?, "fileRetentionDays"? } (1–365). Publica esignature.verification-settings.changedESIGNATURE_ADMIN

Nenhuma rota aceita organização como parâmetro. Resposta de POST (resumida):

json
{
  "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):

Statusdetails.codeQuando
403THIRD_PARTY_DISABLEDA 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
413FILE_TOO_LARGEAcima de ESIGNATURE_VERIFICATION_MAX_BYTES
400FILE_EMPTY, UNSUPPORTED_FILE_TYPE, DETACHED_CONTENT_REQUIRED, FILE_UNREADABLEArquivo 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étodoRotaDescrição
GET/e-signature/healthSonda 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

json
{
  "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
}
CampoTipoObrigatórioDescrição
namestring (1–100)SimNome da configuração. Único por organização
providerTypeOPENSIGN | DOCUSIGN | ADOBESIGN | ZAPSIGNSimSó OPENSIGN funciona hoje (§15)
credentialsobjeto de textosSimCifrado antes de gravar. As chaves dependem do provedor
isDefaultbooleanoNãoSem valor, a primeira configuração da organização vira a padrão
isActivebooleanoNãoPadrão true
settingsobjetoNãoAjustes específicos do provedor

Credenciais do OpenSign

ChaveObrigatóriaDescrição
baseUrlSimHost de malha do motor, em https (com mTLS, http é recusado)
masterKeySimMaster key do motor (ele só a aceita vinda de dentro do container, isto é, pelo portão)
gateTokenSimSegredo do portão do motor. Sem ele, o motor responde 403 a tudo
appIdNãoIdentificador da aplicação Parse. Padrão opensign
apiPrefixNãoPadrã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

StatusCódigoQuando
400VALIDATIONCorpo reprovado no Zod, ou providerType fora do enum
403—Sem ESIGNATURE_ADMIN, ou token sem organizationId
409CONFLICTJá existe configuração com esse nome na organização
500INTERNALESIGNATURE_CREDENTIAL_MASTER_KEY ausente ou malformada — a cifragem falha

A criação não testa a conexão. Chame POST /:id/test logo 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

json
{
  "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 }
  ]
}
CampoTipoObrigatórioDescrição
titlestring (1–255)SimTítulo do envelope
messagestring (máx. 2000)NãoMensagem aos signatários
configIdUUIDNãoConfiguração a usar. Omitido, usa a padrão da organização
fileIdUUIDUm dos doisArquivo já guardado no file-storage
fileBase64stringUm dos doisArquivo em base64. Exige fileName
fileNamestring (máx. 255)Com fileBase64Nome do arquivo, usado para deduzir o tipo
signerslista, mínimo 1SimCada item com name, email e order opcional
widgetslistaNãoCampos de assinatura. Sem eles, um campo por signatário na primeira página
businessIdstring (máx. 100)NãoIdentificador da operação de origem
expiresInDaysinteiro 1–365NãoNo OpenSign, vira TimeToCompleteDays; padrão do provedor é 15

Resposta 201

json
{
  "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

StatusCódigoQuando
400VALIDATIONNenhum ou os dois de fileId/fileBase64; fileBase64 sem fileName; lista de signatários vazia
404NOT_FOUNDconfigId 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)
500INTERNALproviderType 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

StatusCódigoQuando
400VALIDATIONCannot cancel request with status COMPLETED ou CANCELLED
404NOT_FOUNDSolicitaçã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)

json
{ "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

json
{ "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

json
{
  "downloadUrl": "https://<file-storage>/...",
  "expiresAt": "2026-08-16T15:03:11.000Z"
}
{
  "downloadUrl": "https://<file-storage>/...",
  "expiresAt": "2026-08-16T15:03:11.000Z"
}

Erros

StatusCódigoQuando
400VALIDATIONDocument is not yet completed and signed — a solicitação não está COMPLETED
404NOT_FOUNDSolicitaçã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.


10

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

bash
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/esignature
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/esignature

2. Configurar o motor OpenSign local como provedor

bash
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

bash
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" \
  -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" \
  -H "Authorization: Bearer $TOKEN" | jq
json
{ "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

bash
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):

json
[
  {
    "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:

PassoNa telaRota pública
AbrirO 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 minPOST …/otp
Conferir"Confirmar" troca o código por um signToken de 30 min, de uso únicoPOST …/verify
Assinar"Desenhar" ou "Digitar"; "Assinar documento" só acende com tudo feitoPOST …/sign
Fim"Documento assinado. Você já pode fechar esta página."—

Primeiro acesso no celular, antes do código
Primeiro acesso no celular, antes do código

Depois de conferir o código, a página libera desenhar ou digitar
Depois de conferir o código, a página libera desenhar ou digitar

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:

bash
curl -s "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>/state" | jq
curl -s "https://esignature.bb.stg.catalisa.app/e-signature/sign/<código>/state" | jq

7. 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:

text
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_captured
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_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

bash
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):

json
{
  "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:

bash
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):

bash
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.pdf precisa 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 use fileId (§11). Credenciais de staging conforme AMBIENTES.md.


11

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 -.-> ES

1. Gerar o documento — ver o README do document-template.

bash
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

bash
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.

texto
8f2c1a90-0000-0000-0000-000000000000
8f2c1a90-0000-0000-0000-000000000000

3. Mandar assinar, correlacionando pelo mesmo businessId

bash
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.

texto
3c8a1e77-0000-0000-0000-000000000000
3c8a1e77-0000-0000-0000-000000000000

Armadilhas.

  • Use o mesmo businessId nos 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 fileId a fileBase64 sempre 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

bash
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 }
    ]
  }' | jq
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 }
    ]
  }' | jq

Armadilhas.

  • A ordem sequencial só é ativada quando algum signatário tem order maior que 1. Com todos em 1 — ou sem order —, 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

json
{
  "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 (y cresce para baixo); o bloco converte ao desenhar.
  • No OpenSign local, signerId é o e-mail do signatário. Sem signerId, 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 signature são desenhados (a imagem da assinatura); text, date e checkbox sã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

bash
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

bash
curl -s -X POST "$BASE/provider-configs/$NEW_ID/test" -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/provider-configs/$NEW_ID/test" -H "Authorization: Bearer $TOKEN" | jq
json
{ "success": true, "message": "Connection successful" }
{ "success": true, "message": "Connection successful" }

3. Promover

bash
curl -s -X POST "$BASE/provider-configs/$NEW_ID/set-default" -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/provider-configs/$NEW_ID/set-default" -H "Authorization: Bearer $TOKEN" | jq

A resposta traz a configuração com isDefault: true. As demais foram desmarcadas na mesma transação.

Armadilhas.

  • set-default desmarca 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

bash
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:

json
[
  { "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

bash
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jq
curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jq
json
{ "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:

SintomaCausa provávelO que fazer
404 ProviderConfig na criaçãoNenhuma configuração com isDefault e isActiveRode set-default numa configuração ativa
500 com "not yet implemented"providerType DOCUSIGN ou ADOBESIGNSó OpenSign e ZapSign funcionam (§15)
500 INTERNAL ao criar configuraçãoESIGNATURE_CREDENTIAL_MASTER_KEY ausente ou fora do formato64 caracteres hexadecimais; verifique o ambiente
401 ou 403 vindos do provedorCredencial errada ou expiradaPOST /:id/test isola isso em uma chamada
413Corpo acima de 1 MBUse fileId em vez de fileBase64
Estado nunca muda de DRAFT/SENTZapSign: 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áginaPOST /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" .-> P

1. Para todos os envelopes da organização, grave na configuração

bash
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 PATCH substitui o objeto settings inteiro (só extUserId e extUserOrganizationId, 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

bash
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:

CampoValores
modelight, dark ou auto (segue o sistema do signatário)
colorsprimary, background, surface, text, danger, em hex de 6 dígitos
radius0 a 32
font.familysystem, inter, roboto, open-sans, lato, montserrat, source-sans
logoFileIdUUID de um arquivo no file-storage da organização do envelope
layoutcard, fullscreen ou minimal
textsPor idioma (pt) ou locale (pt-BR): heading, intro, consent, done, declined, expired, invalid, cancelled, até 300 caracteres cada
poweredBytrue ou false
redirectUrlPara 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: uma settings.appearance inválida é ignorada inteira na hora de montar a página, sem erro. Depois de gravar, abra um link de teste e confira.
  • senderName mora em settings, não em appearance — é o nome no e-mail do código, não na página.

A mesma página no modo escuro
A mesma página no modo escuro

Assinatura digitada no celular, modo escuro
Assinatura digitada no celular, modo escuro

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:

reasonO que aconteceu
send_limitO link gastou os 10 envios de código da vida dele
attempt_limitO 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

bash
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

bash
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_wrong vindas 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 · reasonCausa provávelO 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-storageCorrija 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 falhouO 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 respondeuConfira se o file-storage (ou o motor, quando source é engine) está no ar e alcançável pelo serviço
engine · no_urlO envelope foi criado sem o original no file-storage, e o motor não deu endereçoEnvelope criado com o file-storage desligado: reemita o envelope (§15)
none · no_documentO envelope não tem documentoEnvelope 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.

CampoO que sai
Título e rótulospt-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"
Datasdd/MM/aaaa HH:mm:ss (horário de Brasília), seja qual for o fuso do usuário técnico
Organizaçãosettings.senderName da configuração, senão o name dela (a mesma regra do e-mail do código)
Enviado ema criação do envelope (o bloco cria e envia no mesmo ato)
Concluído ema última assinatura
Originador"Assinatura Catalisa", sem e-mail e sem IP
Cada signatárionome, 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 + bloco 0cda9ceb. 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)

bash
curl -s -X PUT "$BASE/verification-settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "thirdPartyEnabled": true, "fileRetentionDays": 30 }' | jq
curl -s -X PUT "$BASE/verification-settings" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "thirdPartyEnabled": true, "fileRetentionDays": 30 }' | jq

Começa desligado (source: DEFAULT) porque o arquivo vai ao Verificador de Conformidade. Sem isso, a conferência responde 403 THIRD_PARTY_DISABLED.

2. Conferir

bash
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

statusLeitura
VALIDAssinado com certificado reconhecido (ICP-Brasil, gov.br, Mercosul, AATL) e íntegro
INVALIDReprovado pelo verificador (por exemplo HASH_FAILURE: o arquivo mudou depois de assinado), sem assinatura (NO_SIGNATURE) ou assinado fora de raiz reconhecida (UNTRUSTED_ANCHOR)
INDETERMINATENã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

bash
HASH=$(sha256sum contrato-social.pdf | cut -d' ' -f1)
curl -s "$BASE/verifications/proof?fileHash=$HASH" -H "Authorization: Bearer $TOKEN" | jq
HASH=$(sha256sum contrato-social.pdf | cut -d' ' -f1)
curl -s "$BASE/verifications/proof?fileHash=$HASH" -H "Authorization: Bearer $TOKEN" | jq

Armadilhas.

  • 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 é o documentHash do envelope.
  • VALID não diz que quem assinou tinha poderes (companies) nem que é quem diz ser além do certificado (biometrics).

12

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 blockComo se relacionaObrigatório
IAMEmite o token e define o organizationId que isola configurações e envelopesSim
File StorageOrigem do documento a assinar (fileId) e destino do assinadoNão
Document TemplateGera o documento que será assinadoNão
Data ExtractionLê o documento assinado ou o comprovante devolvido pelo clienteNão
Webhooks EngineEntrega os eventos esignature.* a sistemas externos do clienteNão
Audit TrailRegistra quem criou, cancelou e baixou envelopeNão
Decision PlatformOrquestra a esteira que decide, gera o contrato e pede a assinaturaNão
CustomersFornece nome e e-mail dos signatáriosNã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 -.-> ES

E 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.


13

Configuração e operação

Variáveis de ambiente

VariávelDescriçãoObrigatóriaPadrão
ESIGNATURE_CREDENTIAL_MASTER_KEYChave AES-256-GCM para cifrar credenciais de provedor. Exatamente 64 caracteres hexadecimais (32 bytes). Gere com openssl rand -hex 32Sim, para usar o módulo—
DATABASE_URLPostgreSQL. O building block usa o schema esignatureSim—
REDIS_URLRedis, usado pelo limite de taxa e pelo publicador de eventosSim—
JWT_SECRETSegredo HS256 compartilhado com o IAM. Mínimo 44 caracteresSim—
S3_*Endpoint, credenciais e bucket, para resolver fileIdSim, se usar fileId—
MODULE_FILE_STORAGE_URLEndereç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_HOSTSOnde 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_B64CA (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_B64Certificado 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 TLSPara o motor com mTLS—
OPENSIGN_TLS_CLIENT_KEY_PEM_B64Chave 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 casaPara o motor com mTLS—
PROVIDER_WEBHOOK_SIGNATURE_ENFORCEMENToff aceita webhook não verificável com aviso; on recusaNãooff
DEPLOYMENT_MODEmonolith ou standaloneNãomonolith
PORTPorta em standaloneNão3000 (a topologia expõe 3014)
ESIGNATURE_ITI_VERIFIER_URLURL 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-homPara conferir assinatura— (sem ela, PROVIDER_NOT_CONFIGURED)
ESIGNATURE_ITI_VERIFIER_TIMEOUT_MSTempo limite de uma chamada; passou, INDETERMINATE / PROVIDER_TIMEOUTNão30000
ESIGNATURE_VERIFICATION_MAX_BYTESTeto do arquivo conferidoNão10485760 (10 MB)
ESIGNATURE_VERIFICATION_IDEMPOTENCY_HOURSJanela em que o mesmo SHA-256 reaproveita a conferência respondida pelo verificador. 0 desligaNão24
ESIGNATURE_VERIFICATION_PURGE_ENABLEDLimpeza da cópia temporária vencida (só em standalone, main.ts). Ligada por padrão: a prova está na trilhaNãotrue
ESIGNATURE_VERIFICATION_PURGE_INTERVAL_HOURSIntervalo da limpezaNão6
ESIGNATURE_PUBLIC_URLOrigem pública do bloco (ex.: https://esignature.bb.catalisa.app). Compõe o signingUrl da página hospedadaSim, para envelope OpenSign— (sem ela, 503 ao criar)
ESIGNATURE_SIGN_LINK_TTL_DAYSValidade do link quando o envelope não tem expiresInDaysNão30
SMTP_HOST / SMTP_PORTSMTP do código de 6 dígitos (o SMTP da casa, TLS implícito na 465)Sim, em produção— / 465
SMTP_USER / SMTP_PASSCredencial SMTPSe o servidor exigir—
SMTP_FROMRemetenteNãono-reply@catalisa.io

A chave mestra é lida direto de process.env no 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, com INTERNAL. Confira a presença dela no deploy; não confie na subida limpa como sinal.

Deploy: migrations do schema esignature

  • 20261017120000_esignature_archived_files cria duas colunas em signature_documents; o verificador de objetos do Launch (scripts/launch/lib.sh, objetos_do_sql) as enxerga e confere.

  • 20261017125000_esignature_signer_signing só faz ALTER TYPE … ADD VALUE IF NOT EXISTS 'SIGNING'. O verificador não enxerga ADD VALUE, então o preflight a mostra como "indeterminada" — e o scripts/launch/1-migrar.sh a aplica sozinho (db execute + resolve). Como o catálogo de objetos não cobre o enum, confira depois do deploy em pg_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 SIGNING e 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ênciaPara quê
PostgreSQLSchema esignature — configurações, envelopes, signatários, documentos e eventos
RedisLimite de taxa e publicação de eventos
S3 ou MinIOResolver fileId em conteúdo, via URL assinada
Bloco file-storageGuardar o original do envelope, servir o PDF à página e arquivar o PDF selado e o certificado (MODULE_FILE_STORAGE_URL)
IAMVerificação do token; o organizationId vem do claim assinado
Instância do provedorO motor opensign-local, alcançável pela malha com TLS mútuo (§7)

Limites e quotas

LimiteValorOnde
Corpo da requisição1 MBapplyCommonMiddleware — é o teto prático de fileBase64
Espera por chamada ao OpenSign30 segundosCliente HTTP do provider
Upload ao OpenSign100 MBLimite do cliente de upload, inalcançável pelo teto de 1 MB da API
title255 caracteresZod
message2.000 caracteresZod
expiresInDays1 a 365Zod
Signatáriosmínimo 1, sem teto declaradoZod
Limite de taxa global10.000 requisições por minuto por IP, quando ligadoRATE_LIMIT_GLOBAL_MAX
Arquivo conferido10 MB por padrão; por multipart, o corpo inteiro cabe em 1 MBESIGNATURE_VERIFICATION_MAX_BYTES, applyCommonMiddleware
Chamada ao verificador30 s por padrãoESIGNATURE_ITI_VERIFIER_TIMEOUT_MS
Retenção da cópia do arquivo1 a 365 dias por organização; padrão da casa 30PUT /verification-settings

Eventos publicados

EventoQuando
esignature.request.createdSolicitação criada, por qualquer das duas rotas de criação
esignature.request.cancelledCancelamento concluído
esignature.request.completedWebhook completed processado; no OpenSign local, último signatário na página do bloco ou refresh que achou o documento concluído
esignature.request.declinedWebhook declined processado
esignature.signer.viewedWebhook viewed processado
esignature.signer.signedWebhook signed processado; no OpenSign local, assinatura aplicada pela página do bloco (com IP e agente do signatário)
esignature.request.signedOpenSign local: uma assinatura aplicada e ainda faltam outras (PARTIALLY_SIGNED)
esignature.signature.refusedOpenSign local: assinatura recusada antes do motor, com reason (INVALID_IMAGE, IMAGE_TOO_LARGE, ALREADY_SIGNED, OUT_OF_ORDER, REQUEST_CANCELLED, BUSY…)
esignature.signature.failedOpenSign local: o motor ou o bloco falhou ao aplicar a assinatura, com code
esignature.request.archive_failedOpenSign local: concluído, mas o PDF selado ou o certificado não foi arquivado (stage); o refresh tenta de novo
esignature.signer.document_unavailableA 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.completedConferê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.reusedA janela de idempotência devolveu uma conferência anterior
esignature.verification.refusedRecusa antes de chamar o provedor, com code
esignature.verification.file_purged / .file_purge_failedA cópia temporária saiu (ou não saiu) do file-storage
esignature.verification-settings.changed / .refusedAdmin 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> }.

StatusCódigoSignificaO que fazer
400VALIDATIONCorpo reprovado, origem de arquivo ambígua, estado incompatível com a operaçãoLeia a message
401—Token ausente, inválido ou expiradoRenove no IAM
403—Falta a permissão exigida, ou o token não carrega organizationIdConfira o papel e a organização
404NOT_FOUNDConfiguração, solicitação ou signatário inexistente, excluído, ou de outra organizaçãoConfira o identificador. "De outra organização" e "inexistente" são a mesma resposta, de propósito
409CONFLICTNome de configuração repetido na organizaçãoEscolha outro
413—Corpo acima de 1 MBUse fileId
429—Limite de taxa estouradoAplique recuo exponencial
500INTERNALProvedor não implementado; chave mestra ausente; falha ao baixar do S3; erro do provedorVerifique 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/health responde a sonda de disponibilidade. É a rota usada pelo healthcheck da 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 em payload e o motivo da falha em error. É 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.

14

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 descarta

O 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"] -.-> T

Os 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ívelDefinição legal, resumidaO OpenSign atende?
I — simplesPermite identificar o signatário e anexa ou associa dados a outros dados eletrônicos do signatárioSim
II — avançadaUsa 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 posteriorNão — falta o controle exclusivo e falta a validação de identidade que o Decreto nº 10.543/2020, art. 5º, II exige
III — qualificadaUsa certificado digital nos termos do art. 10, § 1º da MP nº 2.200-2 — ou seja, ICP-BrasilNã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 legalPresunção de veracidade em relação aos signatáriosVálido entre as partes que o admitiram
Quem tem o ônus da provaQuem contesta precisa desconstituirQuem invoca precisa provar autoria e integridade
É o que este building block entrega hoje?NãoSim

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. 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 guardaOnde
Quem foi convidado a assinar — nome e e-mailsigners
A ordem exigida entre os signatáriossigners.order
Quando cada um recebeu, visualizou, assinou ou recusousigners.sentAt, viewedAt, signedAt, declinedAt
O motivo da recusasigners.declineReason
SHA-256 do PDF assinado e nível da assinaturasignature_requests.documentHash, hashAlgorithm, signatureLevel
Hash do original, do PDF selado e do certificado; IP e hora de cada signatário; ids dos arquivos arquivadossignature_requests.evidence
O PDF selado e o certificado de conclusãofile-storage da organização (signedFileId, certificateFileId)
Cada passo na página hospedada, com IP e user-agentEventos esignature.signer.* no stream iam-events
Todo evento recebido de provedor com webhook, com o corpo originalesignature_webhook_events.payload
EvidênciaCom o OpenSign local, o building block captura?
Hash SHA-256 do documento assinadoSim — documentHash, conferido contra o hash que o motor informa (engineHashMatches)
Hash do originalSim — na evidência e no carimbo do rodapé do PDF
IP de cada signatárioSim — a página repassa o IP de quem assinou ao motor; vai para o carimbo e para a evidência
Certificado de conclusãoSim — arquivado no file-storage; a URL ainda não vem na evidência (§15)
Segundo fatorSim — 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çãoA assinatura simples basta?
Contrato entre partes privadas que aceitaram o meio eletrônicoEm 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ônicoSim, pelo art. 784, § 4º do CPC — desde que a integridade seja conferida pelo provedor
Emitir CCBSim — 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 MEINão — o art. 5º, § 2º, III da Lei nº 14.063 exige qualificada
Ato de transferência e registro de bem imóvelNã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édicoNão — o art. 13 da Lei nº 14.063 exige qualificada
Ato em que a autoria pode ser contestada em juízoDepende 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):

TentativaResultado
Cliente certo, CA fixada200
Sem fixar a CA (pool do sistema)UNABLE_TO_VERIFY_LEAF_SIGNATURE
CA de outro emissor fixadaUNABLE_TO_VERIFY_LEAF_SIGNATURE
Certificado de cliente de outra CAECONNRESET (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 diz source: DEFAULT — padrão da casa, não alterado. Ligar e desligar exigem ESIGNATURE_ADMIN e 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 pelo audit-trail, e a poda de retenção da trilha mantém a linha mais recente de cada arquivo. GET /verifications/proof prova 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 VALID prova: 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).

15

Limitações conhecidas

LimitaçãoImpactoSituação
DocuSign e Adobe Sign só existem no enumSã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 funcionamConhecido
ZapSign: sem posicionamento de campos, sem reenvio, sem template pela APIwidgets 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_ENFORCEMENTPor 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 webhooksCorrigido
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 configuradoCorrigido
O OpenSign local não tem webhookO 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/refreshPor design
Nenhum provedor com ICP-BrasilO 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 simplesO 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árioPor design
OpenSign local: o motor não autentica o signatárioIsEnableOTP=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 issoPor design
Produção sela com PFX autoassinadoDecisã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ávelPor 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 mudaO 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 certificadoevidence.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 corrigidoPor design
Envelope criado com o file-storage desligado não guarda o originalSem 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 resolveConhecido
Código só por e-mailO segundo fator da página hospedada é e-mail (SMTP). WhatsApp entra como outra implementação de OtpSenderRoadmap
O nível de assinatura não é modeladoNã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çãoRoadmap
O OpenSign não emite carimbo de tempo confiávelOs horários da trilha são do relógio do servidor, sem autoridade de carimbo de tempo (RFC 3161). Para prova de anterioridade, isso é fracoLimitação do provedor
A licença do OpenSign não é AGPL-3 puraO 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 comercialPendente de avaliação jurídica
Corpo limitado a 1 MBfileBase64 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 fileIdPor design do middleware comum; ajustável na infraestrutura
Criar configuração não valida credencialUma credencial errada, ou um providerType não implementado, é aceita e só falha depois. Sempre chame POST /:id/testPor design; o teste existe para isso
EXPIRED nunca é gravadoO estado existe no enum e é mapeado a partir do provedor, mas nenhum caminho do código o persiste. Envelope vencido continua no último estado conhecidoRoadmap
OpenSign local: reenviar não manda e-mailPOST /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-templateSem 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 arquivoPor design
Sem rota para ler os eventos de webhookesignature_webhook_events é gravada mas não exposta. Investigar divergência exige consulta ao bancoRoadmap
Sem rotação da chave mestraTrocar ESIGNATURE_CREDENTIAL_MASTER_KEY inutiliza todas as credenciais já cifradas. Não há procedimento de recifragemRoadmap
Permissões só no papel ADMINESIGNATURE_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 provedorConfiguração pendente no IAM
Sem retenção nem expurgo automatizadoNome e e-mail de signatário ficam indefinidamente. Atender pedido de eliminação da LGPD é processo manualRoadmap
Conferência: não há instância de produção do verificadorO 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 MBO corpo passa pelo limite comum. Arquivo maior entra por fileId (até 10 MB)Por design do middleware comum
Conferência: o resultado envelheceUm 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 menorPor design
Conferência: sem comparação com o CPF esperadoO relatório traz o documento mascarado; o bloco ainda não responde "assinou quem eu esperava?"Roadmap
Conferência: sem telaSó API e fachada; nenhuma tela do app, do desktop ou do backoffice mostra a conferência aindaRoadmap
Conferência: purga só em standaloneA limpeza da cópia temporária sobe no main.ts do bloco, como nos outros blocos; no monolito não rodaPor design

16

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:

EventoLeitura
esignature.signer.otp_sentO 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_failedO 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_configuredProdução sem SMTP_HOST: nenhum código sai. Corrija o serviço (§13)
esignature.signer.otp_refused com resend_waitPediu 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