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 cartão inteligente, 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 contêiner Linux) e instala o pacote da Estação de Trabalho na máquina Windows de cada titular. O Lacuna Signer faz o trabalho com o documento (hash, montagem do PDF, download do documento assinado); 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 contêiner trustbridge-server, no Docker (Linux) ou no Azure App Service, com SQL Server	1.13.0	Instalação do Servidor, Azure App Service
Serviço da Estação de Trabalho e Tray App	MSI assinado TrustBridge-Workstation-<versão>-x64.msi, um por máquina Windows de titular	1.5.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.
• A Estação de Trabalho 1.5.0 exige o Servidor 1.13.0, e os dois são atualizados juntos. Uma máquina numa versão anterior não participa da criação de sessões no Servidor 1.13.0. Veja o Histórico de versões.
• 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 bearer tokens: 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) ao relatar um problema.

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; 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" }

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 é consultado no Tray App e a requisição fica aberta até ele responder ou a consulta 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 status HTTP. Um lote conta como uma chamada para o limitador e para a Franquia de Assinaturas.

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). Não há webhook. Por quanto tempo um documento continua disponível depende da retenção do Lacuna Signer, 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 (a consulta expirou ou foi recusada, 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 numa versão da Estação de Trabalho anterior à 1.5.0.
• 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 não pôde ser alcançado (nada foi assinado; reenvie depois).
• 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 Soluçã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.
• A página de certificados da PKI de teste da Lacuna não tem uma seção do TrustBridge.

TODO(docs): se a Lacuna oferece um Servidor TrustBridge hospedado de teste ou um sandbox, e se a raiz da PKI de teste da Lacuna pode ser cadastrada como Autoridade Certificadora Confiável para testes.

Experimente

• Num Servidor em execução, abra /scalar para navegar pelo contrato e testar chamadas com uma chave de API.
• 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.