我的 INSS 提案拍卖手册

注意！

QI Tech 的 webhooks 不应被严格映射。返回的 webhooks payload 中可能会新增额外字段。

简介

欢迎使用我的 INSS 提案拍卖 API。

我的 INSS 提案拍卖是一项服务，允许查询由受益人创建的提案申请，并由受托方提交提案，从而为退休人员/养老金领取者提供信贷机会。

该 API 允许在拍卖中创建、更新、查询和取消提案。愿最佳提案胜出！！！

遇到问题？

如有任何问题，请联系我们的支持团队（suporte@qitech.com.br），我们将尽快回复。

环境

我们为客户提供两个环境。API 的基础 URL 为：

生产环境 - https://api-auth.qitech.app/
沙盒环境 - https://api-auth.sandbox.qitech.app/

仅限 HTTPS

出于安全考虑，与 QI Tech API 的所有通信必须使用 HTTPS。为避免因疏忽或其他原因发起 HTTP 调用，本服务器仅开放端口 443 并使用 TLS 1.2 通信。使用其他协议的调用将被自动拒绝。

ProposalRequest：信贷提案申请

ProposalRequest 是代表受益人发起的信贷提案申请的对象。养老金领取者或退休人员若要发起申请，需要有可用余额、具备资格，且其福利处于激活且未被锁定的状态。

当 QI Tech 收到新的信贷提案申请时，将向已配置的端点发送 Webhook。

以下是发送的 payload 示例：

{
    "expiration_datetime": "2024-09-22T10:22:10Z",
    "status": "ongoing",
    "inclusion_limit_datetime": "2024-09-02T14:22:15Z",
    "proposal_request_key": "24e9625a-e264-4d33-8b59-a5238001b12f",
    "proposal_request_data": {
        "consigned_credit": {
            "balance": 432
        }
    }
}

注意

以上是提案申请的初始数据。要查看受益人的所有信息，需要创建一个提案以接受相应的 ProposalRequest。其余数据包括 CPF、姓名、出生日期、福利号码、福利类型等...

ProposalRequest 对象定义

ProposalRequest 的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，部分信息可能会被省略。

名称	类型	描述
proposal_request_key	string	提案申请的唯一标识符
proposal_request_data	object	描述提案申请数据的对象
status	string	提案申请状态（`ongoing`、`finished`、`expired`）
expiration_datetime	string	提案申请的过期日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`
inclusion_limit_datetime	string	在拍卖中提交提案的截止日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`

ProposalRequestData 对象定义

名称	类型	描述
name	string	受益人全名
state	string	受益人所在州
document_number	string	受益人 CPF
birth_date	string	受益人出生日期，格式为 `DDMMYYYY`
benefit_number	integer	退休人员/养老金领取者的福利号码
benefit_status	string	描述福利状况的枚举值
assistance_type	string	福利类型的枚举值
benefit_situation	string	描述福利状况的枚举值
max_total_balance	float	该福利种类可承诺的最大金额
used_total_balance	float	已批注贷款、为可携性预留、再融资、变更、RMC 和 RCC 的已承诺总额
requested_disbursed_amount	float	受益人申请的放款金额
number_of_installments	integer	受益人申请的分期数
has_legal_representative	boolean	是否有法定代表人
has_power_of_attorney	boolean	是否有委托代理人
has_entity_representation	boolean	是否有代表实体
consigned_credit.balance	float	受益人可用余额

提案申请状态详细说明

提案申请的状态可以是：

状态	描述
ongoing	提案申请进行中，拍卖仍然有效。
finished	提案申请已结束，拍卖已关闭，所提交的某个提案已被接受并纳入。
expired	提案申请已过期，拍卖已在未纳入任何提案的情况下关闭。

发送 Webhook 后查询提案申请

如有需要，仍可重新查询受益人发起的提案申请（即使在发送自动 Webhook 之后）。使用提案申请的 ID（通过自动 Webhook 发送）通过 API 进行调用。

注意

只有在合作伙伴接受提案申请并创建提案后，才允许完整查询受益人数据。

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}

MÉTODO

- GET

Path Params

字段	类型	描述	字符数	必填
`proposal_request_key`	uuidv4	ProposalRequest 的唯一标识密钥，使用 uuid v4 格式。	36	是

Response - 部分查询

STATUS

- 200

Response Body：ProposalRequest 部分查询

{
    "proposal_request_data": {
        "consigned_credit": {
            "balance": 750.00
        }
    },
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "ongoing",
    "inclusion_limit_datetime": "YYYY-MM-DDTHH:MM:SSZ",
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}

Response Body：ProposalRequest 完整查询

