E-Signature

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.

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.

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.

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

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.

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.

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.

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.

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.

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: upload do arquivo → cria ou reaproveita<br/>os contatos dos signatários → monta os campos<br/>de assinatura → 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

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, é marcar como expirado. O Parse Server do OpenSign não tem um estado de cancelamento; o provider define Status: 'expired' no documento remoto, enquanto o nosso banco grava CANCELLED. Os dois lados ficam com nomes diferentes para o mesmo fato, de propósito: o nosso vocabulário é canônico e o do provedor não precisa ser. E o cancelamento tolera respostas 404, 409 e 422 do provedor, tratando-as como já cancelado.
• O reenvio não é um reenvio de verdade. O OpenSign não expõe endpoint de reenvio na API REST; o provider atualiza o campo SentToOthers do documento para disparar o fluxo de notificação. Funciona por efeito colateral, não por contrato — e é frágil a mudanças do lado do provedor.
• O download devolve a URL do provedor, não o arquivo. GET /requests/:id/download responde com downloadUrl e expiresAt; o serviço não faz proxy do binário. É a escolha certa para não carregar PDF em memória a cada consulta, e o custo é que a URL é do provedor e caduca conforme as regras dele — o expiresAt padrão de uma hora é um palpite nosso, não uma garantia dele.
• 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.

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.

Glossário

Modelo de dados — schema esignature no PostgreSQL. 5 modelos.

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

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:

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.

Prefixo HTTP: /e-signature. Em monolito, a base é http://localhost:3000. Em standalone, a porta é 3014; em staging, https://esignature.bb.stg.catalisa.app.

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.

Configurações de provedor — /e-signature/api/v1/esignature/provider-configs

Solicitações de assinatura — /e-signature/api/v1/esignature/requests

Filtros aceitos em GET /requests: filter[status] e filter[businessId]. Paginação por page[number] e page[size].

Webhook do provedor

Saúde

POST /e-signature/api/v1/esignature/provider-configs

Cria a configuração e cifra as credenciais antes de gravar. O corpo aceita tanto o envelope JSON:API (data.attributes) quanto o objeto direto.

Request

{
  "name": "OpenSign Produção",
  "providerType": "OPENSIGN",
  "credentials": {
    "baseUrl": "https://opensign.suaempresa.com.br",
    "appId": "opensign",
    "apiPrefix": "/api/app",
    "masterKey": "<segredo do Parse Server>"
  },
  "isDefault": true,
  "isActive": true
}

{
  "name": "OpenSign Produção",
  "providerType": "OPENSIGN",
  "credentials": {
    "baseUrl": "https://opensign.suaempresa.com.br",
    "appId": "opensign",
    "apiPrefix": "/api/app",
    "masterKey": "<segredo do Parse Server>"
  },
  "isDefault": true,
  "isActive": true
}

Credenciais do OpenSign

Resposta 201 — devolve a configuração sem o campo credentials. O segredo não volta em nenhuma rota, nunca.

Erros

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

{
  "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 }
  ]
}

Resposta 201

