Consignado Privado

Módulo de integração com a Dataprev (Consulta Trabalhador) para viabilizar o crédito consignado privado. Os três recursos desta seção não são um CRUD livre: cada POST registra uma consulta à Dataprev, autorizada pelo token de um termo de autorização ativo, e a processa em segundo plano. O resultado fica gravado como um registro histórico com id/code próprios.

Recurso	Rota base	Operação Dataprev
Vínculos empregatícios	v5/private-payroll-employment-relationships	listar-autorizados-trabalhador — lista os vínculos do CPF
Dados do trabalhador	v5/private-payroll-employee-data	consultar-dados-trabalhador — renda, margem, empregador, alertas, empréstimos legados
Saldo FGTS	v5/private-payroll-fgts-balances	consultar-saldo-fgts — saldo e multa rescisória disponíveis para garantia

A configuração da Dataprev (código de solicitante, credenciais) é feita por empresa pela equipe da Semear.

Processamento assíncrono

Nenhuma chamada deste módulo aguarda a Dataprev. O fluxo é sempre o mesmo:

1. A API valida o que não depende do provedor (termo, vínculo, CPF, completude do vínculo) com os mesmos códigos de erro de sempre.
2. Grava a consulta com status pending ("Consultando") e responde imediatamente com esse registro.
3. Em segundo plano, a consulta é feita na Dataprev e o mesmo registro é atualizado para sucesso ou erro. Em erro, status.note traz o motivo retornado pela Dataprev.

O resultado pode ser acompanhado de duas formas:

• Eventos de webhook, assinando os tipos abaixo. O payload é a própria consulta, no mesmo formato da resposta do POST. É a forma recomendada, e a única para dados do trabalhador e saldo FGTS, que não têm GET /{id} na API de integração.
• Consulta periódica, só para vínculos, pelo GET /v5/private-payroll-employment-relationships/{id}, até o status sair de pending.

Evento	Code	Quando
private_payroll_employment_relationship.completed	2000	Consulta de vínculos concluída, com ou sem vínculos encontrados.
private_payroll_employment_relationship.failed	2001	Consulta de vínculos terminou em erro.
private_payroll_employee_data.completed	2010	Consulta de dados do trabalhador concluída.
private_payroll_employee_data.failed	2011	Consulta de dados do trabalhador terminou em erro.
private_payroll_fgts_balance.completed	2020	Consulta de saldo FGTS concluída.
private_payroll_fgts_balance.failed	2021	Consulta de saldo FGTS terminou em erro.
authorization_term.accepted	1705	O trabalhador aceitou o termo pela jornada de aceite; a autorização na Dataprev é disparada em seguida.
authorization_term.activated	1700	A Dataprev autorizou o termo; token e expiresAt preenchidos.
authorization_term.rejected	1703	A Dataprev recusou a autorização do termo, ou o trabalhador recusou o termo na jornada de aceite.

O mesmo modelo vale para o termo de autorização, criado como Pendente e autorizado na Dataprev em segundo plano depois que o aceite do trabalhador é registrado, e para a formalização, a averbação, o envio do contrato e a desaverbação do empréstimo. Os eventos do empréstimo estão em Eventos do empréstimo.

Novas tentativas e limite de chamadas

• Falhas temporárias da Dataprev (tempo esgotado, indisponibilidade) são repetidas automaticamente algumas vezes, com espera crescente entre as tentativas.
• Quando a cota da Dataprev é excedida, o processamento é adiado até o horário indicado pelo provedor.
• Erros de negócio (como IV ou TS) encerram o processamento na hora, sem nova tentativa.
• As chamadas à Dataprev são limitadas por empresa a um número de consultas por segundo, somando todos os tipos de consulta. O limite é configurado no grupo de configurações da Dataprev da empresa ("Consultas por Segundo", chave requests_per_second); quando não informado, vale 25 por segundo. Quando a cota do ambiente é por minuto, como em homologação (cerca de 10 chamadas por minuto), preencha "Consultas por Minuto" (chave requests_per_minute): esse valor substitui o limite por segundo e distribui as chamadas ao longo do minuto.

