Skip to main content

Manual – Consignado Privado: Vínculos Empregatícios

API em desenvolvimento

A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.

1. Objetivo do Documento​

Este manual descreve como funciona o monitoramento dos vínculos empregatícios de tomadores de crédito no Consignado Privado e como as atualizações são notificadas via webhooks.

2. Contexto e Motivação​

Os contratos de crédito consignado privado dependem de vínculos empregatícios ativos para manter as reservas válidas.
Por esse motivo, a Dataprev é consultada diariamente para identificar mudanças nesses vínculos (ex: encerramento de contrato de trabalho ou criação de um novo vínculo).

Quando há alterações, o sistema envia webhooks automáticos aos parceiros informando o novo status da reserva ou o novo vínculo detectado.

🔄 Fluxo Geral do Processo​

  1. O sistema consulta diariamente os vínculos empregatícios na Dataprev.
  2. Caso um vínculo ativo seja encerrado, o contrato é atualizado e o parceiro é notificado.
  3. Se o trabalhador criar um novo vínculo, o sistema identifica automaticamente e tenta revincular a reserva.
  4. Webhooks são enviados em cada etapa para que o parceiro mantenha seus sistemas atualizados.

3. Webhook – Encerramento de Vínculo Empregatício​

📅 Quando é enviado​

Quando um trabalhador perde o vínculo empregatício e o contrato consignado estava associado a esse vínculo.

🔍 O que acontece​

O status da reserva é atualizado para “terminated”, indicando que ela foi encerrada por término de vínculo.
O parceiro deve atualizar seu sistema de acordo com essa informação.

💡 Exemplo de Payload​

{
    "status": "terminated",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "terminated",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
    }
}

4. Webhook – Novos Vínculos Empregatícios​

📅 Quando é enviado​

Quando o sistema identifica que o trabalhador com contrato ativo passou a ter um novo vínculo empregatício, após o encerramento anterior.

🔍 O que acontece​

O sistema notifica o parceiro com os dados completos do novo vínculo.

💡 Exemplo de Payload​

{
    "status": "active",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.new_employment_relationship",
    "data": {
        "document_number": "71742311016",
        "registration_number": "123456789ABCDEFR",
        "employer_document_number": "02302554000179",
        "status": "active",
        "employment_relationship_data": {
            "name": "LETYCIA AGUILAR DA SILVA",
            "eligible": true,
            "loan_count": 0,
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "total_due_amount": 1642.16,
            "base_margin_amount": 911.67,
            "political_exposition": "not_exposed",
            "worker_category_code": 101,
            "employer_document_type": "CNPJ",
            "available_margin_amount": 319.08
        }
    }
}

5. Webhook – Reserva Revinculada a Novo Vínculo​

📅 Quando é enviado​

Após o sistema detectar um novo vínculo e revincular automaticamente uma reserva que estava terminada.

🔍 O que acontece​

O revínculo ocorre apenas se a nova margem for suficiente.

Não há recálculo de parcelas nem reperfilamento da dívida.

Uma nova chave de reserva (reservation_key) é gerada, mantendo a mesma chave credit_operation_key ou external_key.

O parceiro recebe dois webhooks, um informando a nova reserva com status "reserved" e outro informando a mudança de status da antiga reserva para o status "transferred". Assim é possível rastreiar os contratos revínculados, terminados e transferidos.

💡 Exemplo de Payload - Contrato revínculado​

{
    "status": "reserved",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.renewed_reservation",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "reserved",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "transferred",
    }
}

💡 Exemplo de Payload - Contrato transferido​

{
    "status": "transferred",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
            "reservation_status": "transferred",
    }
}

Observação:​

A external_key ou credit_operation_key como as maiorias dos dados se mantém a mesma.

6. Boas Práticas​

Monitore seus webhooks diariamente para garantir sincronização com o sistema LaaS.

Trate as atualizações de status de forma idempotente (ou seja, evite processar o mesmo evento duas vezes).

Guarde logs de recebimento de webhooks para fins de auditoria.