Biometria SERPRO (BIOMETRIC_SERPRO)

Para o fluxo completo de conformidade NT65 (consignado INSS), consulte NT65 Consignado INSS.

O perfil BIOMETRIC_SERPRO utiliza a base biométrica do SERPRO (Governo Federal) para validação de identidade. Requer CPF e data de nascimento do signatário.

Campos obrigatórios: cpf no signer + birthDate nos metadata

Passo 1: Criar transação

const tx = await client.transactions.create({
  purpose: 'DOCUMENT_SIGNATURE',
  policy: { profile: 'BIOMETRIC_SERPRO' },
  signer: {
    name: 'João Silva',
    userExternalId: 'user-001',
    cpf: '12345678900',
  },
  document: { content: documentBase64, filename: 'contrato.pdf' },
  metadata: {
    birthDate: '1990-05-15',
  },
});

tx = client.transactions.create(CreateTransactionRequest(
    purpose='DOCUMENT_SIGNATURE',
    policy=Policy(profile='BIOMETRIC_SERPRO'),
    signer=Signer(name='João Silva', user_external_id='user-001', cpf='12345678900'),
    document=InlineDocument(content=document_base64, filename='contrato.pdf'),
    metadata={'birthDate': '1990-05-15'},
))

tx, _ := client.Transactions.Create(ctx, &signdocs.CreateTransactionRequest{
    Purpose: signdocs.TransactionPurposeDocumentSignature,
    Policy:  signdocs.Policy{Profile: "BIOMETRIC_SERPRO"},
    Signer:  signdocs.Signer{Name: "João Silva", UserExternalID: "user-001", CPF: "12345678900"},
    Document: &signdocs.DocumentInline{Content: documentBase64, Filename: "contrato.pdf"},
    Metadata: map[string]string{"birthDate": "1990-05-15"},
})

CreateTransactionRequest request = new CreateTransactionRequest();
request.purpose = "DOCUMENT_SIGNATURE";
request.policy = new Policy("BIOMETRIC_SERPRO");
request.signer = new Signer("João Silva", null, "user-001");
request.signer.cpf = "12345678900";
request.document = new CreateTransactionRequest.InlineDocument(documentBase64, "contrato.pdf");
request.metadata = Map.of("birthDate", "1990-05-15");

Transaction tx = client.transactions().create(request);

$tx = $client->transactions->create(new CreateTransactionRequest(
    purpose: 'DOCUMENT_SIGNATURE',
    policy: new Policy(profile: 'BIOMETRIC_SERPRO'),
    signer: new Signer(name: 'João Silva', userExternalId: 'user-001', cpf: '12345678900'),
    document: ['content' => $documentBase64, 'filename' => 'contrato.pdf'],
    metadata: ['birthDate' => '1990-05-15'],
));

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

var client = SignDocsBrasilClient.CreateBuilder()
    .ClientId("your-client-id")
    .ClientSecret("your-client-secret")
    .Build();

var tx = await client.Transactions.CreateAsync(new CreateTransactionRequest
{
    Purpose = "DOCUMENT_SIGNATURE",
    Policy = new Policy { Profile = "BIOMETRIC_SERPRO" },
    Signer = new Signer { Name = "João Silva", UserExternalId = "user-001", Cpf = "12345678900" },
    Document = new InlineDocument { Content = documentBase64, Filename = "contrato.pdf" },
    Metadata = new Dictionary<string, string> { ["birthDate"] = "1990-05-15" },
});

Passo 2: Etapa SERPRO_IDENTITY_CHECK

A etapa é processada automaticamente pela API. O sistema consulta a base biométrica do SERPRO usando o CPF informado. Inicie e complete a etapa:

const steps = await client.steps.list(tx.transactionId);
const serproStep = steps.find(s => s.type === 'SERPRO_IDENTITY_CHECK');

await client.steps.start(tx.transactionId, serproStep.stepId);
const result = await client.steps.complete(tx.transactionId, serproStep.stepId);