Sempre que outro fluxo da API procura a última consulta válida de um trabalhador ou vínculo, só consultas concluídas com sucesso são consideradas.

Jornada completa do consignado privado

As três consultas são a primeira metade de uma jornada que termina no contrato averbado e desembolsado:

POST /v5/loan-private-payrolls/terms ............ termo de autorização (termId)
   │
POST /v5/private-payroll-employment-relationships  vínculos → employmentRelationshipId
   │
   ├── POST /v5/private-payroll-employee-data ..... employeeDataId
   └── POST /v5/private-payroll-fgts-balances ..... fgtsBalanceId
   │
POST /v5/loan-simulations ....................... simulação (opcional)
   │
POST /v5/loans .................................. emissão, com o bloco privatePayroll
   │                                              { employeeDataId, fgtsBalanceId, garantia }
POST /v5/loans/{id}/signature-requests .......... CCB + assinatura eletrônica + jornada do tomador
   │                                              (tomador assina → status signed)
PUT  /v5/loans/{id}/endorsements ................ averbação na Dataprev
   │
POST /v5/loan-private-payrolls/{id}/contract-information  envio da CCB assinada à Dataprev
   │
PUT  /v5/loans/{id}/disbursements ............... desembolso

Se o contrato averbado não for desembolsado dentro do prazo configurado pela empresa, a averbação é excluída na Dataprev e o contrato é cancelado — ver Desaverbação automática.

O employeeDataId e o fgtsBalanceId são o elo entre as consultas e o contrato: informados no bloco privatePayroll da emissão, eles copiam para o empréstimo a matrícula, a inscrição do empregador, a elegibilidade, a margem e os valores de FGTS que a averbação vai exigir. Sem eles, o contrato é emitido mas não averba.

A emissão aceita três modos de cálculo — por valor da parcela (installmentAmount), por valor líquido (disbursementAmount) ou por valor contratado (principalAmount). No consignado privado com garantia de FGTS, o modo por valor contratado costuma ser o mais prático, porque a Dataprev exige que a garantia cubra exatamente o valor do empréstimo.

Encadeamento entre os três recursos

Termo ativo (authorizationTermId)
   │
   ▼
POST /v5/private-payroll-employment-relationships ──► items[].id  (um por vínculo)
   │
   ├──► POST /v5/private-payroll-employee-data   { authorizationTermId, employmentRelationshipId }
   │
   └──► POST /v5/private-payroll-fgts-balances   { authorizationTermId, employmentRelationshipId }

O vínculo (items[].id da consulta de vínculos) é a chave das duas consultas seguintes: a partir dele o servidor carrega matrícula, tipo e número de inscrição do empregador, e valida que o CPF do vínculo é o mesmo do subject do termo.

Autenticação

Todos os endpoints exigem API Key. Cada recurso tem duas permissões: consultar (executar o POST) e acessar (ler pelo GET, quando existe). Além disso, o nível de acesso do usuário (própria unidade, parceiro, agência, agente ou usuário) limita quais consultas gravadas ele enxerga.

Validações comuns às três consultas

Antes de registrar a consulta, a API valida o termo e, quando aplicável, o vínculo. Essas validações continuam síncronas e voltam 400 no próprio POST. Os códigos mudam de prefixo por módulo (4050, 4051, 4053), mas a sequência é a mesma:

Sufixo	Validação	Texto
002	authorizationTermId informado	Informe o termo de autorização do trabalhador
003	Termo existe e está no nível de acesso	Termo de autorização não encontrado
004	status = active e expiresAt no futuro	Termo de autorização não está ativo ou expirou
005	token preenchido	Termo de autorização sem token do provedor
007	employmentRelationshipId informado (dados e FGTS)	Informe o vínculo empregatício a consultar
008	Vínculo existe (dados e FGTS)	Vínculo empregatício não encontrado
009	CPF do vínculo = CPF do termo (dados e FGTS)	O vínculo informado não pertence ao trabalhador do termo de autorização
010	Vínculo tem matrícula e inscrição do empregador (dados e FGTS)	O vínculo informado não possui matrícula ou inscrição do empregador

