Webhook de autorização de portabilidade

A QI Tech envia o webhook credit_transfer.portability_authorization a cada mudança de status da autorização de portabilidade, o pedido de anuência que ela registra na Dataprev para o beneficiário confirmar no Meu INSS. Há uma autorização por proposta INSS, criada quando a CTC devolve o NU. O fluxo e os prazos estão em Anuência do beneficiário na portabilidade.

WEBHOOK_TYPE

credit_transfer.portability_authorization

info

Os webhooks da QI Tech podem ganhar campos novos sem aviso. Não rejeite um payload por ter campos que você não mapeou. Para consultar e reenviar webhooks, veja Reenvio de webhooks.

Corpo do webhook

webhook_typestringSempre credit_transfer.portability_authorization.portability_authorization_keystring (UUID)Chave da autorização. Uma por proposta.proposal_keystring (UUID)Proposta de portabilidade a que a autorização pertence.portability_authorization_statusstringStatus da autorização. Veja Status.event_datetimestringData e hora do evento, no formato AAAA-MM-DDTHH:MM:SS.dataobjectDetalhes da autorização.

portability_numberstringNúmero da portabilidade (NU) gerado pela CTC.requested_atstringData e hora em que a QI pediu o registro da autorização na Dataprev.expiration_datestring ou nullÚltimo dia para o beneficiário confirmar: registro mais 5 dias corridos. Preenchido a partir de awaiting_confirmation.confirmation_datestring ou nullDia em que o beneficiário confirmou no Meu INSS.deadline_datestring ou nullÚltimo dia para a exclusão pelo banco de origem e a averbação: confirmação mais 20 dias corridos.authorized_valuesobjectO que o beneficiário autoriza. Valores em reais; taxas como fração (0.0179 = 1,79%).

installmentsintegerNúmero de parcelas.installment_face_valuenumberValor da parcela, em reais.loan_amountnumberValor do empréstimo, em reais. É a estimativa de saldo da digitação.monthly_interest_ratenumberTaxa de juros mensal.annual_interest_ratenumberTaxa de juros anual.monthly_cetnumberCET mensal.annual_cetnumberCET anual.

errorobject ou nullPreenchido em failed: code e description devolvidos pela Dataprev.

{
  "webhook_type": "credit_transfer.portability_authorization",
  "portability_authorization_key": "c1a9d3f0-8e4b-4f2a-b6d7-0e5a9c2b7d13",
  "proposal_key": "7f2c0e2a-5d1b-4c7a-9d3e-2b1f0a8c6e41",
  "portability_authorization_status": "confirmed",
  "event_datetime": "2026-11-20T14:03:11",
  "data": {
    "portability_number": "202611180000246536429",
    "requested_at": "2026-11-18T09:12:38",
    "expiration_date": "2026-11-23",
    "confirmation_date": "2026-11-20",
    "deadline_date": "2026-12-10",
    "authorized_values": {
      "installments": 84,
      "installment_face_value": 312.4,
      "loan_amount": 14250.0,
      "monthly_interest_rate": 0.0179,
      "annual_interest_rate": 0.2374,
      "monthly_cet": 0.0191,
      "annual_cet": 0.2549
    },
    "error": null
  }
}

Status

Status da autorização de portabilidade

Em azul, os status intermediários; em verde, a confirmação; em vermelho, os status finais em que a portabilidade não segue.

Status	Significado	Efeito na proposta
`pending_inclusion`	A QI está registrando a autorização na Dataprev. Fora da janela das 6h às 22h, espera a janela abrir	Nenhum
`awaiting_confirmation`	Registrada. O beneficiário tem até `expiration_date` para confirmar no Meu INSS	Nenhum. A proposta segue em `pending_acceptance`
`confirmed`	O beneficiário confirmou. Abre o prazo de 20 dias corridos até `deadline_date`	Libera o aceite e o pagamento
`expired`	5 dias corridos sem resposta do beneficiário	`canceled`, com `portability_authorization_expired`. A QI envia a desistência à CTC
`refused`	O beneficiário recusou no Meu INSS	`canceled`, com `portability_authorization_refused`. A QI envia a desistência à CTC
`failed`	A Dataprev recusou o registro: benefício bloqueado, NU já autorizado, contrato não encontrado. O motivo vem em `error`	`canceled`, com `portability_authorization_failed`
`canceled`	A proposta foi cancelada ou retida antes da averbação, ou a Dataprev cancelou a autorização porque o contrato de origem foi refinanciado ou trocou de titular	Segue o cancelamento ou a retenção da proposta

