Referência rápida do TrustBridge

O essencial do Lacuna TrustBridge em uma página, com links para os artigos completos.

Para que serve

O Lacuna TrustBridge permite que a sua aplicação, no servidor, assine documentos PDF com o certificado ICP-Brasil de uma pessoa por uma API REST, enquanto a chave privada fica onde está: num smart card, num token USB ou no repositório do Windows da estação de trabalho do titular ou, quando a implantação opta por isso, num cofre no Servidor TrustBridge. A sua aplicação envia o CPF e o PIN do titular uma vez para abrir uma Sessão de Assinatura e assina dentro dela; ela nunca fica sabendo qual custódia respondeu. O TrustBridge é auto-hospedado: você executa o Servidor (um container Linux) e instala o pacote do Workstation na máquina Windows de cada titular. O Lacuna Signer faz o trabalho com o documento (hash, montagem do PDF, download do documento assinado), ou o REST PKI Core o faz para uma Aplicação Cliente que um Administrador configura para usá-lo; o TrustBridge assina hashes e não armazena documentos.

Escolha outro	Quando ele se encaixa melhor
CloudHub	Os certificados são certificados em nuvem guardados num provedor ICP-Brasil (um PSC), e não em tokens ou máquinas que você administra.
Rest PKI Core	A pessoa assina enquanto usa a sua aplicação web, no navegador, e você quer uma página de assinatura hospedada.
Web PKI	A sua própria página web precisa acessar, por JavaScript, os certificados no computador do usuário enquanto ele está nela.
Signer	Você precisa de um fluxo de documentos: participantes, notificações, aprovações, uma página de assinatura para cada pessoa.

Instalação

Não há biblioteca cliente: a API é HTTP e JSON (ou multipart), então qualquer cliente HTTP serve. O que você implanta:

Componente	Distribuído como	Versão atual	Guia
Servidor	Imagem de container trustbridge-server, no Docker (Linux) com SQL Server ou PostgreSQL, ou no Azure App Service com Azure SQL	1.24.0	Instalação do Servidor, Azure App Service
Workstation Service e Tray App	MSI assinado TrustBridge-Workstation-<versão>-x64.msi, um por máquina Windows de titular	1.10.0	Instalação da estação de trabalho

• Todo Servidor precisa de uma licença do Lacuna PKI SDK (Certificates:Validation:License, PKI_LICENSE no .env do Docker) e a entrega a cada estação de trabalho admitida; o MSI não recebe licença.
• Atualize primeiro o Servidor, depois a frota. O Workstation 1.10.0 exige o Servidor 1.20.0 ou posterior (1.23.0 ou posterior para que o console administrativo mostre quem está no console de cada máquina), e o Servidor 1.15.0 recusa o Workstation 1.4.x; por isso, uma frota ainda na 1.4.x passa para a 1.5.0 antes da atualização do Servidor. Uma máquina na 1.5.0 atende todas as sessões, exceto as de PIN por transação. Veja o Histórico de versões.
• O banco de dados é o SQL Server ou, no Docker, o PostgreSQL 16 ou posterior, escolhido uma única vez por implantação; o App Service continua no Azure SQL.
• Uma máquina nova espera na fila de admissão até que um Administrador a admita no console administrativo.

Configuração e autenticação

