---
title: "Referência rápida do TrustBridge"
description: "O TrustBridge em uma página: o que você implanta, a chave de API, criar uma Sessão de Assinatura com CPF e PIN (ou para uma Empresa), assinar PDFs, ler o resultado e tratar erros."
canonical: "https://docs.lacunasoftware.com/articles/trustbridge/quick-reference"
locale: "pt-BR"
product: "TrustBridge"
last_updated: "2026-10-13"
---

# 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](https://docs.lacunasoftware.com/articles/cloudhub/quick-reference) | 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](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference) | A pessoa assina enquanto usa a sua aplicação web, no navegador, e você quer uma página de assinatura hospedada. |
| [Web PKI](https://docs.lacunasoftware.com/articles/web-pki/quick-reference) | A sua própria página web precisa acessar, por JavaScript, os certificados no computador do usuário enquanto ele está nela. |
| [Signer](https://docs.lacunasoftware.com/articles/signer/quick-reference) | 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](https://docs.lacunasoftware.com/articles/trustbridge/server-installation), [Azure App Service](https://docs.lacunasoftware.com/articles/trustbridge/azure) |
| 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](https://docs.lacunasoftware.com/articles/trustbridge/workstation-installation) |

- **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](https://docs.lacunasoftware.com/articles/trustbridge/changelog). 
- 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](https://docs.lacunasoftware.com/articles/trustbridge/rest-api) 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. 

```bash
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 }'
```

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

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

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

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

```bash
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](https://docs.lacunasoftware.com/articles/trustbridge/rest-api#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](https://docs.lacunasoftware.com/articles/trustbridge/troubleshooting#erros-na-aplicação-cliente) 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](https://docs.lacunasoftware.com/articles/pki-guide/test-certs) 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](https://docs.lacunasoftware.com/articles/trustbridge/rest-api#testando-o-contrato-manualmente). 

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