{
    "proposal_request_data": {
        "name": "João Silva",
        "state": "SP",
        "birth_date": "14031992",
        "benefit_number": 8784006178,
        "benefit_status": "elegible",
        "assistance_type": "retirement_by_age",
        "document_number": 71881324451,
        "consigned_credit": {
            "balance": 750.00
        },
        "benefit_situation": "active",
        "max_total_balance": 1800.00,
        "used_total_balance": 1400.00,
        "has_power_of_attorney": false,
        "number_of_installments": 48,
        "has_legal_representative": false,
        "has_entity_representation": false,
        "requested_disbursed_amount": 15000.00,
        "social_benefit_max_balance": 1800.00,
        "social_benefit_used_balance": 1400.00,
        "dataprev_proposal_request_id": 41
    },
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "ongoing",
    "inclusion_limit_datetime": "YYYY-MM-DDTHH:MM:SSZ",
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}

注：Response Body 字段的详细说明在上方 ProposalRequest 对象定义中描述。

Proposal：向受益人提交的信贷提案

Proposal 是代表受托方向受益人提交的信贷提案的对象。为使 QI Tech 针对特定提案申请向退休人员/养老金领取者提交新的提案，将进行拍卖，最佳信贷报价将被选中推进。

注意

每个提案申请只接受一个提案——仅允许根据合作伙伴的意愿进行修改。

Proposal 对象定义

Proposal 的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，部分信息可能会被省略。

