Guias de Desenvolvimento

Signing Sessions

Guias dos SDKs

NT65 Consignado — BIOMETRIC_SERPRO_AUTO_FALLBACK

Conformidade NT65 para crédito consignado INSS. Biometria com fallback automático para foto de documento.

1. O que é

O perfil mais completo. Garante conformidade com a NT65 do INSS para crédito consignado. Adiciona divulgação de finalidade antes da biometria e inclui fallback automático para comparação por foto de documento quando o SERPRO não possui dados biométricos do beneficiário.

DIVULGAÇÃO DE FINALIDADE ──> Liveness ──> Comparação facial ──> Validação SERPRO
                                                                      │
                                                  ┌───────────────────┤
                                                  │                   │
                                             SERPRO OK           SERPRO sem biometria
                                                  │                   │
                                             COMPLETED       FOTO DE DOCUMENTO ativa
                                                                      │
                                                                 COMPLETED

2. Requisitos

Campo Obrigatório Notas
name Sim Nome completo
cpf Sim CPF do beneficiário
birthDate Sim Data de nascimento (YYYY-MM-DD)
userExternalId Sim ID no seu sistema

Feature flags necessárias no tenant: nt65ComplianceEnabled, serpro.enabled, documentExtractionEnabled

3. Criar a sessão

Crie a sessão no backend. A página hospedada cuida de tudo.

import { readFileSync } from 'fs';

const pdfBase64 = readFileSync('contrato-consignado.pdf').toString('base64');

const session = await client.signingSessions.create({
  purpose: 'DOCUMENT_SIGNATURE',
  policy: { profile: 'BIOMETRIC_SERPRO_AUTO_FALLBACK' },
  signer: {
    name: 'Roberto Santos',
    cpf: '12345678901',
    birthDate: '1985-03-15',
    userExternalId: 'user-005',
  },
  document: { content: pdfBase64, filename: 'contrato-consignado.pdf' },
  // Opcional: pré-upload de foto de documento para fallback
  fallbackDocument: {
    image: cnhPhotoBase64,
    type: 'CNH',
  },
  returnUrl: 'https://app.example.com/done',
  locale: 'pt-BR',
  expiresInMinutes: 60,
});

import base64

with open('contrato-consignado.pdf', 'rb') as f:
    pdf_base64 = base64.b64encode(f.read()).decode()

session = client.signing_sessions.create(CreateSigningSessionRequest(
    purpose='DOCUMENT_SIGNATURE',
    policy=Policy(profile='BIOMETRIC_SERPRO_AUTO_FALLBACK'),
    signer=Signer(
        name='Roberto Santos', cpf='12345678901',
        birth_date='1985-03-15', user_external_id='user-005',
    ),
    document=InlineDocument(content=pdf_base64, filename='contrato-consignado.pdf'),
    fallback_document=FallbackDocument(image=cnh_photo_base64, type='CNH'),
    return_url='https://app.example.com/done',
    locale='pt-BR',
    expires_in_minutes=60,
))

pdfBytes, _ := os.ReadFile("contrato-consignado.pdf")
pdfBase64 := base64.StdEncoding.EncodeToString(pdfBytes)

session, err := client.SigningSessions.Create(ctx, &signdocs.CreateSigningSessionRequest{
    Purpose: signdocs.PurposeDocumentSignature,
    Policy:  signdocs.Policy{Profile: "BIOMETRIC_SERPRO_AUTO_FALLBACK"},
    Signer: signdocs.Signer{
        Name: "Roberto Santos", CPF: "12345678901",
        BirthDate: "1985-03-15", UserExternalID: "user-005",
    },
    Document:         &signdocs.DocumentInline{Content: pdfBase64, Filename: "contrato-consignado.pdf"},
    FallbackDocument: &signdocs.FallbackDocument{Image: cnhPhotoBase64, Type: "CNH"},
    ReturnURL:        "https://app.example.com/done",
    Locale:           "pt-BR",
    ExpiresInMinutes: 60,
})

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

String pdfBase64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("contrato-consignado.pdf")));
CreateSigningSessionRequest request = new CreateSigningSessionRequest();
request.purpose = "DOCUMENT_SIGNATURE";
request.policy = new Policy("BIOMETRIC_SERPRO_AUTO_FALLBACK");
request.signer = new Signer("Roberto Santos", "user-005");
request.signer.cpf = "12345678901";
request.signer.birthDate = "1985-03-15";
request.document = new CreateSigningSessionRequest.InlineDocument(pdfBase64, "contrato-consignado.pdf");
request.returnUrl = "https://app.example.com/done";
request.locale = "pt-BR";
request.expiresInMinutes = 60;
SigningSession session = client.signingSessions().create(request);

$pdfBase64 = base64_encode(file_get_contents('contrato-consignado.pdf'));

$session = $client->signingSessions->create(new CreateSigningSessionRequest(
    purpose: 'DOCUMENT_SIGNATURE',
    policy: new Policy(profile: 'BIOMETRIC_SERPRO_AUTO_FALLBACK'),
    signer: new Signer(
        name: 'Roberto Santos', cpf: '12345678901',
        birthDate: '1985-03-15', userExternalId: 'user-005',
    ),
    document: ['content' => $pdfBase64, 'filename' => 'contrato-consignado.pdf'],
    returnUrl: 'https://app.example.com/done',
    locale: 'pt-BR',
    expiresInMinutes: 60,
));

using SignDocsBrasil.Api.Models;

var pdfBase64 = Convert.ToBase64String(await File.ReadAllBytesAsync("contrato-consignado.pdf"));

var session = await client.SigningSessions.CreateAsync(new CreateSigningSessionRequest
{
    Purpose = "DOCUMENT_SIGNATURE",
    Policy = new Policy { Profile = "BIOMETRIC_SERPRO_AUTO_FALLBACK" },
    Signer = new Signer
    {
        Name = "Roberto Santos", Cpf = "12345678901",
        BirthDate = "1985-03-15", UserExternalId = "user-005",
    },
    Document = new InlineDocument { Content = pdfBase64, Filename = "contrato-consignado.pdf" },
    ReturnUrl = "https://app.example.com/done",
    Locale = "pt-BR",
    ExpiresInMinutes = 60,
});

4. Três resultados possíveis do SERPRO

Resultado Descrição O que acontece
COMPLETED SERPRO validou a identidade Transação finalizada normalmente. Etapa DORMANT ignorada.
SKIPPED SERPRO possui dados biográficos mas sem imagem biométrica para este CPF DOCUMENT_PHOTO_MATCH ativa automaticamente (DORMANT → PENDING). Se fallbackDocument foi pré-enviado, a foto é usada automaticamente.
FAILED Dados incompatíveis (CPF/nome/data errados) ou pontuação biométrica baixa Fallback não é ativado. Corrija os dados e tente novamente.

5. Webhooks NT65

Evento Quando
STEP.PURPOSE_DISCLOSURE_SENT Notificação de finalidade enviada ao beneficiário
TRANSACTION.DEADLINE_APPROACHING 2 dias úteis antes do prazo de submissão ao INSS
TRANSACTION.FALLBACK SERPRO sem dados biométricos, fallback por foto ativado

6. Checklist de conformidade NT65

← Biometria SERPRO
Próximo: Política Customizada →
Voltar para Visão Geral