Vínculos empregatícios (private-payroll-employment-relationships)

Rota base v5/private-payroll-employment-relationships. Ver visão geral do módulo.

É o passo de descoberta: dado um termo ativo, a API chama a Dataprev (listar-autorizados-trabalhador) com o CPF do titular e o token do termo, e grava uma consulta com um item por vínculo encontrado. O id de cada item é o employmentRelationshipId exigido por Dados do trabalhador e Saldo FGTS.

Processamento assíncrono

O POST não aguarda a Dataprev. A API valida o que não depende do provedor, grava a consulta com status pending ("Consultando") e sem itens, e responde imediatamente com esse registro. Em segundo plano, a consulta é feita na Dataprev e o mesmo registro é atualizado para success, empty ou error, com os itens encontrados. Acompanhe o resultado por GET /{id} ou assinando os eventos private_payroll_employment_relationship.completed e private_payroll_employment_relationship.failed, cujo payload é a própria consulta, no mesmo formato do GET /{id}.

Autenticação

API Key. O POST exige permissão de consulta de vínculos; o GET exige permissão de leitura.

Rotas implementadas

Rota	Verbo	Resumo
/v5/private-payroll-employment-relationships	POST	Registra a consulta de vínculos e processa na Dataprev em segundo plano. Aceita um termo existente ou os dados para criar o termo na mesma chamada.
/v5/private-payroll-employment-relationships/{id}	GET	Obtém uma consulta já realizada, com seus itens.

O recurso expõe ainda PUT /{id}/status, busca (GET "", POST search) e GET filter-fields, que não fazem parte da collection.

Campos da entidade

Campo	Tipo	Descrição
id	string (uuid)	Identificador da consulta. Use em GET /{id}.
code	integer	Código sequencial da consulta.
documentNumber	string	CPF do trabalhador, copiado do subject do termo.
name	string	Nome do trabalhador, copiado do termo.
authorizationTermId	string (uuid)	Termo usado (informado ou criado na chamada).
provider	object (code/key/name)	Sempre dataprev (100).
queriedAt	string (date-time)	Momento em que a consulta foi registrada.
items	array	Um item por vínculo (ver abaixo). Vazio enquanto status = pending e quando status = empty ou error.
status	object (Status)	success (1), empty (2, Sem Vínculos), error (3) ou pending (4, Consultando). Em erro, note traz o motivo. Ver PrivatePayrollEmploymentRelationshipStatus.

items[]

Campo	Tipo	Descrição
id	string (uuid)	Identificador do vínculo. É o employmentRelationshipId das consultas seguintes.
documentNumber	string	CPF do trabalhador.
registrationNumber	string	Matrícula do trabalhador no empregador.
employerDocumentType	object (code/name)	Tipo do documento do empregador conforme a Dataprev: 1 CNPJ, 2 CPF (empregador pessoa física).
employerDocumentNumber	string	Número do documento do empregador.
isEligible	boolean	Se o vínculo pode receber consignado segundo o provedor.
isBlockedForLoan	boolean	Se o trabalhador bloqueou a contratação nesse vínculo.
ineligibilityReason	string | null	Motivo de inelegibilidade, quando isEligible = false.

Um vínculo só deve seguir no fluxo quando isEligible = true e isBlockedForLoan = false.

---

POST /v5/private-payroll-employment-relationships

Registra a consulta de vínculos do trabalhador e processa na Dataprev em segundo plano. O payload é o mesmo da criação do termo, com um campo a mais: authorizationTermId.

Autenticação: API Key. Exige permissão de consulta de vínculos.

Comportamento

1. Forma A: carrega o termo informado e valida existência, active e token (4050003–4050005).
2. Forma B: valida e cria o termo com status pending (Pendente). A autorização do termo na Dataprev é feita em segundo plano.
3. Grava a consulta com status pending, sem itens, e responde 201 com o registro, sem aguardar a Dataprev.
4. Em segundo plano, na Forma B, a consulta aguarda a autorização do termo. Se a Dataprev recusar a autorização, o termo passa a rejected (código 5), com o motivo em status.note, e a consulta termina com status = error.
5. Com o termo ativo, chama a Dataprev com o CPF do titular e o token do termo. Falhas temporárias do provedor (tempo esgotado, indisponibilidade) são repetidas automaticamente algumas vezes, com espera crescente; quando a cota da Dataprev é excedida, o processamento é adiado até o horário indicado pelo provedor. Erros de negócio encerram a consulta na hora.
6. Atualiza o mesmo registro para success (com os itens), empty ou error, e publica private_payroll_employment_relationship.completed ou .failed.

Payload de entrada

Campos enviados pela requisição Consultar vínculos com um termo já criado da collection. A API também aceita os dados do termo no lugar de authorizationTermId (Forma B, abaixo), criando o termo e consultando os vínculos numa única chamada.

Visualizar parâmetros

Campo	Tipo	Obrigatório	Descrição
authorizationTermId	string (uuid)	Sim (Forma A)	id de um termo active com token. Inexistente → 4050003; não ativo → 4050004; sem token → 4050005.

