Manual Consignado Privado - Movimentação de Vínculos: Averbação por Revínculo
Esta página cobre os endpoints e webhooks da reaverbação por revínculo. Para entender por que a autorização é obrigatória em determinados casos, e o que diferencia uma falha retentável de uma falha terminal, veja Regras de Negócio — Reaverbação automática vs. autorização obrigatória.
1. Autorização
Semelhante ao fluxo de contratação de um novo empréstimo, é possível que a integração seja configurada para que todos os revínculos sejam criados pendente de autorização. Caso seja configurada para revincular automaticamente, ainda assim nos casos onde o novo vínculo é informado pela DATAPREV com margem parcial, as novas averbações serão criadas no status pendente de autorização.
Dependendo do status em que o revínculo foi criado, será enviado um webhook informando a criação da nova averbação e seu status (pending_requester_authorization ou pending_reservation):
Webhook Body
- Revínculo criado aguardando autorização
- Revínculo criado na fila para averbação
{
"status": "pending_requester_authorization",
"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": "pending_requester_authorization",
"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",
}
}
{
"status": "pending_reservation",
"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": "pending_reservation",
"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",
}
}
2. Autorização e atualização da margem
Para os casos onde o novo vínculo não tem margem consignável suficiente para averbar a parcela cheia do contrato, é obrigatório que seja realizada a autorização da averbação. Diferente da averbação de um contrato novo — identificada pela external_key da operação de crédito, documentada em Averbação de Novos Empréstimos — Autorização e Averbação — a autorização do revínculo é feita pela reservation_key: o identificador da própria reserva criada para o revínculo, recebido no webhook laas.private_payroll.renewed_reservation acima.
Request
Response sucesso
Response Body
{
"reservation_key": "<Reservation Key>",
"document_number": "12345678901",
"registration_number": "99999999999-A",
"employer_document_number": "12345678901234",
"external_key": "abc123def456",
"contract_number": "2024001234",
"inclusion_date": "2024-03-18",
"disbursement_date": "2024-03-20",
"contract_data": {
"amount": 5000.00,
"installments": 12,
"interest_rate": 0.018
},
"reservation_data": {
"installment_value": 500.00,
"margin_value": 450.00
},
"reservation_status": "authorized"
}
Response falha
Uma reservation_key inexistente e uma reservation_key que exista mas pertença a outro solicitante retornam o mesmo erro (PRP000111) — não há uma variante dedicada de "não encontrado".
Response Body
- Reserva não encontrada ou não pertence ao solicitante
- Averbação já está autorizada
{
"title" : "Reservation is not ready for authorization",
"code" : "PRP000111",
"description" : "The reservation is not ready for authorization",
"translation" : "A reserva não está pronta para autorização"
}
{
"title" : "Reservation is not pending requester authorization",
"code" : "PRP000057",
"description" : "The reservation is not pending requester authorization",
"translation" : "A reserva não está pendente de autorização do requerente",
}
Uma vez autorizado o revínculo com margem parcial, não é possível alterar o valor da averbação posteriormente. Os valores que não forem averbados deverão ser cobrados diretamente do tomador.
É possível atualizar o valor da nova averbação através de uma consulta de dados no novo vínculo antes de decidir a autorização; este mecanismo é importante pois é possível que a primeira margem do novo vínculo informada pela DATAPREV seja parcial dependendo do período de contribuição da primeira competência.
3. Revínculo
Sucesso
Quando a nova reserva é averbada com sucesso, são enviados dois webhooks informando a alteração de status da averbação original para transferred e a alteração de status da nova reserva para reserved.
Webhook Body
{
"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",
"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",
"termination_date":null,
"periods": [],
"reason":null
}
}
Webhook Body
{
"status": "reserved",
"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": "reserved",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"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",
"termination_date":null,
"periods": [
{
"amount": 339.06,
"due_date": "2026-08-28",
"installment_key": "<Installment Key>",
"installment_number": 1
},
{
"amount": 339.06,
"due_date": "2026-09-28",
"installment_key": "<Installment Key>",
"installment_number": 2
},
{
"amount": 339.06,
"due_date": "2026-10-28",
"installment_key": "<Installment Key>",
"installment_number": 3
}
],
"reason": null,
}
}
Falha
Diferente da averbação de crédito novo, caso haja uma falha no revínculo por margem excedida, a averbação irá retornar ao status de pendente de autorização. Nestes casos é possível que a margem consignável disponível para o revínculo tenha flutuado, sendo necessária uma nova consulta de dados para reavaliar a reaverbação.
Webhook Body
{
"status": "pending_requester_authorization",
"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": "pending_requester_authorization",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"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",
"termination_date":null,
"periods": [],
"reason": {
"enumerator": "margin_exceeded",
"description": "Consignable margin exceeded",
"translation": "Margem consignável excedida"
}
}
}
Caso haja uma falha na averbação porque o vínculo empregatício não está mais disponível para reaverbação, a nova averbação será cancelada e não haverá mais tentativas.
Webhook Body
{
"status": "pending_requester_authorization",
"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": "canceled",
"requester_key": "123e4567-e89b-12d3-a456-426614174000",
"registration_number": "99999999999-A",
"employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
"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",
"termination_date":null,
"periods": [],
"reason": {
"enumerator": "employment_relationship_not_ineligible_due_to_previous_termination",
"description": "Employment relationship is not ineligible due to loan closed by previous relationship termination",
"translation": "Vínculo não está inelegível por empréstimo encerrado por término de vínculo anterior"
},
}
}
Assim como na averbação de um contrato novo, essas falhas de reaverbação também disparam o webhook dedicado laas.private_payroll.reservation_failure — ver detalhamento em Erros de Averbação. Para o revínculo, data.reservation_type vem como "transferred".