Skip to main content

Seguro

Este manual passa pelas etapas do fluxo de emissão de crédito consignado atrelado à contratação de seguro, o desembolso destas operações será realizado em uma conta interna de titularidade do tomador aberta durante o fluxo de emissão. Desta conta ocorrerá um split no desembolso do crédito transferindo parte do valor desembolsado para uma conta externa à QI de titularidade do tomador e o restante para o pagamento do prêmio do seguro.

1. Consulta BC PROTEGE+​

O fluxo de emissão do seguro junto a uma operação de crédito envolverá a abertura de uma conta interna na QI de titularidade do tomador. Para abrir a conta, é necessário que o tomador não esteja na lista do BC PROTEGE+. É possível realizar a consulta via api utilizando o endpoint a seguir, caso o tomador esteja na lista o seguro será cancelado após a formalização.

GET
/bacen_protect/validate/[document_number]
Response Body
{
    "permission_result": "approved"
}
Testes em Sandbox

Os CPFs iniciados em 9 retornarão permissão rejeitada.

2. Simulação e emissão da dívida​

Para simular e emitir uma dívida atrelada à emissão de um seguro, deve-se adicionar um objeto à lista de rebates dentro do objeto finantial.

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

Exemplo de payload de simulação​

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"
          }
        ]
    }
}

Exemplo payload de emissão​

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
        }
    ]
}
Seleção do Produto

O enumerador description é utilizado para definir o tipo de produto de seguro que será emitido, isto interfere diretamente no valor do prêmio e nas coberturas. Consulte a equipe de operações para saber quais enumeradores devem ser utilizados na sua integração.

3. Formalização​

Durante o fluxo de formalização da dívida no QI Sign, serão apresentadas algumas telas para garantir a ciência e o consentimento do tomador em relação à contratação do seguro.

OPT-OUT

É possível que o tomador decida abandonar a contratação do seguro e seguir somente com a contratação do crédito, neste caso o valor que seria destinado ao prêmio do seguro também será desembolsado na conta do tomador.

Junto ao webhook de formalização do crédito, será enviado um evento informando se o seguro foi aceito ou rejeitado no fluxo de formalização.

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"
}
Motivo de Rejeição

Os possíveis enumeradores do motivo de rejeição podem ser consultados na tabela Motivos de rejeição.

Abertura de conta

Após a formalização da dívida junto ao seguro, é realizada a abertura da conta interna onde será depositado o valor integral de desembolso da operação de crédito e de onde será realizado o slpit entre o valor desembolsado ao tomador e o valor do prêmio do seguro. Os dados bancários da conta são informados no objeto payment_account.

4. Desembolso interno​

Após a etapa de averbação, a operação será desembolsada na conta interna aberta após a formalização e será enviado o seguinte webhook de desembolso.

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. Ações pós desembolso​

Para acompanhar o sucesso ou a falha nas tentativas de transferência para a conta externa de titularidade do tomador, deve-se monitorar o seguinte 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"
}

Reapresentação de ação pós desembolso​

Em caso de falha, deve ser utilizado o seguinte endpoint para reapresentação da ação pós desembolso

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"
  }
}
Testes em Sandbox

Para homologar uma falha na ação pós desembolso, pode-se utilizar a número de conta 11581339 para pix manual ou a chave b9380607-dac6-4e17-8ca7-eb761e3aa1dc para chave 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
		}]

Para homologar recusa de uma transferência TED, deve-se utilizar o endpoint:

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

6. Cancelamento em caso de falha da ação pós desembolso​

Em caso de falha de desembolso interno já foi feito, ação pós desembolso com falha e não havendo reapresentação da ação, deve-se utilizar o seguinte endpoint para cancelamento.

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

7. Emissão do seguro​

Após o sucesso na ação pós desembolso, será realizada a transferência do valor do prêmio e a emissão do seguro, para acompanhamento do status do seguro deve-se monitorar o seguinte 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"
}
Cancelamento do seguro

Para verificar os possíveis motivos de cancelamento do seguro, consulte a tabela Motivo de cancelamento.

Envio obrigatório do bilhete ao tomador

É obrigatório que o pdf do bilhete seja enviado ao tomador após a emissão do seguro, o documento pode ser consultado através da consulta de documentos utilizando a insurance_policy_document_key informada no webhook de emissão do seguro.

Testes em Sandbox

Para testar o cancelamento do seguro pode-se utilizar o seguinte endpoint:

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

Consulta de seguro​

Para ativamente consultar as informações de um seguro pode-se utilizar o seguinte endpoint.

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
}

Fluxograma​

Anexos​

Motivo de rejeição​

EnumeradorDescrição
insurance_rejectedseguro rejeitado
bacen_protectbc protege+

Motivo de cancelamento​

EnumeradorDescrição
reversed_operationOperação revertida e seguro cancelados
cover_limit_amount_exceededSomente o seguro foi cancelado. Algum limite de cobertura foi ultrapassado e não foi possível a emissão do seguro
insurance_premium_cancelSomente o seguro foi cancelado. Cancelamento do tomador direto com a seguradora