Nos desfechos expired, refused e failed chegam dois webhooks, nesta ordem: o da autorização, com o status final, e o da proposta, com canceled. Você não precisa cancelar nada.

Exemplos

awaiting_confirmation

{
  "webhook_type": "credit_transfer.portability_authorization",
  "portability_authorization_key": "c1a9d3f0-8e4b-4f2a-b6d7-0e5a9c2b7d13",
  "proposal_key": "7f2c0e2a-5d1b-4c7a-9d3e-2b1f0a8c6e41",
  "portability_authorization_status": "awaiting_confirmation",
  "event_datetime": "2026-11-18T09:12:52",
  "data": {
    "portability_number": "202611180000246536429",
    "requested_at": "2026-11-18T09:12:38",
    "expiration_date": "2026-11-23",
    "confirmation_date": null,
    "deadline_date": null,
    "authorized_values": {
      "installments": 84,
      "installment_face_value": 312.4,
      "loan_amount": 14250.0,
      "monthly_interest_rate": 0.0179,
      "annual_interest_rate": 0.2374,
      "monthly_cet": 0.0191,
      "annual_cet": 0.2549
    },
    "error": null
  }
}

failed

{
  "webhook_type": "credit_transfer.portability_authorization",
  "portability_authorization_key": "c1a9d3f0-8e4b-4f2a-b6d7-0e5a9c2b7d13",
  "proposal_key": "7f2c0e2a-5d1b-4c7a-9d3e-2b1f0a8c6e41",
  "portability_authorization_status": "failed",
  "event_datetime": "2026-11-18T09:12:52",
  "data": {
    "portability_number": "202611180000246536429",
    "requested_at": "2026-11-18T09:12:38",
    "expiration_date": null,
    "confirmation_date": null,
    "deadline_date": null,
    "authorized_values": {
      "installments": 84,
      "installment_face_value": 312.4,
      "loan_amount": 14250.0,
      "monthly_interest_rate": 0.0179,
      "annual_interest_rate": 0.2374,
      "monthly_cet": 0.0191,
      "annual_cet": 0.2549
    },
    "error": {
      "code": "IE",
      "description": "Benefício bloqueado para empréstimo pelo beneficiário"
    }
  }
}

Proposta cancelada por autorização expirada

{
  "webhook_type": "credit_transfer.proposal",
  "proposal_key": "7f2c0e2a-5d1b-4c7a-9d3e-2b1f0a8c6e41",
  "proposal_status": "canceled",
  "event_datetime": "2026-11-23T22:05:02",
  "cancel_reason": "portability_authorization_expired",
  "cancel_reason_description": "Autorização de portabilidade expirada sem resposta do beneficiário"
}

Motivos de cancelamento da proposta

Chegam em cancel_reason e cancel_reason_description do webhook credit_transfer.proposal com proposal_status igual a canceled.

`cancel_reason`	Significado
`portability_authorization_expired`	5 dias corridos sem resposta do beneficiário
`portability_authorization_refused`	O beneficiário recusou no Meu INSS
`portability_authorization_failed`	A Dataprev recusou o registro. O motivo está em `data.error` do webhook da autorização

Erros

A partir de 18/11/2026, o aceite da proposta (PATCH /v2/credit_transfer/proposal/{proposal_key} com accepted_by_requester) é recusado nestes casos:

Situação	O que fazer
Autorização ainda não confirmada	Aguarde o `confirmed`. Até 30/11/2026, o saldo pode chegar antes da confirmação; veja Entre 18/11 e 30/11/2026
Parcela ou taxa acima de `authorized_values`	Aceite com parcela e taxa iguais ou menores que as autorizadas
Autorização `expired`, `refused`, `failed` ou `canceled`	A proposta já foi ou será cancelada. Digite uma proposta nova
Sem prazo para a averbação até `deadline_date`	A portabilidade não pode mais ser concluída por esse NU. Digite uma proposta nova

Corpo do webhook​

Status​

Exemplos​

Motivos de cancelamento da proposta​

Erros​

Corpo do webhook

Status

Exemplos

Motivos de cancelamento da proposta

Erros