API REST • v1 ESTÁVEL

Assinatura digital de documentos PDF

API para aplicação de assinatura digital ICP-Brasil no padrão PAdES, com suporte a carimbo do tempo, selo visual, página de autenticação, QR Code e integração com automações.

Começar integração Baixar documentação

DISPONIBILIDADE

Status da API

Abrir health check

Status Consultando...

Versão 1.0.0

Tempo de resposta Consultando...

API v1 — Estável

INTEGRAÇÃO

Primeiros passos

O consumo básico da API pode ser concluído em cinco etapas.

Solicite uma API Key à P&S2B.

Leia o arquivo PDF em binário e converta-o para Base64.

Envie uma requisição POST para /api/v1/sign.

Informe a API Key no cabeçalho X-API-Key.

Decodifique data.signedPdfBase64 e salve o arquivo resultante como PDF.

ENDEREÇO

URL base

https://sign.pes2b.com

SEGURANÇA

Autenticação

Todos os endpoints protegidos exigem uma API Key válida no cabeçalho X-API-Key.

X-API-Key: SUA_CHAVE

A API Key deve possuir pelo menos 32 caracteres. A chave deve ser armazenada em variável de ambiente, credencial do n8n ou cofre de segredos.

Importante: nunca publique a API Key em código-fonte, GitHub, documentação, prints, workflows exportados ou mensagens de e-mail.

Resposta de autenticação inválida

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "message": "API Key inválida."
}

MONITORAMENTO

Health checks

GET /api/v1/health Público

{
  "success": true,
  "message": "Serviço disponível.",
  "data": {
    "service": "pes2b-sign-service",
    "status": "UP"
  },
  "version": "1.0.0"
}

GET /actuator/health

GET /actuator/info

ENDPOINT PRINCIPAL

Assinar PDF

POST /api/v1/sign API Key

Recebe um documento PDF convertido para Base64 e devolve o PDF assinado também em Base64.

O documento retornado pode conter assinatura PAdES-B ou PAdES-T, conforme a configuração ativa do servidor.

ENTRADA

Requisição

{
  "pdfBase64": "JVBERi0xLjQK..."
}

Campo	Tipo	Obrigatório	Descrição
`pdfBase64`	String	Sim	Conteúdo integral do PDF codificado em Base64.

O campo aceita Base64 puro, normalmente iniciado por JVBER, ou Data URI:

data:application/pdf;base64,JVBERi0xLjQK...

SAÍDA

Resposta de sucesso

{
  "success": true,
  "data": {
    "signedPdfBase64": "JVBERi0xLjQK..."
  }
}

O consumidor deve decodificar data.signedPdfBase64 e salvar o resultado com a extensão .pdf.

APARÊNCIA

Modos de aparência visual

O serviço suporta quatro modos visuais. Atualmente, o modo é definido no ambiente do servidor.

NONE

Apenas assinatura criptográfica, sem elementos visuais.

STAMP_ONLY

Selo com assinante, data, padrão e ID em todas as páginas.

PAGE_ONLY

Página final premium com dados do certificado e QR Code.

STAMP_AND_PAGE

Selo em todas as páginas e página final premium.

EXEMPLOS

Exemplo em cURL

curl --request POST \
  "https://sign.pes2b.com/api/v1/sign" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: SUA_CHAVE" \
  --data '{
    "pdfBase64": "JVBERi0xLjQK..."
  }'

Exemplo em JavaScript

const response = await fetch(
  "https://sign.pes2b.com/api/v1/sign",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.PES2B_API_KEY
    },
    body: JSON.stringify({
      pdfBase64
    })
  }
);

if (!response.ok) {
  throw new Error(
    `Erro ao assinar PDF: ${response.status}`
  );
}

const result = await response.json();

const signedPdfBase64 =
  result.data.signedPdfBase64;

Configuração no n8n

Use um node HTTP Request.

Defina o método POST e a URL https://sign.pes2b.com/api/v1/sign.

Envie o cabeçalho X-API-Key utilizando uma credencial segura do n8n.

Use o body JSON com pdfBase64.

Reconstrua o arquivo usando data.signedPdfBase64.

TRATAMENTO DE FALHAS

Códigos de erro

Código	HTTP	Descrição
`UNAUTHORIZED`	401	API Key ausente ou inválida.
`INVALID_REQUEST`	400	Requisição inválida.
`INVALID_JSON`	400	JSON inválido.
`INVALID_PDF`	400	Conteúdo não corresponde a um PDF válido.
`FILE_TOO_LARGE`	400/413	Arquivo superior ao limite permitido.
`TIMESTAMP_ERROR`	400/500	Falha ao obter ou incorporar carimbo do tempo.
`INTERNAL_ERROR`	500	Erro interno ao processar o documento.

{
  "success": false,
  "code": "INVALID_PDF",
  "message": "O conteúdo informado não corresponde a um PDF válido.",
  "requestId": "e4bcb98e-f87f-45bc-b8d7-55f9ebf84f15",
  "timestamp": "2026-07-11T18:30:00-03:00",
  "path": "/api/v1/sign"
}

Guarde o requestId. Ele permite localizar a requisição nos logs do serviço.

RECURSOS

Downloads

JSON

OpenAPI 3

Definição completa da API para Postman, Insomnia, Bruno e geração de clientes.

Baixar OpenAPI

POSTMAN

Collection oficial

Collection com Health, Info e assinatura de PDF.

Baixar Collection

MARKDOWN

Documentação completa

Versão apropriada para equipes técnicas e compartilhamento com outros chats.

Baixar Markdown

RELEASES

Changelog

Histórico das versões e funcionalidades publicadas.

Baixar Changelog

COMPATIBILIDADE

Versionamento

A versão estável atual da API é v1.

v1 /api/v1 Estável

Mudanças incompatíveis serão publicadas em uma nova versão. A API v1 continuará estável para as integrações existentes.

VERSÕES

Changelog

12 de julho de 2026 Versão 1.0.0

Estável

Primeira versão de produção do PES2B Sign Service.

Assinatura PAdES-B e PAdES-T.
Carimbo do tempo RFC 3161.
Autenticação segura por API Key.
Selo em todas as páginas.
Página premium com QR Code.
Health checks e Request ID.
Integração validada com n8n.

BOAS PRÁTICAS

Segurança

O PDF é processado em memória e não deve ser persistido sem autorização.
A API Key deve permanecer em cofre de credenciais ou variável de ambiente.
O conteúdo Base64 do documento não deve ser registrado nos logs.
A senha do certificado e o arquivo PFX nunca devem ser enviados em uma requisição comum.
O arquivo final deve ser preservado exatamente como retornado pela API.