steps = client.steps.list(tx.transaction_id)
serpro_step = next(s for s in steps if s.type == 'SERPRO_IDENTITY_CHECK')

client.steps.start(tx.transaction_id, serpro_step.step_id)
result = client.steps.complete(tx.transaction_id, serpro_step.step_id)

steps, _ := client.Steps.List(ctx, tx.TransactionID)
// Encontrar a etapa SERPRO_IDENTITY_CHECK
var serproStep signdocs.Step
for _, s := range steps {
    if s.Type == "SERPRO_IDENTITY_CHECK" {
        serproStep = s
        break
    }
}

client.Steps.Start(ctx, tx.TransactionID, serproStep.StepID, nil)
result, _ := client.Steps.Complete(ctx, tx.TransactionID, serproStep.StepID, nil)

List<Step> steps = client.steps().list(tx.transactionId);
Step serproStep = steps.stream()
    .filter(s -> "SERPRO_IDENTITY_CHECK".equals(s.type))
    .findFirst().orElseThrow();

client.steps().start(tx.transactionId, serproStep.stepId);
Step result = client.steps().complete(tx.transactionId, serproStep.stepId);

$steps = $client->steps->list($tx->transactionId);
$serproStep = current(array_filter($steps, fn($s) => $s->type === 'SERPRO_IDENTITY_CHECK'));

$client->steps->start($tx->transactionId, $serproStep->stepId);
$result = $client->steps->complete($tx->transactionId, $serproStep->stepId);

var steps = await client.Steps.ListAsync(tx.TransactionId);
var serproStep = steps.First(s => s.Type == "SERPRO_IDENTITY_CHECK");

await client.Steps.StartAsync(tx.TransactionId, serproStep.StepId);
var result = await client.Steps.CompleteAsync(tx.TransactionId, serproStep.StepId);

Passo 3: Finalizar transação

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

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

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

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

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

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

Government Database Validation

A partir da versão 1.3 da API, o resultado da etapa SERPRO_IDENTITY_CHECK inclui um objeto governmentDbValidation com informações detalhadas da validação contra a base governamental. Este objeto aparece no result da etapa ao consultá-la após conclusão.

Exemplo de resultado completo da etapa:

{
  "serproIdentity": {
    "valid": true,
    "provider": "serpro_datavalid",
    "nameMatch": true,
    "birthDateMatch": true,
    "biometricMatch": true,
    "biometricConfidence": 0.95,
    "governmentDatabase": "SERPRO_DATAVALID",
    "biometricScore": 0.95
  },
  "governmentDbValidation": {
    "database": "SERPRO_DATAVALID",
    "validatedAt": "2026-04-06T15:30:00Z",
    "cpfHash": "sha256:...",
    "biometricScore": 0.95,
    "cached": false
  }
}

Campo	Tipo	Descrição
`database`	string	Base de dados utilizada (ex: `SERPRO_DATAVALID`).
`validatedAt`	string (ISO 8601)	Momento da validação original.
`cpfHash`	string	Hash SHA-256 do CPF validado.
`biometricScore`	number	Score de similaridade biométrica (0-1).
`cached`	boolean	Se `true`, uma validação SERPRO anterior foi reutilizada após verificação de similaridade facial.
`cacheVerifySimilarity`	number	Score do CompareFaces utilizado para aceitar o cache. Presente apenas quando `cached: true`.

Quando cached: true, isso significa que o sistema encontrou uma validação SERPRO anterior para o mesmo CPF e verificou a similaridade facial entre a imagem atual e a imagem da validação original via CompareFaces. O campo cacheVerifySimilarity indica o score dessa comparação.

Cache de verificação

A verificação SERPRO é cacheada por 24 meses. Consultas subsequentes para o mesmo CPF dentro deste período não geram novas chamadas ao SERPRO, reduzindo custos e latência.