Skip to main content

Manual Previdência Privada - Averbação e Desembolso

API em desenvolvimento

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

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma estrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

1 - Averbação​

Webhooks​

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK TYPE
credit_operation.collateral
STATUS
Opened
Webhook Body
{
  "webhook": {
    "key": "<UUID>",
    "data": {
      "collateral_data": {},
      "collateral_type": "private_pension",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}

Falha na averbação​

Se uma reserva falhar, será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK TYPE
private_pension_failed_reservation
STATUS
Pending requester action
Webhook Body
Webhook Body
{
    "key": "<Debt Key>",
    "status": "failed",
    "webhook_type": "private_pension_failed_reservation",
    "event_datetime": "2025-10-26 16:41:28",
    "data": {
        "enumerator": "Fail enumerator.",
        "description": "Descrição da falha.",
    }
}

2 - Desaverbação​

A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.

Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:

POST
/debt/DEBT-KEY/cancel_permanently

Webhooks​

WEBHOOK TYPE
debt
STATUS
canceled_permanently
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {}
}

3 - Falha no desembolso​

TED​

Em caso de falha no desembolso via TED

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
 {
     "key": "<Debt Key>",
     "status": "canceled",
     "webhook_type": "debt",
     "event_datetime": "2025-03-18 16:41:28",
     "data": {
         "ted_refusal": {
             "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
             "description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
             "origin": {
                 "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
                 "account_number": "00086",
                 "bank_code": "329",
                 "name": "ACCOUNT TRANSITORY",
                 "type": "payment_account",
                 "document": "32402502000135",
                 "branch_digit": null,
                 "account_digit": "8",
                 "branch": "0001"
             },
             "fee": 0,
             "reason_enumerator": "agencia_conta_invalida",
             "timestamp": "2022-11-07T14:36:05",
             "amount": 483.6,
             "reason": "Agência ou Conta Destinatária do Crédito Inválida",
             "destination": {
                 "branch": "0000",
                 "account_number": "000000",
                 "name": "NOME DO EMPREGADO",
                 "purpose": "Crédito em Conta",
                 "type": "checking_account",
                 "branch_digit": null,
                 "document": "12345678900",
                 "bank_code": "341",
                 "account_digit": "7"
             }
         },
         "cancel_reason": "ted_refusal"
     }
 }

PIX​

Em caso de falha no desembolso via PIX

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {
        "cancel_reason": "pix_refusal",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        }
    }
}

4 - Reapresentação de Pagamento​

Altera a data de desembolso sem afetar os valores financeiros da operação.

POST
/debt/DEBT-KEY/change_disbursement_date

Request​

Request Body
{
    "disbursement_date": "2025-03-19",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "<CPF DO TRABALHADOR>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "<NOME DO TRABALHADOR>",
            "percentage_receivable": 100
        }
    ]
}

Response​

STATUS
200 OK
Response Body
{
    "disbursement_date": "2025-03-19",
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ]
}