My INSS Proposal Auction Manual
QI Tech webhooks should not be mapped restrictively. Additional fields may be included in webhook payloads returned by our APIs.
Introduction
Welcome to the My INSS Proposal Auction API.
The My INSS Proposal Auction is a service that allows querying Proposal Requests, created by beneficiaries, and the inclusion of Proposals, by consigners, to offer Credit opportunities to retirees/pensioners.
The API allows creating, updating, querying and canceling proposals within the Auction. May the best proposal win!!!
Problems?
If you have any issues, please contact our support (suporte@qitech.com.br) and we will respond as quickly as possible.
Environments
We have two environments for our customers. The base URLs for the APIs are:
- Production -
https://api-auth.qitech.app/ - Sandbox -
https://api-auth.sandbox.qitech.app/
HTTPS Only
For security reasons, all communication with QI Tech APIs must be performed using HTTPS communication. To prevent HTTP calls from being made inadvertently or for other reasons, this server only makes available port 443 with TLS 1.2 communication. Calls made using other protocols will be automatically denied.
ProposalRequest: Credit Proposal Request
The ProposalRequest is the object that represents the Credit Proposal Request made by the beneficiary. For a pensioner or retiree to make a request, it is necessary that they have available balance, are eligible, and have an active and unblocked benefit.
When QI Tech receives a new Credit Proposal Request, we will send a Webhook to the configured endpoint.
Below is an example of the payload sent:
{
"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
}
}
}
This is the initial data of the proposal request. To view ALL INFORMATION about beneficiaries, it is necessary to create a Proposal accepting the respective ProposalRequest. The remaining data consists of CPF, Name, Birth date, benefit number, benefit type, among others...
ProposalRequest Object Definition
All information exchanges of a ProposalRequest use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted.
| Name | Type | Description |
|---|---|---|
| proposal_request_key | string | Unique identifier of the Proposal Request |
| proposal_request_data | object | Object that describes the data of the Proposal Request |
| status | string | Status of the Proposal Request (ongoing, finished, expired) |
| expiration_datetime | string | Expiration date of the Proposal Request in YYYY-MM-DDTHH:MM:SSZ format |
| inclusion_limit_datetime | string | Deadline for including Proposals in the auction in YYYY-MM-DDTHH:MM:SSZ format |
ProposalRequestData Object Definition
| Name | Type | Description |
|---|---|---|
| name | string | Full name of the Beneficiary |
| state | string | State of the Beneficiary |
| document_number | string | CPF of the Beneficiary |
| birth_date | string | Birth date of the Beneficiary in DDMMYYYY format |
| benefit_number | integer | Benefit number of the Retiree/Pensioner |
| benefit_status | string | Enumerator that describes the benefit situation |
| assistance_type | string | Enumerator of the benefit Type |
| benefit_situation | string | Enumerator that describes the benefit situation |
| max_total_balance | float | Possible committed value for the respective benefit species |
| used_total_balance | float | Total value committed in loan endorsements, reserved for portability, refinancing, changes, RMC and RCC |
| requested_disbursed_amount | float | Disbursement amount requested by the beneficiary |
| number_of_installments | integer | Number of installments requested by the beneficiary |
| has_legal_representative | boolean | Indicates if the beneficiary has a legal representative |
| has_power_of_attorney | boolean | Indicates if the beneficiary has a power of attorney |
| has_entity_representation | boolean | Indicates if the beneficiary has entity representation |
| consigned_credit.balance | float | Available balance amount of the beneficiary |
Proposal Request Status Details
The status of the Proposal Request can be:
| Status | Description |
|---|---|
| ongoing | Proposal Request ongoing, the auction continues active. |
| finished | Proposal Request finished, the auction has ended and a sent Proposal was accepted and included. |
| expired | Proposal Request expired, the auction has ended without including any Proposal in due time. |
Querying a Proposal Request after Webhook delivery
If desired, it is still possible to query the Proposal Request made by the beneficiary again (even after sending the automatic Webhook). Make a call via API using the ID of the Proposal Request sent via automatic Webhook.
The complete consultation of beneficiary data will also only be allowed if the Partner Accepts the Proposal Request and Creates a Proposal.
/social_security_auction/proposal_request/{proposal_request_key}GETPath Params
| Field | Type | Description | Characters | Required |
|---|---|---|---|---|
proposal_request_key | uuidv4 | Unique identification key of the ProposalRequest used in uuid v4 format. | 36 | Yes |
Response - Partial Query
Response Body: Partial query of 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: Complete query of 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"
}
NOTE: The field details of the Response Body are described in the ProposalRequest Object definition above.
Proposal: Credit Proposal to Beneficiary
The Proposal is the object that represents the Credit Proposal made by the consigner to the beneficiary. For QI Tech to include a new Proposal for the retiree/pensioner, given a specific Proposal Request, an Auction will be held where the best Credit Offer will be taken forward.
Only one Proposal per Proposal Request will be accepted - allowing only modification of the same, according to partner interest.
Proposal Object Definition
All information exchanges of a Proposal use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted.
| Name | Type | Description |
|---|---|---|
| proposal_request_key | string | Unique identifier of the Proposal Request. |
| request_control_key | string | Unique identification key of the Proposal included in uuid v4 format. |
| proposal_data | object | Object that describes the Proposal data sent by the partner. |
| status | string | Status of the Proposal (created, bid, lost, won, cancelled). |
| cet | float | CET value calculated for the proposal included in the Auction (calculated later). |
| updated_at | string | Date of inclusion or update of the Proposal in YYYY-MM-DDTHH:MM:SSZ format. |
| rank_position | integer | Current position of the Proposal in the Auction ranking for its respective equivalent Proposal Request. |
NOTE: The content of the proposal_data object is composed of information sent by the Participant in a request described later.
Proposal Request Status Details
The status of the Proposal can be:
| Status | Description |
|---|---|
| created | Proposal was created, but was not included in the Auction of its respective Proposal Request in progress. |
| bid | Proposal was included in the auction with its conditions - still subject to changes. |
| lost | Proposal lost the Auction of that Proposal Request. The Auction ended without including this Proposal. |
| won | Proposal won the Auction of that Proposal Request. The Auction ended with the inclusion of this Proposal. |
| cancelled | Proposal cancelled by the participant. |
Accepting a Proposal Request and Creating a Proposal
To accept the Proposal Request created by the beneficiary and be able to query their complete data, make a call via API with the ID received from the Proposal Request via automatic Webhook or subsequent query, as shown in the example below:
/social_security_auction/proposal_request/{proposal_request_key}/proposalPOSTPath Params
| Field | Type | Description | Characters | Required |
|---|---|---|---|---|
proposal_request_key | uuidv4 | Unique identification key of the ProposalRequest used in uuid v4 format. | 36 | Yes |
Response
Response Body: Proposal created
{"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea"}
Response Body Params
| Field | Type | Description | Characters | Required |
|---|---|---|---|---|
request_control_key | uuidv4 | Unique identification key of the Proposal included in uuid v4 format. | 36 | Yes |
Including a Proposal in the auction
To effectively include or update your proposal in the Credit Auction, make a call via API with the relevant Proposal data as shown in the example below:
/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}PATCHRequest Body: Including a Proposal in the auction
{
"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"
}
For the monthly_interest_rate and installment_face_value fields, ONLY 1 of these 2 fields should be informed in the request. The other does not need to be included in the sent Payload, if it is, a null value should be provided.
Body Params
| Field | Type | Description | Required |
|---|---|---|---|
disbursed_issue_amount | float | Disbursement amount intended by the Proposal. | Yes |
monthly_interest_rate | float | Monthly interest rate of the Proposal in the range from 0 to 1 (0% to 100%, respectively). | No |
installment_face_value | float | Installment amount intended by the Proposal. | No |
number_of_installments | integer | Number of installments of the proposal. | Yes |
contacts | array | List of contacts of the Proposal that will be sent to the beneficiary | Yes |
contacts.contact_type | string | Type of contact channel registered in the Proposal. Possible values are email, phone and website. | Yes |
contacts.contact | string | Partner contact, which will be sent to the beneficiary. | Yes |
expiration_datetime | string | Expiration date of the Proposal sent to the beneficiary, in YYYY-MM-DDTHH:MM:SSZ format | Yes |
Response
Response Body: Proposal created
{
"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "bid",
"rank_position": 2
}
Response Body Params
| Field | Type | Description |
|---|---|---|
request_control_key | string | Unique identification key of the Proposal included in uuid v4 format. |
status | string | Status of the proposal |
rank_position | integer | Position of the proposal in the Auction Ranking for its respective Proposal Request |
Canceling the Proposal
If you want to delete a Proposal created or included in the Auction, simply make a call via API, with the relevant Proposal data:
It is only possible to Create/Include ONE Proposal per Proposal Request. Given the dynamic nature of the Auction, if you cancel your Proposal it is not possible to go back and/or include a new one for this same Proposal Request.
/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}/cancelPUT| Field | Type | Description | Characters | Required |
|---|---|---|---|---|
proposal_request_key | uuidv4 | Unique identification key of the ProposalRequest used in uuid v4 format. | 36 | Yes |
request_control_key | uuidv4 | Unique identification key of the Proposal included in uuid v4 format. | 36 | Yes |
Response
Response Body: Proposal cancelled
{
"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "cancelled"
}
Response Body Params
| Field | Type | Description |
|---|---|---|
request_control_key | string | Unique identification key of the Proposal included in uuid v4 format. |
status | string | Status of the proposal |
Querying the Proposal
If you want to query your Proposal, simply make a call via API using the ID returned when creating the Proposal:
/social_security_auction/proposal/{request_control_key}GETPath Params
| Field | Type | Description | Characters | Required |
|---|---|---|---|---|
request_control_key | uuidv4 | Unique identification key of the Proposal included in uuid v4 format. | 36 | Yes |
Response
Response Body: Query of Proposal Included in Auction
{
"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: Query of Proposal Created and not included in Auction
{
"proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
"status": "created",
"request_control_key": "01a7a1bf-b75b-4526-bbc3-a27e85e14325"
}
NOTE: The field details returned in the Response Body are described in the Proposal Object definition above.
HTTP Status
The signature API uses the following standardization in HTTP return statuses, according to RFC 7231:
| HTTP Status | Meaning | Description |
|---|---|---|
| 400 | Bad Request | The sent request has some formatting error. In most cases, we return an explanation of where the error is in the message body. |
| 401 | Unauthorized | There was some problem with authentication, check if the API Key is correct and in the correct header, according to the Authentication section. |
| 403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key. |
| 404 | Not Found | The requested data was not found using the key used. This status is also returned when an invalid endpoint is requested. |
| 405 | Method Not Allowed | The HTTP method used does not apply to the endpoint used. |
| 406 | Not Acceptable | The data sent in the request body is invalid. Generally, this means the sent data is not valid JSON. |
| 409 | Conflict | The request id corresponds to an id already processed previously. This status is returned in case of duplicate requests sent to the server. |
| 500 | Internal Server Error | We had a problem processing this request, when we encounter this error our specialists are automatically notified and begin analysis and solution immediately. |
| 503 | Service Unavailable | You encountered an unavailability, planned or not, of our server infrastructure. |