{
  "data": {
    "type": "signature-request",
    "id": "3c8a1e77-0000-0000-0000-000000000000",
    "links": { "self": "/api/v1/esignature/requests/3c8a1e77-0000-0000-0000-000000000000" },
    "attributes": {
      "title": "CCB - Proposta 2026-000481",
      "status": "DRAFT",
      "businessId": "proposta-2026-000481",
      "viewUrl": "https://opensign.suaempresa.com.br/...",
      "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",
      "viewUrl": "https://opensign.suaempresa.com.br/...",
      "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

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

No OpenSign, o cancelamento marca o documento remoto como expirado. Respostas 404, 409 e 422 do provedor são toleradas — a gravação local prossegue.

POST /e-signature/api/v1/esignature/requests/:id/resend

Request (corpo opcional)

{ "signerEmail": "maria@exemplo.com.br" }

{ "signerEmail": "maria@exemplo.com.br" }

Sem signerEmail, reenvia a todos. Com ele, o signatário precisa existir no envelope — caso contrário, 404.

Resposta 200

{ "message": "Signature request resent successfully" }

{ "message": "Signature request resent successfully" }

A mensagem confirma que a chamada ao provedor não falhou. Ela não confirma que um e-mail saiu — no OpenSign o reenvio é um efeito colateral de atualizar o documento, não um contrato de envio (§7).

GET /e-signature/api/v1/esignature/requests/:id/download

Resposta 200

{
  "downloadUrl": "https://opensign.suaempresa.com.br/files/...",
  "expiresAt": "2026-08-16T15:03:11.000Z"
}

{
  "downloadUrl": "https://opensign.suaempresa.com.br/files/...",
  "expiresAt": "2026-08-16T15:03:11.000Z"
}

Erros

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.

Do zero a uma solicitação de assinatura criada. Comandos escritos para staging; não executados nesta redação. Você precisa de uma instância OpenSign alcançável.

O caminho tem seis passos, e o terceiro é o que economiza tempo:

flowchart LR
    P1["1. Autenticar no IAM"] --> P2["2. Configurar o provedor"]
    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 a solicitação"]
    P4 --> P5["5. Acompanhar por requestId"]
    P5 --> P6["6. Listar por businessId"]

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | 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": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://esignature.bb.stg.catalisa.app/e-signature/api/v1/esignature

2. Configurar o provedor

CFG=$(curl -s -X POST "$BASE/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "OpenSign Homologação",
    "providerType": "OPENSIGN",
    "credentials": {
      "baseUrl": "https://opensign.exemplo.internal",
      "appId": "opensign",
      "apiPrefix": "/api/app",
      "masterKey": "SUBSTITUA_PELO_SEGREDO_DA_SUA_INSTANCIA"
    },
    "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": "OpenSign Homologação",
    "providerType": "OPENSIGN",
    "credentials": {
      "baseUrl": "https://opensign.exemplo.internal",
      "appId": "opensign",
      "apiPrefix": "/api/app",
      "masterKey": "SUBSTITUA_PELO_SEGREDO_DA_SUA_INSTANCIA"
    },
    "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.

3. Testar a conexão antes de qualquer outra coisa

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

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

4. Criar a solicitação de assinatura

REQ=$(curl -s -X POST "$BASE/requests" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato de Teste",
    "message": "Documento de homologação. Não possui valor contratual.",
    "fileBase64": "'"$(base64 -w0 contrato.pdf)"'",
    "fileName": "contrato.pdf",
    "businessId": "teste-001",
    "expiresInDays": 7,
    "signers": [
      { "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }
    ]
  }')

REQ_ID=$(echo "$REQ" | jq -r '.data.id')
echo "$REQ" | jq '{status: .data.attributes.status,
                    signatarios: [.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": "Contrato de Teste",
    "message": "Documento de homologação. Não possui valor contratual.",
    "fileBase64": "'"$(base64 -w0 contrato.pdf)"'",
    "fileName": "contrato.pdf",
    "businessId": "teste-001",
    "expiresInDays": 7,
    "signers": [
      { "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }
    ]
  }')

REQ_ID=$(echo "$REQ" | jq -r '.data.id')
echo "$REQ" | jq '{status: .data.attributes.status,
                    signatarios: [.data.relationships.signers.data[].attributes | {email, status, signingUrl}]}'

Resposta prevista:

{
  "status": "DRAFT",
  "signatarios": [
    { "email": "maria@exemplo.com.br", "status": "SENT", "signingUrl": "https://opensign.exemplo.internal/..." }
  ]
}

{
  "status": "DRAFT",
  "signatarios": [
    { "email": "maria@exemplo.com.br", "status": "SENT", "signingUrl": "https://opensign.exemplo.internal/..." }
  ]
}

O signingUrl é a URL individual de assinatura. Trate-a como segredo — quem tem o link consegue assinar.

5. Acompanhar

curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status: .data.attributes.status,
         signatarios: [.data.relationships.signers.data[].attributes | {email, status, viewedAt, signedAt}]}'

curl -s "$BASE/requests/$REQ_ID" -H "Authorization: Bearer $TOKEN" \
  | jq '{status: .data.attributes.status,
         signatarios: [.data.relationships.signers.data[].attributes | {email, status, viewedAt, signedAt}]}'

Resposta prevista, antes de qualquer movimentação do signatário:

{
  "status": "DRAFT",
  "signatarios": [
    { "email": "maria@exemplo.com.br", "status": "SENT", "viewedAt": null, "signedAt": null }
  ]
}

{
  "status": "DRAFT",
  "signatarios": [
    { "email": "maria@exemplo.com.br", "status": "SENT", "viewedAt": null, "signedAt": null }
  ]
}

Se o estado nunca mudar depois de a pessoa assinar, não é bug do seu lado: é a rota de webhook, que hoje não está funcional (§15).

6. Listar por operação

curl -s "$BASE/requests?filter%5BbusinessId%5D=teste-001&page%5Bsize%5D=10" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta, [.data[].attributes.title]'

curl -s "$BASE/requests?filter%5BbusinessId%5D=teste-001&page%5Bsize%5D=10" \
  -H "Authorization: Bearer $TOKEN" | jq '.meta, [.data[].attributes.title]'

Resposta prevista:

{ "totalItems": 1, "totalPages": 1, "currentPage": 1, "itemsPerPage": 10 }

{ "totalItems": 1, "totalPages": 1, "currentPage": 1, "itemsPerPage": 10 }

[ "Contrato de Teste" ]

[ "Contrato de Teste" ]

O contrato.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, use fileId (§11). Credenciais de staging conforme AMBIENTES.md.

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.

PDF_B64=$(curl -s -X POST \
  "https://document-template.bb.stg.catalisa.app/document-templates/api/v1/document-templates/$TPL_ID/render/pdf" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"variables": { ... }, "businessId":"proposta-2026-000481"}' \
  | jq -r '.data.attributes.pdfBase64')

PDF_B64=$(curl -s -X POST \
  "https://document-template.bb.stg.catalisa.app/document-templates/api/v1/document-templates/$TPL_ID/render/pdf" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"variables": { ... }, "businessId":"proposta-2026-000481"}' \
  | jq -r '.data.attributes.pdfBase64')

O retorno é o PDF em base64. Confira que a variável não ficou vazia antes de seguir — a rota de PDF do document-template não está configurada em staging nem em produção hoje.

2. Guardar no file-storage e obter um fileId

FILE_ID=$(curl -s -X POST https://storage.bb.stg.catalisa.app/file-storage/api/v1/files \
  -H "Authorization: Bearer $TOKEN" -F "file=@ccb.pdf" | jq -r '.data.id')

echo "$FILE_ID"

FILE_ID=$(curl -s -X POST https://storage.bb.stg.catalisa.app/file-storage/api/v1/files \
  -H "Authorization: Bearer $TOKEN" -F "file=@ccb.pdf" | jq -r '.data.id')

echo "$FILE_ID"

Resposta prevista: um UUID, que é o que o e-signature aceita em fileId.

8f2c1a90-0000-0000-0000-000000000000

8f2c1a90-0000-0000-0000-000000000000

3. Mandar assinar, correlacionando pelo mesmo businessId

curl -s -X POST "$BASE/requests" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": "CCB - Proposta 2026-000481",
    "fileId": "'"$FILE_ID"'",
    "businessId": "proposta-2026-000481",
    "signers": [{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }]
  }' | jq '.data.id'

curl -s -X POST "$BASE/requests" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "title": "CCB - Proposta 2026-000481",
    "fileId": "'"$FILE_ID"'",
    "businessId": "proposta-2026-000481",
    "signers": [{ "name": "Maria Souza", "email": "maria@exemplo.com.br", "order": 1 }]
  }' | jq '.data.id'

Resposta prevista: o identificador da solicitação de assinatura, que você guarda junto da sua operação.

3c8a1e77-0000-0000-0000-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

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, o contato é reaproveitado por e-mail entre solicitações. Mudar o nome de um signatário que já existe não atualiza o cadastro dele no provedor.
• Sem widgets, o building block posiciona um campo de assinatura por signatário na primeira página, em coordenadas fixas espaçadas horizontalmente. Para contrato de várias páginas, informe widgets — o padrão quase nunca é onde você quer.

Posicionar campos de assinatura em página específica

{
  "widgets": [
    { "type": "signature", "page": 8, "x": 90,  "y": 610, "width": 180, "height": 55, "required": true },
    { "type": "date",      "page": 8, "x": 300, "y": 610, "width": 120, "height": 30 },
    { "type": "checkbox",  "page": 8, "x": 90,  "y": 680, "label": "Li e concordo" }
  ]
}

{
  "widgets": [
    { "type": "signature", "page": 8, "x": 90,  "y": 610, "width": 180, "height": 55, "required": true },
    { "type": "date",      "page": 8, "x": 300, "y": 610, "width": 120, "height": 30 },
    { "type": "checkbox",  "page": 8, "x": 90,  "y": 680, "label": "Li e concordo" }
  ]
}

Armadilhas.

• As coordenadas são as do provedor, e a origem do sistema de coordenadas do OpenSign pode não ser a que você espera. Valide visualmente num documento de teste antes de subir para produção.
• Sem signerId, o campo é atribuído a todos os signatários. Com dois signatários e um campo, você acaba com dois campos sobrepostos na mesma posição.
• O signerId esperado é o identificador do contato no provedor, não o UUID do Signer no nosso banco. É a armadilha mais provável desta rota.
• Os tipos aceitos pelo nosso schema são signature, text, date e checkbox. O OpenSign suporta mais tipos, que não estão expostos aqui.

Trocar a configuração padrão de provedor

Objetivo. Passar a usar uma nova conta no provedor sem interromper os envelopes em aberto.

flowchart LR
    A["1. Criar a nova configuração<br/>POST /provider-configs"] --> B["2. Testar ANTES de promover<br/>POST /provider-configs/:id/test"]
    B -->|"success: false"| Pare["Pare. Corrija a credencial<br/>e teste de novo"]
    B -->|"success: true"| C["3. Promover<br/>POST /provider-configs/:id/set-default"]
    C --> D["A antiga é desmarcada na mesma transação"]
    D --> E["Envelopes já criados continuam na configuração antiga<br/>— o configId está gravado no envelope"]

1. Criar a nova configuração

NEW_CFG=$(curl -s -X POST "$BASE/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"OpenSign Novo","providerType":"OPENSIGN","credentials":{ ... }}')
NEW_ID=$(echo "$NEW_CFG" | jq -r '.data.id')

NEW_CFG=$(curl -s -X POST "$BASE/provider-configs" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"OpenSign Novo","providerType":"OPENSIGN","credentials":{ ... }}')
NEW_ID=$(echo "$NEW_CFG" | jq -r '.data.id')

2. Testar ANTES de promover

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

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

{ "success": true, "message": "Connection successful" }

{ "success": true, "message": "Connection successful" }

3. Promover

curl -s -X POST "$BASE/provider-configs/$NEW_ID/set-default" -H "Authorization: Bearer $TOKEN" | 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

curl -s "$BASE/provider-configs" -H "Authorization: Bearer $TOKEN" \
  | jq '[.data[] | {id, name: .attributes.name, tipo: .attributes.providerType,
                    padrao: .attributes.isDefault, ativa: .attributes.isActive}]'

