Evidências e Verificação

Após a conclusão de uma transação, a API gera um pacote de evidências com todas as informações da operação. A verificação pública permite que terceiros validem a autenticidade sem autenticação.

Passo 1: Obter evidências (autenticado)

Retorna o pacote completo de evidências de uma transação concluída.

const evidence = await client.evidence.get(tx.transactionId);

console.log(evidence.evidenceId);
console.log(evidence.status);
console.log(evidence.signer.name);
console.log(evidence.signer.userExternalId);

// Documento assinado
if (evidence.document) {
  console.log(evidence.document.hash);     // SHA-256 do documento
  console.log(evidence.document.filename);
}

// Etapas com resultados
for (const step of evidence.steps) {
  console.log(step.type, step.status, step.completedAt);
}

evidence = client.evidence.get(tx.transaction_id)

print(evidence.evidence_id)
print(evidence.status)
print(evidence.signer.name)

if evidence.document:
    print(evidence.document.hash)
    print(evidence.document.filename)

for step in evidence.steps:
    print(step.type, step.status, step.completed_at)

evidence, _ := client.Evidence.Get(ctx, tx.TransactionID)

fmt.Println(evidence.EvidenceID)
fmt.Println(evidence.Status)
fmt.Println(evidence.Signer.Name)

if evidence.Document != nil {
    fmt.Println(evidence.Document.Hash)
    fmt.Println(evidence.Document.Filename)
}

for _, step := range evidence.Steps {
    fmt.Println(step.Type, step.Status, step.CompletedAt)
}

Evidence evidence = client.evidence().get(tx.transactionId);

System.out.println(evidence.evidenceId);
System.out.println(evidence.status);
System.out.println(evidence.signer.name);

if (evidence.document != null) {
    System.out.println(evidence.document.hash);
    System.out.println(evidence.document.filename);
}

for (Evidence.EvidenceStep step : evidence.steps) {
    System.out.println(step.type + " " + step.status);
}

$evidence = $client->evidence->get($tx->transactionId);

echo $evidence->evidenceId;
echo $evidence->status;
echo $evidence->signer['name'];

if ($evidence->document) {
    echo $evidence->document['hash'];
    echo $evidence->document['filename'];
}

foreach ($evidence->steps as $step) {
    echo $step['type'] . ' ' . $step['status'];
}

using SignDocsBrasil.Api;
using SignDocsBrasil.Api.Models;

var evidence = await client.Evidence.GetAsync(tx.TransactionId);

Console.WriteLine(evidence.EvidenceId);
Console.WriteLine(evidence.Status);
Console.WriteLine(evidence.Signer.Name);
Console.WriteLine(evidence.Signer.UserExternalId);

// Documento assinado
if (evidence.Document != null)
{
    Console.WriteLine(evidence.Document.Hash);     // SHA-256 do documento
    Console.WriteLine(evidence.Document.Filename);
}

// Etapas com resultados
foreach (var step in evidence.Steps)
{
    Console.WriteLine($"{step.Type} {step.Status} {step.CompletedAt}");
}

Passo 2: Verificação pública (sem autenticação)

Endpoint público que permite a qualquer pessoa verificar a autenticidade de uma evidência. Não requer token de acesso.

const result = await client.verification.verify(evidenceId);

console.log(result.evidenceId);
console.log(result.transactionId);
console.log(result.status);              // COMPLETED
console.log(result.signer.displayName);
console.log(result.completedAt);

result = client.verification.verify(evidence_id)

print(result.evidence_id)
print(result.transaction_id)
print(result.status)              # COMPLETED
print(result.signer.display_name)

result, _ := client.Verification.Verify(ctx, evidenceID)

fmt.Println(result.EvidenceID)
fmt.Println(result.TransactionID)
fmt.Println(result.Status)            // COMPLETED
fmt.Println(result.Signer.DisplayName)

VerificationResponse result = client.verification().verify(evidenceId);

System.out.println(result.evidenceId);
System.out.println(result.transactionId);
System.out.println(result.status);              // COMPLETED
System.out.println(result.signer.displayName);

$result = $client->verification->verify($evidenceId);

echo $result->evidenceId;
echo $result->transactionId;
echo $result->status;                  // COMPLETED
echo $result->signer['displayName'];

using SignDocsBrasil.Api;
using SignDocsBrasil.Api.Models;

var verification = await client.Evidence.VerifyAsync(evidence.EvidenceId);

Console.WriteLine(verification.EvidenceId);
Console.WriteLine(verification.TransactionId);
Console.WriteLine(verification.Status);              // COMPLETED
Console.WriteLine(verification.Signer.DisplayName);
Console.WriteLine(verification.CompletedAt);

Passo 3: Downloads (sem autenticação)

Obtém URLs pré-assinadas para download dos artefatos de evidência. Também público.

const downloads = await client.verification.downloads(evidenceId);

console.log(downloads.expiresAt);

// Relatório de evidências (documento com todas as etapas, timestamps e resultados)
if (downloads.evidenceReportUrl) {
  console.log(downloads.evidenceReportUrl);
}

// Documento assinado (com assinaturas digitais embutidas ou .p7s separado)
if (downloads.signedDocumentUrl) {
  console.log(downloads.signedDocumentUrl);
}

downloads = client.verification.downloads(evidence_id)

print(downloads.expires_at)

if downloads.evidence_report_url:
    print(downloads.evidence_report_url)

if downloads.signed_document_url:
    print(downloads.signed_document_url)

downloads, _ := client.Verification.Downloads(ctx, evidenceID)

fmt.Println(downloads.ExpiresAt)