名称	类型	描述
proposal_request_key	string	提案申请的唯一标识符。
request_control_key	string	提交的提案的唯一标识密钥，使用 uuid v4 格式。
proposal_data	object	描述合作伙伴发送的提案数据的对象。
status	string	提案状态（`created`、`bid`、`lost`、`won`、`cancelled`）。
cet	float	为拍卖中提交的提案计算的 CET 值（后续计算）。
updated_at	string	提案提交或更新的日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`。
rank_position	integer	当前提案在其对应提案申请的拍卖排名中的位置。

注：proposal_data 对象的内容由参与者在后续描述的请求中发送的信息组成。

提案状态详细说明

提案的状态可以是：

状态	描述
created	提案已创建，但尚未提交到其对应进行中的提案申请的拍卖中。
bid	提案已以其条件提交至拍卖——仍可修改。
lost	提案在该提案申请的拍卖中落败。拍卖已关闭，未纳入本提案。
won	提案赢得了该提案申请的拍卖。拍卖已关闭，并纳入了本提案。
cancelled	提案已被参与者取消。

接受提案申请并创建提案

要接受受益人创建的提案申请并查询其完整数据，请使用通过自动 Webhook 或后续查询获取的提案申请 ID 进行 API 调用，示例如下：

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}/proposal

MÉTODO

- POST

Path Params

字段	类型	描述	字符数	必填
`proposal_request_key`	uuidv4	ProposalRequest 的唯一标识密钥，使用 uuid v4 格式。	36	是

Response

STATUS

- 201 (Created)

Response Body：提案已创建

{"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea"}

Response Body Params

字段	类型	描述	字符数	必填
`request_control_key`	uuidv4	提交的提案的唯一标识密钥，使用 uuid v4 格式。	36	是

在拍卖中提交提案

要有效地提交或更新您在信贷拍卖中的提案，请使用提案的相关数据进行 API 调用，示例如下：

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}

MÉTODO

- PATCH

Request Body：在拍卖中提交 Proposal

{
    "disbursed_issue_amount": 15000,
    "monthly_interest_rate": 0.04252764,
    "installment_face_value": 400.00,
    "number_of_installments": 48,
    "contacts": [
        {
            "contact_type": "email",
            "contact": "exemplo@qitech.com.br"
        },
        {
            "contact_type": "phone",
            "contact": "5511999999999"
        }
    ],
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}

注意

对于 monthly_interest_rate 和 installment_face_value 字段，请求中只能填写这 2 个字段中的 1 个。另一个无需包含在发送的 Payload 中；如果包含，则必须设置为空值。

Body Params

字段	类型	描述	必填
`disbursed_issue_amount`	float	提案预期放款金额。	是
`monthly_interest_rate`	float	提案月利率，区间为 0 到 1（分别对应 0% 到 100%）。	否
`installment_face_value`	float	提案预期分期金额。	否
`number_of_installments`	integer	提案的分期数。	是
`contacts`	array	将发送给受益人的提案联系方式列表	是
`contacts.contact_type`	string	提案中注册的联系渠道类型。可选值为 `email`、`phone` 和 `website`。	是
`contacts.contact`	string	将发送给受益人的合作伙伴联系方式。	是
`expiration_datetime`	string	发送给受益人的提案过期日期，格式为 `YYYY-MM-DDTHH:MM:SSZ`	是

Response

STATUS

- 202 (Accepted)

Response Body：提案已创建

{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "bid",
  "rank_position": 2
}

Response Body Params

字段	类型	描述
`request_control_key`	string	提交的提案的唯一标识密钥，使用 uuid v4 格式。
`status`	string	提案状态
`rank_position`	integer	该提案在其对应提案申请的拍卖排名中的位置

取消提案

如需删除已创建或已提交至拍卖的提案，只需使用提案的相关数据进行 API 调用：

注意！

每个提案申请只能创建/提交一个提案。鉴于拍卖的动态特性，一旦取消提案，将无法撤销，也无法为同一提案申请提交新的提案。

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}/cancel

MÉTODO

- PUT

字段	类型	描述	字符数	必填
`proposal_request_key`	uuidv4	ProposalRequest 的唯一标识密钥，使用 uuid v4 格式。	36	是
`request_control_key`	uuidv4	提交的提案的唯一标识密钥，使用 uuid v4 格式。	36	是

Response

STATUS

- 202 (Accepted)

Response Body：提案已取消

{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}

Response Body Params

字段	类型	描述
`request_control_key`	string	提交的提案的唯一标识密钥，使用 uuid v4 格式。
`status`	string	提案状态

查询提案

如需查询您的提案，只需使用创建提案时返回的 ID 进行 API 调用：

ENDPOINT

- /social_security_auction/proposal/{request_control_key}

MÉTODO

- GET

Path Params

字段	类型	描述	字符数	必填
`request_control_key`	uuidv4	提交的提案的唯一标识密钥，使用 uuid v4 格式。	36	是

Response

STATUS

- 200

Response Body：查询已提交至拍卖的提案

{
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "bid",
    "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
    "proposal_data": {
        "contacts": [
            {
                "contact": "exemplo@qitech.com.br",
                "contact_type": "email"
            },
            {
                "contact": "5511999999999",
                "contact_type": "phone"
            }
        ],
        "simulation": {
            "cet": 0.0019,
            "annual_cet": 0.023647,
            "iof_amount": 462.04,
            "issue_amount": 15539.74,
            "disbursed_issue_amount": 15000,
            "prefixed_interest_rate": {
                "daily_rate": 0.00001417,
                "annual_rate": 0.00511527,
                "monthly_rate": 0.00042528,
                "interest_base": "calendar_days"
            },
            "installments_face_value": 327.04
        },
        "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ",
        "monthly_interest_rate": 0.04252764,
        "disbursed_issue_amount": 15000,
        "number_of_installments": 48
    },
    "cet": 0.0019,
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "rank_position": 1
}

Response Body：查询已创建但未提交至拍卖的提案

{
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "created",
    "request_control_key": "01a7a1bf-b75b-4526-bbc3-a27e85e14325"
}

注：Response Body 中返回字段的详细说明在上方 Proposal 对象定义中描述。

HTTP 状态码

签名 API 使用以下 HTTP 返回状态标准，遵循 RFC 7231：

HTTP 状态码	含义	描述
400	Bad Request	发送的请求存在格式错误。大多数情况下，我们会在消息正文中返回错误位置的说明。
401	Unauthorized	认证出现问题，请检查 API Key 是否正确以及是否在正确的 header 中，参见认证部分。
403	Forbidden	访问的端点为内部使用，该 API Key 无权使用。
404	Not Found	使用提供的密钥未找到所请求的数据。当请求无效的端点时也会返回此状态。
405	Method Not Allowed	使用的 HTTP 方法不适用于该端点。
406	Not Acceptable	请求正文中发送的数据无效。通常意味着发送的数据不是有效的 JSON。
409	Conflict	请求 ID 与之前已处理的 ID 对应。当向服务器发送重复请求时会返回此状态。
500	Internal Server Error	处理此请求时出现问题，遇到此错误时，我们的专家将自动收到通知并立即开始分析和解决。
503	Service Unavailable	您遇到了我们服务器基础设施的计划或非计划中断。

简介​

欢迎使用我的 INSS 提案拍卖 API。​

遇到问题？​

环境​

仅限 HTTPS​

ProposalRequest：信贷提案申请​

ProposalRequest 对象定义​

ProposalRequestData 对象定义​

提案申请状态详细说明​

发送 Webhook 后查询提案申请​

Path Params​

Response - 部分查询​

Proposal：向受益人提交的信贷提案​

Proposal 对象定义​

提案状态详细说明​

接受提案申请并创建提案​

Path Params​

Response​

Response Body Params​

在拍卖中提交提案​

Body Params​

Response​

Response Body Params​

取消提案​

Response​

Response Body Params​

查询提案​

Path Params​

Response​

HTTP 状态码​

简介

欢迎使用我的 INSS 提案拍卖 API。

遇到问题？

环境

仅限 HTTPS

ProposalRequest：信贷提案申请

ProposalRequest 对象定义

ProposalRequestData 对象定义

提案申请状态详细说明

发送 Webhook 后查询提案申请

Path Params

Response - 部分查询

Proposal：向受益人提交的信贷提案

Proposal 对象定义

提案状态详细说明

接受提案申请并创建提案

Path Params

Response

Response Body Params

在拍卖中提交提案

Body Params

Response

Response Body Params

取消提案

Response

Response Body Params

查询提案

Path Params

Response

HTTP 状态码