跳到主要内容

保险

本手册介绍与保险合同挂钩的薪资抵押信贷发行流程的各个步骤。这些操作的放款将存入发行流程中为借款人开立的内部账户。从该账户中，将对信贷放款进行拆分，将部分放款金额转入借款人在 QI 以外的外部账户，其余部分用于支付保险费。

1. BC PROTEGE+ 查询​

与信贷操作挂钩的保险发行流程将涉及在 QI 为借款人开立内部账户。要开立账户，借款人不得在 BC PROTEGE+ 名单中。 可通过以下端点使用 API 进行查询。若借款人在该名单中，保险将在正式化后被取消。

GET
/bacen_protect/validate/[document_number]
Response Body
{
    "permission_result": "approved"
}
沙盒测试

以 9 开头的 CPF 将返回权限被拒绝。

2. 债务模拟与发行​

要模拟和发行与保险发行挂钩的债务，须在 financial 对象的折扣列表中添加一个对象。

Objeto Rebate
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_description"
    }
  ]
}

模拟 payload 示例​

POST
/debt
request_body
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "rebates": [
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    }
}

发行 payload 示例​

POST
/debt_simulation
request_body
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
产品选择

description 枚举器用于定义将发行的保险产品类型，这直接影响保险费金额和保障范围。请咨询运营团队了解您的集成应使用哪些枚举器。

3. 正式化​

在 QI Sign 的债务正式化流程中，将显示若干屏幕以确保借款人了解并同意购买保险。

OPT-OUT

借款人可能决定放弃购买保险，仅签署信贷合同。在这种情况下，原本用于保险费的金额也将存入借款人账户。

在信贷正式化 webhook 的同时，将发送一个事件，告知保险在正式化流程中是否被接受或拒绝。

WEBHOOK_TYPE
insurance_premium.status_change
Webhook Body
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "payment_account": {
      "account_number": "1234567",
      "account_digit": "8",
      "account_branch": "0001",
      "owner_document_number": "98765432100",
      "ispb": "32402502"
    }
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "accepted",
  "webhook_type": "insurance_premium.status_change"
}
拒绝原因

拒绝原因的可能枚举值可在拒绝原因表中查询。

账户开立

债务与保险正式化完成后，将开立内部账户，信贷操作的全额放款将存入该账户，并从中进行拆分——部分金额转给借款人，其余部分用于支付保险费。账户的银行信息在 payment_account 对象中提供。

4. 内部放款​

完成薪资抵押步骤后，操作将放款至正式化后开立的内部账户，并发送以下放款 webhook。

WEBHOOK_TYPE
debt
STATUS
disbursed
payload
{
    "key": "53f23b3be-2bc8-46fb-943f-5d4532eecf5e",
    "data": {
      "installments": [
        {
          "due_date": "2026-01-24",
          "total_amount": 4645.64,
          "installment_key": "80f8f098-0232-4543-1e6b-50f970bac6e2",
          "pre_fixed_amount": 74.31,
          "installment_number": 1,
          "principal_amortization_amount": 4571.33
        }
      ],
      "ted_receipt_list": [],
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-12-26 18:56:45"
  }
}

5. 放款后操作​

要跟踪向借款人外部账户转账的成功或失败，须监控以下 webhook。

WEBHOOK_TYPE
after_disbursement_action_update
Webhook Body
{
  "data": [
    {
      "action_error": {
        "description": "An error occurred while sending pix_transfer bfea6188-879c-46e5-b842-d1e934d44775 to SPI",
        "error_code": "disbursing_error"
      },
      "status": "error",
      "action_data": {
        "pix_transfer_type": "manual",
        "target_account": {
          "document_number": "98765432100",
          "financial_institution_code": 1,
          "ispb": 0,
          "name": "Nome Tomador",
          "financial_institution_code_number": "341",
          "account_branch": "9123",
          "account_digit": "0",
          "account_number": "9999"
        },
        "transaction_amount": 100
      },
      "action_key": "fcec7529-3598-4ce2-9448-4c24d1cb9df0",
      "execution_data": null,
      "action_type": "pix"
    }
  ],
  "event_datetime": "2025-12-30 13:25:08",
  "key": "e7a73248-d737-4cb4-ad07-6d303fc4b96c",
  "webhook_type": "debt_actions"
}

放款后操作重新呈报​

如发生失败，须使用以下端点重新呈报放款后操作。

