Guias de Desenvolvimento

Signing Sessions

Guias dos SDKs

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: pdfBase64, 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=pdf_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: pdfBase64, 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(pdfBase64, "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' => $pdfBase64, 'filename' => 'contrato.pdf'],
    metadata: ['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);

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);

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.