A lista completa está em Tratamento de erros.

Comportamento em falha do provedor

A falha na Dataprev não volta no POST, que já respondeu com a consulta em pending. Ela é registrada depois, no mesmo registro:

Recurso	Falha na Dataprev
Vínculos	A consulta passa a status = error (motivo em status.note) e o evento private_payroll_employment_relationship.failed é publicado.
Dados do trabalhador	A consulta passa a status = error (motivo em status.note) e o evento private_payroll_employee_data.failed é publicado.
Saldo FGTS	A consulta passa a status = error (motivo em status.note) e o evento private_payroll_fgts_balance.failed é publicado.

Campos com código vindo diretamente da Dataprev

employerDocumentType, gender, nationalityCountry, politicallyExposedPerson, cbo, cnae, loanBlockType e os tipos de alerts[]/legacyLoans[] são objetos { code, name } preenchidos com o código e a descrição devolvidos pela própria Dataprev — não são listas fixas da API.

Eventos do empréstimo

Publicados ao longo da vida do contrato de consignado privado. O payload é um resumo do empréstimo (identificadores, status, datas, valores e taxas principais).

Evento	Code	Quando
loan.document_created	1006	A CCB foi gerada e anexada ao contrato.
loan.document_failed	1014	A geração da CCB (ou da CCB com o link de assinatura) terminou em falha.
loan.signature_requested	1010	Envelope de assinatura e jornada de formalização criados; contrato em awaiting_formalization.
loan.signed	1007	O tomador concluiu a assinatura eletrônica; contrato em signed.
loan.endorsement_requested	1011	Averbação enviada à Dataprev; contrato em endorsement_processing.
loan.endorsed	1005	A Dataprev confirmou a averbação.
loan.endorsement_failed	1008	A Dataprev recusou a averbação.
private_payroll_loan.contract_information_sent	2050	A Dataprev aceitou o envio da CCB assinada e das evidências.
private_payroll_loan.contract_information_failed	2051	O envio do contrato à Dataprev terminou em erro.
loan.disbursement_requested	1012	Desembolso enviado ao banco liquidante ou ao pagador.
loan.disbursed	1002	Desembolso confirmado.
loan.disbursement_failed	1013	Desembolso recusado ou não concluído.
private_payroll_loan.exclusion_completed	2052	Averbação excluída na Dataprev pela desaverbação automática.
private_payroll_loan.exclusion_failed	2053	A exclusão da averbação na Dataprev terminou em erro.
loan.canceled	1004	Contrato cancelado (inclusive pela desaverbação automática).

O antigo evento private_payroll_worker_profile.completed (2040) deixou de existir junto com a consulta de perfil do trabalhador: as consultas de bureau e de autorregulação passaram para Consultas.

Consultas externas e jornadas

• Consultas de bureau e autorregulação (por exemplo, perfil do trabalhador em bureau de crédito e as consultas de autorregulação do pagador) não fazem parte deste módulo: são feitas por v5/queries. A autorregulação não roda mais automaticamente antes da CCB; quando exigida pelo convênio, deve ser solicitada como consulta.
• Jornadas: o aceite do termo e a assinatura da CCB pelo trabalhador acontecem em páginas de jornada geradas pela plataforma. Ver Jornadas.

Páginas deste módulo

• Vínculos empregatícios (private-payroll-employment-relationships)
• Dados do trabalhador (private-payroll-employee-data)
• Saldo FGTS (private-payroll-fgts-balances)
• Leilão de propostas
• Massa de teste em homologação

A emissão, a assinatura, a averbação e o desembolso estão em Empréstimos.