O endereço base é o do seu próprio Servidor (por exemplo, https://trustbridge.example.com), e toda operação fica sob /v1; uma rota sem esse prefixo responde 404 ENDPOINT_NOT_FOUND. Toda chamada precisa de uma chave de API no header X-API-Key.

• Obtenha uma chave na tela Aplicações Cliente do console administrativo (/admin/applications): cadastre a sua aplicação e use Emitir chave. O valor é mostrado uma única vez e só o hash dele é armazenado.
• Uma chave inválida é sempre 401 UNAUTHORIZED, esteja ela ausente, desconhecida, revogada, expirada ou com a aplicação desativada.
• Trate sessionId e signatureId como tokens de portador: qualquer chave aceita pode usar uma sessão ou buscar um documento cujo id tenha. Mantenha-os fora dos logs.
• Informe o X-Correlation-Id (presente em toda resposta, inclusive nos erros) e o code do erro ao relatar um problema; a Trilha de Auditoria do Servidor registra o código com que cada chamada foi respondida (Servidor 1.24.0).

Operações principais

Crie uma sessão, assine dentro dela, busque o PDF assinado (que é também onde você lê o resultado) e encerre a sessão. A página API REST documenta todas as operações; um Servidor em execução publica o documento OpenAPI em /openapi/v1.json e uma referência navegável em /scalar, ambos sem credencial.

Criar uma Sessão de Assinatura

POST /v1/sessions com o cpf do titular (onze dígitos, dígitos verificadores conferidos) e o pin (que só uma Aplicação Cliente com o PIN dispensado na criação pode omitir); opcionalmente, sessionDuration em segundos (acima do máximo, o valor é limitado ao máximo) e email, um endereço alternativo para um certificado que não traga nenhum.

curl -s https://trustbridge.example.com/v1/sessions \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{ "cpf": "12345678909", "pin": "1234", "sessionDuration": 3600 }'

{ "sessionId": "8f3c…", "cpf": "12345678909", "expiresIn": 3600, "expiresAt": "2026-09-21T15:04:05Z",
  "transactionPin": null, "certificate": "MIIH…", "chain": ["MIIG…", "MIIF…"] }

certificate (DER, base64) e chain (os emissores dele, do mais próximo para o mais distante; [] para um certificado numa estação de trabalho) descrevem o certificado vinculado. transactionPin é null, a menos que a sua Aplicação Cliente tenha o PIN por transação ligado.

O Servidor tenta primeiro os Certificados do Cofre desse CPF e depois pede às estações de trabalho que têm um certificado para ele que provem conhecer o PIN; o PIN em si nunca sai do Servidor. Quando nenhuma estação tem o PIN em cache, o titular recebe um pedido de PIN no Tray App e a requisição fica aberta até ele responder ou o pedido expirar (60 s por padrão): use um timeout generoso no cliente. Há uma sessão ativa por CPF; criar outra substitui a anterior.

Assinar por uma Empresa

Acrescente cnpj (catorze caracteres, CNPJ alfanumérico aceito) para assinar com o e-CNPJ de uma Empresa; cpf continua sendo o da pessoa Responsável por ele. Com cnpj, só o e-CNPJ dessa Empresa pode vincular a sessão; sem ele, um e-CNPJ nunca pode. As respostas trazem cnpj apenas quando ele se aplica. Exige o Servidor 1.13.0.

{ "cpf": "12345678909", "cnpj": "12ABC34501DE35", "pin": "1234" }

Assinar um documento

POST /v1/signatures com o sessionId e um PDF, em JSON (document em base64, fileName opcional) ou em multipart. A assinatura acontece dentro da requisição, que responde 202 com o signatureId e o fileName sob o qual o documento foi assinado.

curl -s https://trustbridge.example.com/v1/signatures \
  -H "X-API-Key: $API_KEY" \
  -F "sessionId=8f3c…" -F "document=@contract.pdf"

{ "signatureId": "a1b2…", "fileName": "contract.pdf", "status": "PROCESSING", "acceptedAt": "2026-09-21T14:10:00Z" }

Um 202 não quer dizer "deu certo": leia o resultado na busca do documento. Só PDFs são assinados, de até 10 MB por padrão. Para vários documentos, POST /v1/signatures/batch aceita até 50 partes de arquivo (por padrão) numa única chamada multipart e responde um resultado por documento, na ordem; leia cada resultado, e não o código de status. Um lote conta como uma chamada para o throttling e para a Franquia de Assinaturas.

A Franquia de Assinaturas é definida por Aplicação Cliente. Um Administrador pode definir, na sua Aplicação Cliente, quantas chamadas de assinatura cada sessão criada por ela pode fazer (1 dá sessões de uso único); a sessão então responde SESSION_EXPIRED depois desse número. Nada numa resposta diz se há uma.

Signer ou REST PKI Core. Um Administrador pode configurar a sua Aplicação Cliente para que os documentos dela sejam assinados com o REST PKI Core em vez do Lacuna Signer. As chamadas e as respostas são as mesmas, mas o signatureId passa a ser o id do REST PKI Core, o REST PKI Core guarda o PDF assinado, e toda falha antes de ele responder o documento assinado é uma recusa, e não um 202. Uma recusa depois de a chave do titular ter assinado não garante nada, num sentido ou noutro: reenviar o documento o assina de novo.

Assinar hashes (Assinatura de hash)

POST /v1/signatures/hashes com o sessionId, um digestAlgorithm (SHA-256, SHA-384 ou SHA-512) e até 50 hashes em base64 responde as assinaturas RSASSA-PKCS1-v1_5 brutas na mesma ordem, de forma síncrona e no modo tudo ou nada. Serve ao integrador que monta o próprio CAdES, XAdES ou PAdES em torno de certificate e chain. Fica desligada até um Administrador concedê-la à sua Aplicação Cliente; até lá, a chamada responde 403 HASH_SIGNING_NOT_GRANTED. Exige o Servidor 1.14.0.

{ "sessionId": "8f3c…", "digestAlgorithm": "SHA-256", "hashes": ["uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek="] }

PIN por transação

Um Administrador pode configurar uma Aplicação Cliente para pedir o PIN a cada chamada de assinatura (Servidor 1.15.0). Leia transactionPin em cada sessão:

• null: nada muda; não envie pin.
• "workstation": cada chamada de assinatura espera enquanto o titular a autoriza no Tray App (60 s por padrão, fora do tempo de assinatura); não envie pin e considere essa espera no seu timeout. Um lote pede uma vez só.
• "client" (um Certificado do Cofre): envie o PIN do titular como pin em toda chamada de assinatura.

Um pin enviado onde não cabe responde 400 INVALID_REQUEST. Um pedido recusado, sem resposta ou não exibido responde 422 PIN_NOT_AVAILABLE com uma palavra em details, e nada é assinado. Com no Tray at the console, o titular pode reabrir o Tray App pelo atalho TrustBridge do menu Iniciar (Workstation 1.9.0); o operador do Servidor vê no console administrativo por que o pedido não pôde ser exibido. Nesse modo, mantenha uma sessão de longa duração por usuário.

O PIN dispensado na criação (Servidor 1.18.0) é uma segunda opção, que só fica ligada junto com o PIN por transação: a sua aplicação pode então omitir o pin em POST /v1/sessions, e a sessão se vincula, sem pedir nada a ninguém, ao único certificado que poderia atendê-la. Quando mais de um poderia (duas máquinas, um certificado do cofre ao lado de uma máquina, um cartão antigo e a renovação dele), a criação responde 400 INVALID_REQUEST com details começando por pin is required.: peça o PIN ao usuário e envie a mesma requisição com ele.

Buscar o documento assinado

GET /v1/signatures/{signatureId}/document. Repita a consulta enquanto vier 409 DOCUMENT_NOT_READY; pare em 200 (o PDF assinado) ou em 422 DOCUMENT_UNAVAILABLE (recusado, cancelado ou expirado, ou que não está mais guardado). Não há webhook. Por quanto tempo um documento continua disponível depende da retenção do Lacuna Signer, ou da do REST PKI Core para um documento assinado lá, já que o Servidor não armazena nada.

curl -s https://trustbridge.example.com/v1/signatures/a1b2…/document \
  -H "X-API-Key: $API_KEY" -o signed.pdf -w '%{http_code}\n'

Verificar, descrever e encerrar uma sessão

• GET /v1/sessions/status?sessionId=… responde active e o tempo restante; nunca estende a sessão. Assinar estende.
• GET /v1/certificates/info?sessionId=… descreve o certificado vinculado; confira se status é ACTIVE antes de assinar.
• POST /v1/sessions/deactivate com { "sessionId": "…" } encerra a sessão na hora; sem nada ativo, responde 401 SESSION_EXPIRED.

Erros

Todo erro é { "error": { "code", "message", "details" } }. Decida pelo code, nunca pela message, e trate um código desconhecido como uma falha inesperada. Veja O envelope de erro.

• SESSION_EXPIRED (401) em qualquer chamada: a sessão expirou, foi desativada, foi substituída ou esgotou a Franquia de Assinaturas. Crie outra.
• INVALID_PIN (401): todos os certificados candidatos foram tentados e nenhum conferiu. TOO_MANY_PIN_ATTEMPTS (429) é o bloqueio por CPF: tentar de novo piora.
• PIN_NOT_AVAILABLE (422): nenhuma comparação pôde ser feita (o pedido de PIN expirou ou foi recusado, o certificado do cofre não abriu, houve tentativas falhas demais recentemente); details diz qual. WORKSTATION_OFFLINE (422): as máquinas do titular estão offline ou, para uma Aplicação Cliente com PIN por transação, numa release do Workstation anterior à 1.6.0; com details workstation removed, a máquina da sessão foi removida da plataforma e a sessão nunca mais vai assinar, então crie outra.
• HASH_SIGNING_NOT_GRANTED (403): a Assinatura de hash não foi concedida à sua Aplicação Cliente.
• CERT_NOT_FOUND (404) / CERT_NOT_ACTIVE (422): não há certificado para o CPF, ou nenhum tem o veredito ACTIVE.
• SIGNER_REJECTED (422) e SIGNER_ERROR (502): o serviço de assinatura recusou a requisição (não a reenvie sem mudanças) ou está inacessível (nada foi assinado; reenvie depois). Com o REST PKI Core, SIGNER_ERROR e INTERNAL_ERROR podem vir depois de a chave do titular ter assinado, e então reenviar assina de novo.
• SERVER_BUSY (429): o Servidor está no limite; tente de novo com o seu próprio backoff e jitter (não há Retry-After).

A página Resolução de problemas relaciona cada código ao que o operador deve verificar.

Certificados e credenciais de teste

• O TrustBridge só assina com certificados cuja cadeia ele reconhece. Para assinar com certificados de teste de uma AC privada, um Administrador acrescenta essa AC na tela Autoridades Certificadoras Confiáveis, o que chega a todas as estações de trabalho admitidas sem reinício.
• Para confiar na PKI de teste da Lacuna, defina Certificates:Validation:UseLacunaTestPki como true (padrão false) no Servidor; uma estação de trabalho faz o mesmo pela própria configuração de mesmo nome. Veja As fontes de âncoras e na estação de trabalho. Somente para desenvolvimento: a Lacuna publica as chaves privadas desses certificados de exemplo. Com ela ligada, o Servidor registra Critical na inicialização e mostra um banner de aviso em todas as páginas administrativas, e a estação de trabalho registra Critical a cada inicialização.
• Com ela ligada, uma conta administrativa vinculada ao CPF de um certificado de exemplo fica aberta a qualquer um que tenha baixado esse exemplo, e a estação de trabalho informa os certificados de exemplo como ACTIVE. Desligue-a em tudo que não seja uma máquina de desenvolvimento.
• Os certificados de exemplo (PKCS #12, senha 1234) e os dados da Lacuna Root Test v3 estão na página Certificados de teste.

A Lacuna não oferece um Servidor TrustBridge hospedado de teste nem um sandbox: para testar, entre em contato com o suporte da Lacuna.

TODO(docs): se cadastrar a Lacuna Root Test v3 na tela Autoridades Certificadoras Confiáveis funciona em vez de UseLacunaTestPki.

Experimente

• Num Servidor em execução, abra /scalar para navegar pelo contrato e testar chamadas com uma chave de API.
• Um Administrador pode fazer uma Assinatura de teste real, de ponta a ponta, na página Assinatura de teste do console administrativo (/admin/test-signature), digitando um CPF, o PIN dele e uma chave de API; ela devolve o PDF assinado de uma página ou, quando são pedidos vários documentos (até 50, Servidor 1.23.0), um ZIP com as cópias assinadas numa única chamada em lote. O PIN pode ficar em branco quando a aplicação da chave tem o PIN dispensado na criação, e a assinatura segue a configuração de Signer ou REST PKI Core dessa aplicação. A implantação também pode oferecê-la na página inicial (Landing Page) pública, com TestSignature:Enabled.
• A Lacuna Software pode fornecer uma coleção do Postman do contrato, com um ambiente que traz um PDF de exemplo: criar uma sessão, assinar, buscar. Veja Testando o contrato manualmente.

TODO(docs): nenhuma demonstração ou projeto de exemplo do TrustBridge está publicado.