Outros campos aceitos (não usados na collection)

Campo	Tipo	Obrigatório	Descrição
subject, document, signatures[], startsAt, expiresAt, data, userId	—	Sim, na Forma B	Idênticos aos de POST /v5/loan-private-payrolls/terms. Validados com os códigos 4060xxx.

Forma B — criando o termo. Sem authorizationTermId, envie os mesmos campos de POST /v5/loan-private-payrolls/terms (subject, signatures, ...): a API cria o termo como Pendente e responde; em segundo plano, autoriza o termo na Dataprev e então consulta os vínculos.

Corpo vazio (nem authorizationTermId nem subject) → 4050002.

Qual forma escolher

Prefira a Forma A em fluxos com várias consultas para o mesmo trabalhador: o termo é reaproveitado. A Forma B é conveniente em jornadas curtas, como um simulador que só precisa saber se o trabalhador tem vínculo elegível.

Exemplo de Requisição e Resposta

Body

Visualizar Body

{
  "authorizationTermId": "{{termId}}"
}

cURL

curl --request POST \
  --url '{{baseUrl}}/v5/private-payroll-employment-relationships' \
  --header 'X-Api-Key: {{x_api_key}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "authorizationTermId": "{{termId}}"
  }'

201 - Created

Objeto com a consulta registrada, com status pending e ainda sem itens. As duas formas devolvem exatamente o mesmo formato. Os itens aparecem no GET /{id} (ou no payload do evento) quando o processamento termina.

Visualizar Response

{
  "id": "00000000-0000-7000-8000-000000000301",
  "code": 1,
  "documentNumber": "00000000000",
  "name": "Nome do Trabalhador",
  "authorizationTermId": "00000000-0000-7000-8000-000000000101",
  "provider": { "code": 100, "key": "dataprev", "name": "Dataprev" },
  "queriedAt": "2026-09-15T07:49Z",
  "items": [],
  "status": { "code": 4, "key": "pending", "name": "Consultando", "date": "2026-09-15T07:49Z", "color": "#FFEB3B", "note": null }
}

400 - Erro

Termo ausente (4050002), não encontrado (4050003), não ativo (4050004) ou sem token (4050005); validação do termo na Forma B (4060xxx); ou exceção não tratada (9999999). A falha na Dataprev não volta no POST: ela chega depois, com a consulta em status = error e o motivo em status.note.

Visualizar Response

{ "messages": [ { "code": "4050004", "text": "Termo de autorização não está ativo ou expirou" } ] }

401 - Não autorizado

API Key ausente, inválida ou expirada.

403 - Proibido

Usuário autenticado sem permissão de consulta de vínculos. Corpo vazio.

---

GET /v5/private-payroll-employment-relationships/{id}

Retorna uma consulta de vínculos, com todos os itens. É a forma de acompanhar uma consulta ainda pending até ela chegar a success, empty ou error. Não chama a Dataprev de novo: é uma leitura do histórico gravado. Útil para recuperar o items[].id escolhido em uma tela anterior ou auditar o que o provedor devolveu em determinada data.

Autenticação: API Key. Exige permissão de leitura de consultas de vínculos.

Parâmetros de rota

Visualizar parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
id	string (uuid)	Sim	id da consulta (não de um item) devolvido no POST.

Exemplo de Requisição e Resposta

cURL

curl --request GET \
  --url 'https://{base-url}/v5/private-payroll-employment-relationships/00000000-0000-7000-8000-000000000301' \
  --header 'X-Api-Key: {api_key}'

200 - Sucesso

Mesmo formato do 201 do POST, aqui com a consulta já processada.

Visualizar Response

{
  "id": "00000000-0000-7000-8000-000000000301",
  "code": 1,
  "documentNumber": "00000000000",
  "name": "Nome do Trabalhador",
  "authorizationTermId": "00000000-0000-7000-8000-000000000101",
  "provider": { "code": 100, "key": "dataprev", "name": "Dataprev" },
  "queriedAt": "2026-09-15T07:50Z",
  "items": [
    {
      "id": "00000000-0000-7000-8000-000000000311",
      "documentNumber": "00000000000",
      "registrationNumber": "000",
      "employerDocumentType": { "code": 1, "name": "CNPJ" },
      "employerDocumentNumber": "00000000000000",
      "isEligible": true,
      "isBlockedForLoan": false,
      "ineligibilityReason": null
    }
  ],
  "status": { "code": 1, "key": "success", "name": "Sucesso", "date": "2026-09-15T07:50Z", "color": "#4CAF50", "note": null }
}

Resposta resumida — os demais campos seguem o exemplo do POST.

400 - Erro

Consulta não encontrada ou fora do nível de acesso (4050001); ou exceção não tratada (9999999).

Visualizar Response

{ "messages": [ { "code": "4050001", "text": "Consulta de vínculos não encontrada" } ] }

401 - Não autorizado

API Key ausente, inválida ou expirada.

403 - Proibido

Usuário autenticado sem permissão de leitura. Corpo vazio.