if downloads.EvidenceReportURL != "" {
    fmt.Println(downloads.EvidenceReportURL)
}
if downloads.SignedDocumentURL != "" {
    fmt.Println(downloads.SignedDocumentURL)
}

VerificationDownloadsResponse downloads = client.verification().downloads(evidenceId);

System.out.println(downloads.expiresAt);

if (downloads.evidenceReportUrl != null) {
    System.out.println(downloads.evidenceReportUrl);
}
if (downloads.signedDocumentUrl != null) {
    System.out.println(downloads.signedDocumentUrl);
}

$downloads = $client->verification->downloads($evidenceId);

echo $downloads->expiresAt;

if ($downloads->evidenceReportUrl) {
    echo $downloads->evidenceReportUrl;
}
if ($downloads->signedDocumentUrl) {
    echo $downloads->signedDocumentUrl;
}

using SignDocsBrasil.Api;
using SignDocsBrasil.Api.Models;

var pack = await client.Evidence.DownloadAsync(tx.TransactionId);

Console.WriteLine(pack.ExpiresAt);

// Relatório de evidências (documento com todas as etapas, timestamps e resultados)
if (pack.EvidenceReportUrl != null)
{
    Console.WriteLine(pack.EvidenceReportUrl);
}

// Documento assinado (com assinaturas digitais embutidas ou .p7s separado)
if (pack.SignedDocumentUrl != null)
{
    Console.WriteLine(pack.SignedDocumentUrl);
}

Tipos de download

Artefato	Campo	Descrição
Relatório de evidências	`evidenceReportUrl`	Documento com todas as etapas, timestamps, resultados e metadados
Documento assinado	`signedDocumentUrl`	Documento original com assinaturas digitais (PAdES para PDF, CAdES .p7s para demais formatos)

As URLs são pré-assinadas e expiram no horário indicado em expiresAt.

Verificar se um PDF está assinado (autenticado · produção)

Diferente da verificação pública por evidenceId acima, este endpoint recebe um PDF arbitrário (base64) e informa se ele contém uma assinatura digital embutida (PAdES/CAdES), listando as assinaturas encontradas.

Requer autenticação e credenciais de produção. O scope verification:write é obrigatório e chaves de sandbox/homologação recebem 403. É detecção apenas: não extrai identidade do signatário, não valida cadeia ICP-Brasil/revogação, e não consulta registros do SignDocs. Arquivos .p7s/.p7m avulsos não são PDFs e são rejeitados (400). O type de cada assinatura é um de pades, pkcs7, legacy ou digital_certificate.

import { readFileSync } from 'node:fs';

const content = readFileSync('contrato.pdf').toString('base64');
const result = await client.verification.verifyDocument({ content, filename: 'contrato.pdf' });

console.log(result.signed);          // true | false
console.log(result.signatureCount);
for (const sig of result.signatures) {
  console.log(sig.type, sig.subFilter, sig.confidence);
}

import base64
from signdocs_brasil.models import VerifyDocumentRequest

content = base64.b64encode(open("contrato.pdf", "rb").read()).decode()
result = client.verification.verify_document(
    VerifyDocumentRequest(content=content, filename="contrato.pdf")
)

print(result.signed)            # True | False
print(result.signature_count)
for sig in result.signatures:
    print(sig.type, sig.sub_filter, sig.confidence)

import (
    "encoding/base64"
    "os"
)

raw, _ := os.ReadFile("contrato.pdf")
content := base64.StdEncoding.EncodeToString(raw)

result, _ := client.Verification.VerifyDocument(ctx, &signdocs.VerifyDocumentRequest{
    Content:  content,
    Filename: "contrato.pdf",
})

fmt.Println(result.Signed)           // true | false
fmt.Println(result.SignatureCount)
for _, sig := range result.Signatures {
    fmt.Println(sig.Type, sig.SubFilter, sig.Confidence)
}

String content = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("contrato.pdf")));

VerifyDocumentResponse result = client.verification()
    .verifyDocument(new VerifyDocumentRequest(content, "contrato.pdf"));

System.out.println(result.signed);          // true | false
System.out.println(result.signatureCount);
for (DetectedSignature sig : result.signatures) {
    System.out.println(sig.type + " " + sig.subFilter + " " + sig.confidence);
}

$content = base64_encode(file_get_contents('contrato.pdf'));
$result = $client->verification->verifyDocument(
    new VerifyDocumentRequest($content, 'contrato.pdf')
);

echo $result->signed;            // true | false
echo $result->signatureCount;
foreach ($result->signatures as $sig) {
    echo $sig->type . ' ' . $sig->subFilter . ' ' . $sig->confidence;
}

using SignDocsBrasil.Api;
using SignDocsBrasil.Api.Models;

var content = Convert.ToBase64String(File.ReadAllBytes("contrato.pdf"));
var result = await client.Verification.VerifyDocumentAsync(
    new VerifyDocumentRequest { Content = content, Filename = "contrato.pdf" });

Console.WriteLine(result.Signed);            // true | false
Console.WriteLine(result.SignatureCount);
foreach (var sig in result.Signatures)
{
    Console.WriteLine($"{sig.Type} {sig.SubFilter} {sig.Confidence}");
}

Metadados do canal de origem

A partir da versão 1.3 dos pacotes de evidência, o objeto de evidência pode incluir um campo metadata com informações sobre o canal de origem da transação. Exemplos:

`source`	Descrição
`telegram_bot`	Transação originada pelo bot Telegram.
`google_drive`	Transação originada pelo add-on Google Drive.
`api`	Transação criada diretamente via API.
`signing_session`	Transação criada via sessão de assinatura expressa.

Este campo é informativo e não afeta a validade jurídica da evidência.