ENDPOINT
/baas/action/ACTION-KEY
MÉTODO
PATCH
payload
{
  "pix_transfer_type": "manual",
  "target_account": {
      "name": "Nome Tomador",
      "account_digit": "0",
      "account_branch": "9123",
      "account_number": "9999",
      "document_number": "98765432100",
      "financial_institution_code_number": "341"
  }
}
沙盒测试

要模拟放款后操作失败，可使用账户号 11581339 进行手动 pix，或使用密钥 b9380607-dac6-4e17-8ca7-eb761e3aa1dc 进行 pix 密钥。

payload
	"disbursement_bank_accounts": [{
			"document_number": "77564023082",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_transfer_type": "manual",
			"bank_code": "001",
			"branch_number": "0001",
			"account_number": "11581339",
			"account_digit": "0",
			"percentage_receivable": 100
		}]

要模拟 TED 转账拒绝，须使用以下端点：

ENDPOINT
/mock/ted/ted_refusal
MÉTODO
POST
Request Body
{
  "transaction_key": "\<Chave unitária da transação\>"
}

6. 放款后操作失败时的取消​

如果内部放款已完成，放款后操作失败且未重新呈报，须使用以下端点进行取消。

ENDPOINT
/debt/DEBT-KEY/reversal
MÉTODO
PUT
payload
{}

7. 保险发行​

放款后操作成功后，将进行保险费转账和保险发行。要跟踪保险状态，须监控以下 webhook。

WEBHOOK_TYPE
insurance_premium.status_change
Webhook Body
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
    "insurance_date": "2024-09-11",
    "term_start_date": "2024-09-11",
    "term_end_date": "2025-09-11",
    "insurance_amount": 1600,
    "operation_amount": 6400,
    "covers": [
      {
        "cover_amount": 200,
        "cover_type": "permanent_disability",
        "cover_prize_amount": 572.82
      },
      {
        "cover_amount": 100,
        "cover_type": "accidental_death",
        "cover_prize_amount": 572.82
      },
      {
        "capitalcover_amount_segurado": 300,
        "cover_type": "unemployment",
        "cover_prize_amount": 572.82
      }
    ],
    "policy_number": "1098200000008",
    "prize_number": "3907",
    "insurance_premium_net_amount": 1145.63,
    "iof_amount": 4.37
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "active",
  "webhook_type": "insurance_premium.status_change"
}
保险取消

要查看保险取消的可能原因，请参阅取消原因表。

必须向借款人发送保单凭据

保险发行后，必须将保单 PDF 发送给借款人。可通过**文件查询**使用保险发行 webhook 中提供的 insurance_policy_document_key 查询该文件。

沙盒测试

要测试保险取消，可使用以下端点：

POST
/mock/insurance_premium/[INSURANCE-PREMIUM-KEY]/cancel

保险查询​

要主动查询保险信息，可使用以下端点。

GET
/debt/[DEBT-KEY]/insurance_premium/[INSURANCE-PREMIUM-KEY]
STATUS
200
Response Body
{
  "insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
  "status": "active",
  "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
  "disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
  "contract_number": "4069550961/QIT",
  "requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_date": "2024-09-11",
  "term_start_date": "2024-09-11",
  "term_end_date": "2025-09-11",
  "insurance_amount": 1600,
  "operation_amount": 6400,
  "customer": {
    "customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
    "document_number": "08556878350",
    "name": "Wilker Oliveiraço",
    "birth_date": "1998-03-21",
    "gender": "male",
    "email": "urich.oliveira@yopmail.com",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "966931427"
    },
    "address": {
      "postal_code": "56821686",
      "state": "CE",
      "city": "Ceará",
      "neighborhood": "Marmiteiros",
      "street": "Conjunto João Gabriel da Mata",
      "number": "95",
      "complement": ""
    }
  },
  "covers": [
    {
      "cover_amount": 300,
      "cover_type": "permanent_disability",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "accidental_death",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "unemployment",
      "cover_prize_amount": 572.82
    }
  ],
  "policy_number": "1098200000008",
  "prize_number": "3907",
  "insurance_premium_net_amount": 1145.63,
  "iof_amount": 4.37
}

流程图​

附录​

拒绝原因​

枚举器描述
insurance_rejected保险被拒绝
bacen_protectbc protege+

取消原因​

枚举器描述
reversed_operation操作已撤销，保险已取消
cover_limit_amount_exceeded仅保险被取消。某项保障限额被超出，无法发行保险
insurance_premium_cancel仅保险被取消。借款人直接向保险公司申请了取消