Evidências do Carimbo Autenticado

Baixa, em um único ZIP, a prova criptográfica de todos os carimbos autenticados (assinatura com certificado em nuvem ICP-Brasil) aplicados a uma operação. O ZIP contém uma pasta por assinante — cada pasta é autossuficiente e pode ser validada de forma independente — mais um README.txt com as instruções de validação.

Quando usar

• Arquivamento jurídico: guardar a prova criptográfica completa fora da ForSign
• Auditoria ou perícia que exija validar cada assinatura de forma independente
• Integrações que anexam o pacote de evidências ao dossiê do próprio sistema

Endpoint

curl -X GET "https://example.com/api/v1/operation/0/authenticated-stamp/evidence-package"

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Existe também a variante por assinante, que devolve o mesmo pacote filtrado para um único carimbo:

curl -X GET "https://example.com/api/v1/operation/0/authenticated-stamp/497f6eca-6276-4993-bfeb-53cbbbba6f08/evidence-package"

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

O stampId de cada assinante vem da listagem de carimbos da operação:

curl -X GET "https://example.com/api/v1/operation/0/authenticated-stamp"

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

{
  "success": true,
  "statusCode": 0,
  "data": null,
  "messages": [
    {
      "key": "string",
      "value": "string"
    }
  ]
}

Parâmetros

Não há query string nem request body.

Resposta

O corpo segue o envelope padrão da API; o ZIP vem em Base64 dentro de data:

{
  "success": true,
  "statusCode": 200,
  "data": {
    "name": "pacote-evidencias-carimbo-12345.zip",
    "base64File": "UEsDBBQAAAAIA...(ZIP em Base64)..."
  },
  "messages": null
}

Estrutura do ZIP

README.txt                          ← instruções de validação (pt-BR)
1-Joao-Silva/
    snapshot.pdf                    ← documento no momento em que ESTE assinante assinou
    signature.p7s                   ← assinatura CMS-detached (PKCS#7 / CAdES-BES) do snapshot
    cert-chain.pem                  ← cadeia de certificados do titular (ICP-Brasil, completada até a raiz)
    metadata.json                   ← titular, CPF mascarado, provedor, data/hora, hash, IP, geolocalização
2-Maria-Souza/
    snapshot.pdf
    signature.p7s
    cert-chain.pem
    metadata.json

• As pastas são numeradas pela ordem de assinatura ({ordem}-{nome-do-assinante}).
• O carimbo autenticado não trava o PDF: cada assinante assina o estado do documento no momento em que assinou, então snapshot.pdf de assinantes diferentes podem diferir. É por isso que a evidência é por assinante, e cada pasta valida sozinha.

Cada metadata.json

Exemplo real dos campos (chaves nulas são omitidas):

{
  "operationId": 98765,
  "operationMemberFileId": 4321,
  "memberKey": "a1b2c3d4...",
  "stampId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "provider": "BirdId",
  "providerDisplayName": "BirdID",
  "holderName": "JOAO SILVA",
  "maskedCpf": "***.456.789-**",
  "certificateSubject": "CN=JOAO SILVA:12345678900, OU=...",
  "certificateSerialNumber": "1A2B3C...",
  "signingTime": "2026-08-14T14:32:10Z",
  "hashAlgorithmOid": "2.16.840.1.101.3.4.2.1",
  "ipAddress": "203.0.113.10",
  "latitude": "-23.550520",
  "longitude": "-46.633308",
  "userAgent": "Mozilla/5.0 ..."
}

Reconstituindo o ZIP (Node.js)

import { writeFile } from 'node:fs/promises';

const res = await fetch(
  `https://api.forsign.digital/api/v1/operation/${operationCompanyId}/authenticated-stamp/evidence-package`,
  { headers: { 'X-Api-Key': process.env.FORSIGN_API_KEY } }
);
if (!res.ok) throw new Error(`Falha ao baixar evidências: ${res.status}`);

const { data } = await res.json();
await writeFile(data.name, Buffer.from(data.base64File, 'base64'));

Erros comuns

Como validar uma assinatura

Dentro da pasta de qualquer assinante, há três caminhos:

1. Validador ForSign — acesse o link ou leia o QR code do dossiê (validador.forsign.digital).
2. Portal VALIDAR / ITI (validade jurídica ICP-Brasil) — https://validar.iti.gov.br, opção "assinatura destacada": snapshot.pdf como documento e signature.p7s como assinatura.
3. Linha de comando (openssl):

openssl cms -verify -in signature.p7s -inform DER \
  -content snapshot.pdf -certfile cert-chain.pem

Para validar a cadeia ICP-Brasil, informe as raízes em -CAfile; sem elas, use -noverify para checar só a integridade da assinatura.

Observações

• Escopo de acesso (LGPD): o pacote inclui dados sensíveis do assinante (IP, geolocalização, user-agent) que não aparecem no snapshot público do carimbo. Por isso este endpoint exige autenticação e permissão de visualização da operação — diferente do download anônimo do snapshot, que devolve o PDF sem esses dados.
• Quando o pacote existe: só operações com pelo menos um carimbo autenticado (assinatura por certificado em nuvem, ex.: BirdID, VIDaaS) aplicado geram evidência. Sem nenhum carimbo, o endpoint devolve 404.
• Uma assinatura por pasta: cada carimbo é uma assinatura CMS-detached independente sobre o snapshot daquele momento. Não existe "assinatura acumulada" no PDF final — a prova jurídica de cada assinante é a tripla snapshot.pdf + signature.p7s + cert-chain.pem da pasta dele.
• Cadeia de certificados completa: o cert-chain.pem entregue já vem completado com as raízes ICP-Brasil quando o provedor devolve a cadeia parcial.
• Nenhum crédito é consumido — o download de evidências é uma operação de leitura.
• Arquive o ZIP inteiro, não só os PDFs: sem o .p7s e a cadeia PEM a assinatura não é verificável de forma independente.

Veja também

• Download em ZIP — os documentos assinados + anexos + CSV de formulários
• Download de documento em Base64 — um documento específico, em JSON
• Criar operação — onde o operationCompanyId nasce