私人养老金手册 - 查询
下一步
API 开发中
该 API 仍处于开发阶段,因此本手册可能会有所变动。
1. 担保查询
担保查询允许核查与养老金产品相关的信息。此操作为异步操作,查询请求将被发送至我们的队列之一并随后处理。请求会立即返回与查询请求相关的唯一标识符及其处理状态。
Request
POST
/private_pension/inquiryPayload
{
"document_number": "\<CPF DO ASSINANTE\>",
"operating_entity": "\<CNPJ ENTIDADE OPERADORA\>",
"investment_funds": [
{
"susep_process_number": "",
"certificate": "",
"name": "",
"document_number": "",
"class": "",
"subclass": "",
},
{
"susep_process_number": "",
"certificate": "",
"name": "",
"document_number": "",
"class": "",
"subclass": "",
},
{
"susep_process_number": "",
"certificate": "",
"name": "",
"document_number": "",
"class": "",
"subclass": "",
},
],
"authorization_term": {
"signature": {
"signer": {
"name": "\<NOME DO ASSINANTE\>",
"birth_date": "\<DATA DE NASCIMENTO DO ASSINANTE\>",
"address": {
"street": "",
"neighborhood": "",
"city": "",
"state": "",
"postal_code": "",
},
"email": "\<EMAIL ASSINANTE\>",
"phone": {
"number": "\<NUMERO ASSINANTE\>",
"area_code": "\<DDD ASSINANTE\>",
"country_code": "55"
},
}
},
"authentication_type": "opt_in",
"authenticity": {
"timestamp": "\<DATA E HORA DA ASSINATURA\>",
"ip_address": "\<IP DO ASSINANTE\>",
"city": "\<CIDADE DA ASSINATURA\>",
"session_id": "\<ID DA SESSÃO DO ASSINANTE\>",
},
}
}
Body Details
| 字段 | 类型 | 描述 |
|---|---|---|
| document_number | string | 借款人 CPF |
| operating_entity | string | 运营实体枚举 |
| investment_funds | 对象 | 投资基金数据 |
| authorization_term | 对象 | 授权数据 |
对象 investment_funds
| 字段 | 类型 | 描述 |
|---|---|---|
| susep_process_number | string | SUSEP 流程编号 |
| certificate | string | 养老金产品证书 |
| name | string | 基金名称 |
| document_number | string | 基金 CNPJ |
| class | string | 基金类别 |
| subclass | string | 基金子类别 |
对象 authorization_term
| 字段 | 类型 | 描述 |
|---|---|---|
| signature | 对象 | 签名数据 |
| authentication_type | string | 认证类型 (opt_in) |
| authenticity | 对象 | 真实性数据 |
对象 signature
| 字段 | 类型 | 描述 |
|---|---|---|
| signer | 对象 | 签署人数据 |
对象 signer
| 字段 | 类型 | 描述 |
|---|---|---|
| name | string | 签署人姓名 |
| birth_date | string | 签署人出生日期 |
| address | 对象 | 签署人地址 |
| 对象 | 签署人电子邮件地址 | |
| phone | 对象 | 签署人电话 |
对象 address
| 字段 | 类型 | 描述 |
|---|---|---|
| street | string | 街道 |
| neighborhood | string | 街区 |
| city | string | 城市 |
| state | string | 州 |
| postal_code | string | 邮政编码 |
对象 phone
| 字段 | 类型 | 描述 |
|---|---|---|
| number | string | 电话号码 |
| area_code | string | 区号 (DDD) |
| country_code | string | 国家电话代码 |
对象 authenticity
| 字段 | 类型 | 描述 |
|---|---|---|
| timestamp | string | 借款人接受的时间戳 |
| ip_address | string | 用户会话 IP |
| city | string | 签署城市 |
| session_id | string | 用户会话内部标识键 |
Response
STATUS
201 (CREATED)Payload
{
"inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
"inquiry_status": "pending_inquiry"
}
Response Body Details
| 字段 | 类型 | 描述 |
|---|---|---|
| inquiry_key | string | 担保查询的唯一标识符 |
| inquiry_status | string | 查询请求状态 (pending_inquiry/success/rejected) |
2. 担保处理查询
GET
/private_pension/inquiry/[inquiry_key]Response
Response Body
{
"inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
"inquiry_status": "pending_inquiry"
}
3. 担保查询 Webhook
查询请求处理完成后,客户将收到包含担保信息的 webhook。
注意
客户必须实现此 webhook 的处理逻辑,以获取担保查询请求的信息。
WEBHOOK TYPE
laas.private_pension.inquiry.status_changeSTATUS
sucessWebhook Body
{
"key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
"status": "success",
"webhook_type": "laas.private_pension.inquiry.status_change",
"event_datetime": "2025-10-08T01:00:00Z",
"data": {
"guarantees": [
{
"contract_id": "851cf2e4-524b-48d7-a133-fd10bb0a7313",
"product": "PGBL",
"operation_type": "PREVIDENCIA",
"operating_entity": {
"document_number": "42283770000139",
"operating_entity_name": "Icatu seguros",
"street": "Avenida Ibirapuera",
"neighborhood": "Moema",
"city": "São Paulo",
"state": "SP",
"postal_code": "04028002",
"authenticity": {
"timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
"city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
"session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
}
},
"guarantor": {
"contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
"person_type": "natural_person",
"document_number": "75020251038",
"name": "Nome garantidor",
"social_name": "Nome social garantidor",
"second_document_number": "126979364",
"birth_date": "1983-12-01",
"street": "Rua Maria Carolina",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"state": "SP",
"postal_code": "01445000",
"phone": "11911111111",
"email": "exemplo@gmail.com",
"movement_type": "supply",
"consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
"consent_file_url": null,
"consent_file_hash": null,
"legal_representatives": [],
},
"plan_type": "PGBL",
"initial_grace": true,
"accumulation_period_end_date": "2050-01-01",
"tax_regime": "indefinite",
"remaining_grace_period": 15,
"load_percentage": 99.50,
"investment_funds": [
{
"susep_process_number": "111111111111111111111111",
"certificate": "12345678QI",
"name": "Fundo QI Tech",
"document_number": "32402502000135",
"class": "Renda Fixa",
"subclass": "Crédito Privado",
"inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
"response_within_deadline": null,
"inquiry_processing_status": "inquiry_nuclea_register",
"inquiry_status": "pending",
"rejection_reason": null,
"rejection_reason_description": null,
"remuneration_criteria": null,
"available_gross_amount": 500,
"elegible_gross_amount": 250,
"lock_gross_amount": 200
}
]
},
{
"contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
"product": "VGBL",
"operation_type": "PREVIDENCIA",
"operating_entity": {
"document_number": "42283770000139",
"operating_entity_name": "Icatu seguros",
"street": "Avenida Ibirapuera",
"neighborhood": "Moema",
"city": "São Paulo",
"state": "SP",
"postal_code": "04028002",
"authenticity": {
"timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
"city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
"session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
}
},
"guarantor": {
"contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
"person_type": "natural_person",
"document_number": "75020251038",
"name": "Nome garantidor",
"social_name": "Nome social garantidor",
"second_document_number": "126979364",
"birth_date": "1983-12-01",
"street": "Rua Maria Carolina",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"state": "SP",
"postal_code": "01445000",
"phone": "11911111111",
"email": "exemplo@gmail.com",
"movement_type": "supply",
"consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
"consent_file_url": null,
"consent_file_hash": null,
"legal_representatives": [],
},
"plan_type": "VGBL",
"initial_grace": true,
"accumulation_period_end_date": "2050-01-01",
"tax_regime": "indefinite",
"remaining_grace_period": 15,
"load_percentage": 99.50,
"investment_funds": [
{
"susep_process_number": "222222222222222222222222",
"certificate": "87654321QI",
"name": "Fundo QI Tech",
"document_number": "32402502000135",
"class": "Renda Fixa",
"subclass": "Crédito Privado",
"inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
"response_within_deadline": null,
"inquiry_processing_status": "inquiry_nuclea_register",
"inquiry_status": "pending",
"rejection_reason": null,
"rejection_reason_description": null,
"remuneration_criteria": null,
"available_gross_amount": 500,
"elegible_gross_amount": 250,
"lock_gross_amount": 200
}
]
},
{
"contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
"product": "PGBL",
"operation_type": "PREVIDENCIA",
"operating_entity": {
"document_number": "42283770000139",
"operating_entity_name": "Icatu seguros",
"street": "Avenida Ibirapuera",
"neighborhood": "Moema",
"city": "São Paulo",
"state": "SP",
"postal_code": "04028002",
"authenticity": {
"timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
"city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
"session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
}
},
"guarantor": {
"contract_code": "94039572-ecf1-4h84-h929-q3eb51gea231",
"person_type": "natural_person",
"document_number": "75020251038",
"name": "Nome garantidor",
"social_name": "Nome social garantidor",
"second_document_number": "126979364",
"birth_date": "1983-12-01",
"street": "Rua Maria Carolina",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"state": "SP",
"postal_code": "01445000",
"phone": "11911111111",
"email": "exemplo@gmail.com",
"movement_type": "supply",
"consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
"consent_file_url": null,
"consent_file_hash": null,
"legal_representatives": [],
},
"plan_type": "PGBL",
"initial_grace": true,
"accumulation_period_end_date": "2050-01-01",
"tax_regime": "indefinite",
"remaining_grace_period": 15,
"load_percentage": 99.50,
"investment_funds": [
{
"susep_process_number": "333333333333333333333333",
"certificate": "56781234QI",
"name": "Fundo QI Tech",
"document_number": "32402502000135",
"class": "Renda Fixa",
"subclass": "Crédito Privado",
"inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
"response_within_deadline": null,
"inquiry_processing_status": "inquiry_nuclea_register",
"inquiry_status": "pending",
"rejection_reason": null,
"rejection_reason_description": null,
"remuneration_criteria": null,
"available_gross_amount": 500,
"elegible_gross_amount": 250,
"lock_gross_amount": 200
}
]
}
]
}
}
Webhook Body Details
| 字段 | 类型 | 描述 |
|---|---|---|
| key | string | 查询请求键 |
| status | string | 文档状态 (success) |
| webhook_type | string | Webhook 类型 |
| event_datetime | string | 事件日期和时间 |
| data | object | Webhook 数据 |
Payload data
| 字段 | 类型 | 描述 |
|---|---|---|
| guarantees | 对象 | 担保数据 |
对象 guarantees
| 字段 | 类型 | 描述 |
|---|---|---|
| contract_id | string | 担保合同附件 IV 模型编号 |
| product | string | 运营实体中的产品名称 |
| operation_type | string | 产品类型 (previdencia) |
| operating_entity | 对象 | 运营实体数据 |
| guarantor | 对象 | 担保人数据 |
| plan_type | 对象 | 养老金计划类型 |
| initial_grace | bool | 是否存在初始宽限期 |
| accumulation_period_end_date | 对象 | 积累期结束日期 |
| tax_regime | enum | 税收制度 |
| remaining_grace_period | int | 宽限期剩余天数(以天为单位) |
| load_percentage | number | 费率百分比 |
| investment_funds | 对象 | 投资基金数据 |
对象 operating_entity
| 字段 | 类型 | 描述 |
|---|---|---|
| document_number | string | 运营实体 CNPJ |
| operating_entity_name | string | 运营实体名称 |
| street | string | 街道 |
| neighborhood | string | 街区 |
| city | string | 城市 |
| state | string | 州 |
| postal_code | string | 邮政编码 |
| authenticity | object | 真实性数据 |
对象 authenticity
| 字段 | 类型 | 描述 |
|---|---|---|
| timestamp | string | 运营实体接受的时间戳 |
| city | string | 签署城市 |
| session_id | string | 会话内部标识键 |
对象 guarantor
| 字段 | 类型 | 描述 |
|---|---|---|
| contract_code | string | 合同代码 |
| person_type | enum | 人员类型 (自然人, 法人) |
| document_number | string | 担保人 CPF/CNPJ |
| name | string | 担保人姓名 |
| social_name | string | 担保人社会姓名 |
| second_document_number | string | 担保人身份证号 (RG) |
| birth_date | string | 担保人出生日期 |
| street | string | 街道 |
| neighborhood | string | 街区 |
| city | string | 城市 |
| state | string | 州 |
| postal_code | string | 邮政编码 |
| phone | string | 担保人电话号码 |
| string | 担保人电子邮件地址 | |
| movement_type | enum | 操作类型 |
| consent_term_code | string | 同意条款代码 |
| consent_file_url | object | 同意文件 URL 数据 |
| consent_file_hash | string | 同意文件哈希值 |
| legal_representatives | object | 法定代表人 |
对象 investment_funds
| 字段 | 类型 | 描述 |
|---|---|---|
| susep_process_number | string | SUSEP 流程编号 |
| certificate | string | 养老金产品证书 |
| name | string | 基金名称 |
| document_number | string | 基金 CNPJ |
| class | string | 基金类别 |
| subclass | string | 基金子类别 |
| inquiry_id | string | 担保标识符 |
| response_within_deadline | bool | 是否在截止日期内响应 |
| inquiry_processing_status | enum | 查询请求处理状态 |
| inquiry_status | enum | 请求状态 |
| rejection_reason | enum | 查询拒绝原因 |
| rejection_reason_description | string | 查询拒绝原因描述 |
| remuneration_criteria | string | 报酬标准 |
| available_gross_amount | number | 可用总金额 |
| elegible_gross_amount | number | 符合条件的总金额 |
| lock_gross_amount | number | 待锁定总金额 |
对象 consent_file_url
| 字段 | 类型 | 描述 |
|---|---|---|
| url | string | 同意文件 URL |
| duration | string | URL 访问有效期 |
对象 legal_representatives
| 字段 | 类型 | 描述 |
|---|---|---|
| person_type | enum | 人员类型 |
| document_number | string | 法定代表人 CPF/CNPJ |
| name | string | 法定代表人姓名 |
| social_name | string | 法定代表人社会姓名 |
枚举 tax_regime
| 枚举值 | 描述 |
|---|---|
| indefinite | 不确定税收制度 |
| progressive | 累进税收制度 |
| regressive | 递减税收制度 |
枚举 person_type
| 枚举值 | 描述 |
|---|---|
| natural_person | 自然人 |
| legal_person | 法人 |
枚举 movement_type
| 枚举值 | 描述 |
|---|---|
| supply | 锁定同意 |
| renegotiate | 重新谈判同意 |
枚举 inquiry_processing_status
| 枚举值 | 描述 |
|---|---|
| inquiry_nuclea_register | 请求已由 Núclea 登记 |
| inquiry_sent_operating_entity | 请求已由运营实体接收 |
| inquiry_returned_operating_entity | 请求已由运营实体返回 |