跳到主要内容

私人养老金手册 - 查询

下一步
API 开发中

该 API 仍处于开发阶段,因此本手册可能会有所变动。


1. 担保查询

担保查询允许核查与养老金产品相关的信息。此操作为异步操作,查询请求将被发送至我们的队列之一并随后处理。请求会立即返回与查询请求相关的唯一标识符及其处理状态。

Request

POST
/private_pension/inquiry
Payload
{
"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_numberstring借款人 CPF
operating_entitystring运营实体枚举
investment_funds对象投资基金数据
authorization_term对象授权数据

对象 investment_funds

字段类型描述
susep_process_numberstringSUSEP 流程编号
certificatestring养老金产品证书
namestring基金名称
document_numberstring基金 CNPJ
classstring基金类别
subclassstring基金子类别

对象 authorization_term

字段类型描述
signature对象签名数据
authentication_typestring认证类型 (opt_in)
authenticity对象真实性数据

对象 signature

字段类型描述
signer对象签署人数据

对象 signer

字段类型描述
namestring签署人姓名
birth_datestring签署人出生日期
address对象签署人地址
email对象签署人电子邮件地址
phone对象签署人电话

对象 address

字段类型描述
streetstring街道
neighborhoodstring街区
citystring城市
statestring
postal_codestring邮政编码

对象 phone

字段类型描述
numberstring电话号码
area_codestring区号 (DDD)
country_codestring国家电话代码

对象 authenticity

字段类型描述
timestampstring借款人接受的时间戳
ip_addressstring用户会话 IP
citystring签署城市
session_idstring用户会话内部标识键

Response

STATUS
201 (CREATED)
Payload
{
"inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
"inquiry_status": "pending_inquiry"
}
Response Body Details
字段类型描述
inquiry_keystring担保查询的唯一标识符
inquiry_statusstring查询请求状态 (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_change
STATUS
sucess
Webhook 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
字段类型描述
keystring查询请求键
statusstring文档状态 (success)
webhook_typestringWebhook 类型
event_datetimestring事件日期和时间
dataobjectWebhook 数据

Payload data

字段类型描述
guarantees对象担保数据

对象 guarantees

字段类型描述
contract_idstring担保合同附件 IV 模型编号
productstring运营实体中的产品名称
operation_typestring产品类型 (previdencia)
operating_entity对象运营实体数据
guarantor对象担保人数据
plan_type对象养老金计划类型
initial_gracebool是否存在初始宽限期
accumulation_period_end_date对象积累期结束日期
tax_regimeenum税收制度
remaining_grace_periodint宽限期剩余天数(以天为单位)
load_percentagenumber费率百分比
investment_funds对象投资基金数据

对象 operating_entity

字段类型描述
document_numberstring运营实体 CNPJ
operating_entity_namestring运营实体名称
streetstring街道
neighborhoodstring街区
citystring城市
statestring
postal_codestring邮政编码
authenticityobject真实性数据

对象 authenticity

字段类型描述
timestampstring运营实体接受的时间戳
citystring签署城市
session_idstring会话内部标识键

对象 guarantor

字段类型描述
contract_codestring合同代码
person_typeenum人员类型 (自然人, 法人)
document_numberstring担保人 CPF/CNPJ
namestring担保人姓名
social_namestring担保人社会姓名
second_document_numberstring担保人身份证号 (RG)
birth_datestring担保人出生日期
streetstring街道
neighborhoodstring街区
citystring城市
statestring
postal_codestring邮政编码
phonestring担保人电话号码
emailstring担保人电子邮件地址
movement_typeenum操作类型
consent_term_codestring同意条款代码
consent_file_urlobject同意文件 URL 数据
consent_file_hashstring同意文件哈希值
legal_representativesobject法定代表人

对象 investment_funds

字段类型描述
susep_process_numberstringSUSEP 流程编号
certificatestring养老金产品证书
namestring基金名称
document_numberstring基金 CNPJ
classstring基金类别
subclassstring基金子类别
inquiry_idstring担保标识符
response_within_deadlinebool是否在截止日期内响应
inquiry_processing_statusenum查询请求处理状态
inquiry_statusenum请求状态
rejection_reasonenum查询拒绝原因
rejection_reason_descriptionstring查询拒绝原因描述
remuneration_criteriastring报酬标准
available_gross_amountnumber可用总金额
elegible_gross_amountnumber符合条件的总金额
lock_gross_amountnumber待锁定总金额
字段类型描述
urlstring同意文件 URL
durationstringURL 访问有效期
字段类型描述
person_typeenum人员类型
document_numberstring法定代表人 CPF/CNPJ
namestring法定代表人姓名
social_namestring法定代表人社会姓名

枚举 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请求已由运营实体返回

枚举 inquiry_status

枚举值描述
success查询请求成功
failed查询请求失败
pending查询请求待处理

枚举 rejection_reason

枚举值描述
invalid_signature无效签名
invalid_client_information无效客户信息
invalid_plan_information无效计划信息
incomplete_information信息不完整
others其他拒绝原因
WEBHOOK TYPE
laas.private_pension.inquiry.status_change
STATUS
failed
Webhook Body
{
"key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
"status": "failed",
"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": "failed",
"rejection_reason": "invalid_plan_information",
"rejection_reason_description": null,
"remuneration_criteria": null,
"available_gross_amount": null,
"elegible_gross_amount": null,
"lock_gross_amount": null
}
]
},
{
"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": "failed",
"rejection_reason": "others",
"rejection_reason_description": "O numero do processo susep nao se refere a esse produto",
"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": "success",
"rejection_reason": null,
"rejection_reason_description": null,
"remuneration_criteria": null,
"available_gross_amount": 500,
"elegible_gross_amount": 250,
"lock_gross_amount": 200
}
]
}
]
}
}