curl -s "$BASE/provider-configs" -H "Authorization: Bearer $TOKEN" \
  | jq '[.data[] | {id, name: .attributes.name, tipo: .attributes.providerType,
                    padrao: .attributes.isDefault, ativa: .attributes.isActive}]'

Resposta prevista — é aqui que se descobre que não há nenhuma com padrao: true e ativa: true:

[
  { "id": "…", "name": "OpenSign Homologação", "tipo": "OPENSIGN", "padrao": true, "ativa": true }
]

[
  { "id": "…", "name": "OpenSign Homologação", "tipo": "OPENSIGN", "padrao": true, "ativa": true }
]

2. Exercitar a credencial contra o provedor

curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jq

curl -s -X POST "$BASE/provider-configs/$CFG_ID/test" -H "Authorization: Bearer $TOKEN" | jq

{ "success": true, "message": "Connection successful" }

{ "success": true, "message": "Connection successful" }

3. Cruzar o sintoma com a causa

flowchart TD
    S{"Qual foi o sintoma?"}
    S -->|"404 ProviderConfig na criação"| C1["Nenhuma configuração isDefault e isActive<br/>→ rode set-default numa configuração ativa"]
    S -->|"500 com not yet implemented"| C2["providerType diferente de OPENSIGN<br/>→ só o OpenSign funciona, §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["O webhook não está atualizando<br/>→ limitação da §15, confira o painel do provedor"]

Ordem de diagnóstico, da causa mais comum para a mais rara:

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.

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.

Variáveis de ambiente

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.

Dependências de infraestrutura

Limites e quotas

Eventos publicados

Os quatro últimos dependem do webhook do provedor (§15). esignature.request.viewed e esignature.request.signed existem no catálogo de tipos mas não são publicados por nenhum caminho de código.

Catálogo de erros

O envelope de erro é { "error": "<código>", "message": "<texto>", "details": <opcional> }.

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.

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:

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

A diferença entre os dois é o ônus da prova. Com ICP-Brasil, presume-se verdadeiro e cabe a quem contesta desconstituir. Sem ICP-Brasil, quem invoca o documento precisa provar autoria e integridade. Por isso o material comercial da Catalisa não pode dizer que a assinatura simples "tem a mesma validade jurídica". A formulação correta é: é juridicamente válida entre as partes que a admitiram, com ônus probatório distinto.

O ativo legal que muda a conversa: o art. 784, § 4º do CPC

O ativo legal que muda a conversa: o art. 784, § 4º do CPC. A Lei nº 14.620/2023, art. 34, acrescentou ao Código de Processo Civil:

"§ 4º Nos títulos executivos constituídos ou atestados por meio eletrônico, é admitida qualquer modalidade de assinatura eletrônica prevista em lei, dispensada a assinatura de testemunhas quando sua integridade for conferida por provedor de assinatura."

Ou seja: assinatura simples serve para constituir título executivo eletrônico, e as duas testemunhas do art. 784, III caem — desde que a integridade seja conferida pelo provedor de assinatura. Essa condição é técnica e é onde o produto precisa entregar: hash do documento, trilha e detecção de adulteração.

E a CCB, especificamente

E a CCB, especificamente. A Cédula de Crédito Bancário não precisa de testemunhas nem de assinatura qualificada. Ela é título executivo por força de lei própria — art. 28 da Lei nº 10.931/2004 —, enquadrando-se no art. 784, XII do CPC ("os demais títulos aos quais, por disposição expressa, a lei atribuir força executiva"), e não no inciso III, que é o das testemunhas. O art. 29, VI exige apenas a assinatura do emitente, e o § 5º do mesmo artigo, incluído pela Lei nº 13.986/2020, admite que ela seja eletrônica "desde que garantida a identificação inequívoca de seu signatário". A Lei nº 13.986/2020 também acrescentou o art. 27-A, que autoriza a emissão da CCB sob forma escritural.

A trilha da assinatura, e o que este building block preserva hoje

A trilha da assinatura, e o que este building block preserva hoje.

flowchart LR
    subgraph Op["Trilha operacional — guardada aqui"]
      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["todo webhook recebido, com o corpo original"]
    end
    subgraph Pr["Trilha probatória — fica no provedor"]
      P1["hash SHA-256 do PDF assinado"]
      P2["trilha de auditoria com IP por evento"]
      P3["certificado de conclusão"]
    end
    Op -->|"serve para você saber e demonstrar internamente"| Uso["acompanhamento e auditoria interna"]
    Pr -->|"é o que sustentaria o art. 784, § 4º do CPC"| Prova["prova de integridade"]
    Pr -.->|"NÃO é espelhada no nosso banco — §15"| Op

E o que o provedor produz mas o building block não captura — e esta é a lacuna mais relevante deste documento:

A leitura prática, e ela é dura: a trilha que este building block mantém hoje é operacional — serve para você saber e demonstrar internamente o que aconteceu. A trilha probatória, a que sustentaria a condição do art. 784, § 4º, existe do lado do OpenSign e não está sendo espelhada. Enquanto isso não for corrigido (§15), a prova de integridade depende de recorrer diretamente ao provedor. Não afirme a cliente que o building block, por si, confere integridade verificável.

O que dizer e o que não dizer a um cliente

O que dizer e o que não dizer a um cliente

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.

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.

Qual nível de assinatura eu obtenho com este building block?

Assinatura eletrônica simples, com o único provedor implementado hoje. O motivo é técnico e específico: o certificado que sela o PDF no OpenSign é do operador do servidor, 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. Instalar um certificado ICP-Brasil no servidor não muda isso. Leia a §14 inteira antes de responder a um cliente, e envolva o jurídico se o ato for de maior exigência.

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 aqui vem a ressalva honesta: o OpenSign produz as evidências necessárias — hash SHA-256, trilha com IP, certificado de conclusão —, mas o building block ainda não as captura (§15). Enquanto isso não for corrigido, a prova de integridade depende de recorrer ao provedor.

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?

Provavelmente nada do seu lado. A atualização de estado depende do webhook do provedor, e essa rota não está funcional hoje (§15). Também não existe rota para reconsultar o estado no provedor. Enquanto isso não for corrigido, o acompanhamento fino depende do painel do provedor. É a limitação mais importante deste building block e é a primeira coisa a verificar.

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?

Hoje, recorrendo ao provedor. O OpenSign calcula e guarda um hash SHA-256 do PDF final assinado e emite um certificado de conclusão com esse hash — mas o building block não busca nem armazena nenhum dos dois (§15). Enquanto essa lacuna existir, calcule e guarde o resumo do arquivo na sua própria aplicação antes de enviar, e trate a consulta ao painel do provedor como parte do procedimento de prova.

O signatário precisa se autenticar de alguma forma além do link?

Não, hoje. O OpenSign oferece verificação por código de uso único, mas o nosso provider não a ativa (§15). Na prática, quem tem o link consegue assinar — inclusive quem receber o e-mail encaminhado. Trate o signingUrl como segredo e considere isso na sua avaliação de risco.

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?

Sim, hoje. É o único provedor implementado e é auto-hospedado. Isso tem um lado bom que vale explicitar no comercial: com ele, o contrato nunca sai da sua infraestrutura, o que elimina uma transferência de dado pessoal a terceiro. E tem o lado a ser dito com clareza: você opera essa instância, e o nível de assinatura obtido é o simples.

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.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md}