Manual Previdência Privada

API em desenvolvimento

A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.

1. Consulta de garantias

A consulta de garantias permite verificar as informações referentes aos produtos de previdência. Esta operação é assíncrona, o pedido de consulta é enviado para uma de nossas filas e processado posteriormente. A requisição retorna de imediato o identificador único referente ao pedido de consulta e seu status de processamento.

Request

POST

/private_pension/balance_inquiry

Payload

{
    "document_number": "\<CPF DO ASSINANTE\>",
    "operating_entity": "\<ENUMERADOR 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

Campo	Tipo	Descrição
document_number	string	CPF do tomador
operating_entity	string	Enumerador da entidade operadora
investment_funds	objeto	Dados de fundos de investimento
authorization_term	objeto	Dados de autorização

Objeto investment_funds

Campo	Tipo	Descrição
susep_process_number	string	Número do processo SUSEP
certificate	string	Certificado do produto de previdência
name	string	Nome do fundo
document_number	string	CNPJ do fundo
class	string	Classe do fundo
subclass	string	Subclasse do fundo

Objeto authorization_term

Campo	Tipo	Descrição
signature	objeto	Dados de assinatura
authentication_type	string	Tipo de autenticação (opt_in)
authenticity	objeto	Dados de autenticidade

Objeto signature

Campo	Tipo	Descrição
signer	objeto	Dados do assinante

Objeto signer

Campo	Tipo	Descrição
name	string	Nome do assinante
birth_date	string	Data de nascimento do assinante
address	objeto	Endereço do assinante
email	objeto	Endereço de email do assinante
phone	objeto	Telefone do assinate

Objeto address

Campo	Tipo	Descrição
street	string	Logradouro
neighborhood	string	Bairro
city	string	Cidade
state	string	Estado
postal_code	string	CEP

Objeto phone

Campo	Tipo	Descrição
number	string	Número de telefone
area_code	string	DDD
country_code	string	Código de telefone do país

Objeto authenticity

Campo	Tipo	Descrição
timestamp	string	Timestamp do aceite do tomador
ip_address	string	IP da sessão do usuário
city	string	Cidade de assinatura
session_id	string	Chave identificadora interna da sessão do usuário

Enumerador operating_entity

Enumerador	Descrição
Icatu	Seguradora Icatu

Response

STATUS

201 (CREATED)

Payload

{
    "balance_inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "balance_inquiry_status": "pending_inquiry"
}

Response Body Details

Campo	Tipo	Descrição
balance_inquiry_key	string	Identificador única para a consulta da garantia
balance_inquiry_status	string	Status da requisição de consulta (pending_inquiry/success/rejected)

2. Consulta do processamento de garantias

GET

/private_pension/balance_inquiry/[balance_inquiry_key]

Response

Response Body

{
    "balance_inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "balance_inquiry_status": "pending_inquiry"
}

3. Webhook de consulta de garantias

Após o processamento do pedido de consulta, o cliente receberá um webhook com as informações das garantias.

Atenção

O cliente deve implementar o tratamento deste webhook para capturar as informações do pedido de consulta das garantias.

WEBHOOK TYPE

laas.private_pension.balance_inquiry.status_change

Webhook Body

{
  "balance_inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
  "status": "success",
  "webhook_type": "laas.private_pension.balance_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
                },
                {
                    "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
                },
                {
                    "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

Campo	Tipo	Descrição
balance_inquiry_key	string	Chave do pedido de consulta
status	string	Status do documento (success)
webhook_type	string	Tipo do webhook
event_datetime	string	Data e hora do evento
data	object	Dados do webhook

Payload data

Campo	Tipo	Descrição
guarantees	objeto	Dados de garantia

Objeto guarantees

Campo	Tipo	Descrição
contract_id	string	Código do anexo IV modelo de termo acessório ao instrumento contratual de garantia
product	string	Denominação do produto na entidade operadora
operation_type	string	Tipo do produto (previdencia)
operating_entity	objeto	Dados da entidade operadora
guarantor	objeto	Dados do garantidor
plan_type	objeto	Tipo do plano de previdência
initial_grace	bool	Existência de período de carência inicial
accumulation_period_end_date	objeto	Data final do período de acumulação
tax_regime	enum	Regime tributário
remaining_grace_period	int	Prazo remanescente do período de carência (em dias)
load_percentage	number	Percentual de carregamento
investment_funds	objeto	Dados de fundo de investimento

Objeto operating_entity

Campo	Tipo	Descrição
document_number	string	Cnpj da entidade operadora
operating_entity_name	string	Nome da entidade operadora
street	string	Logradouro
neighborhood	string	Bairro
city	string	Cidade
state	string	Estado
postal_code	string	CEP
authenticity	object	Dados de autenticidade

Objeto authenticity

Campo	Tipo	Descrição
timestamp	string	Timestamp do aceite da entidade operadora
city	string	Cidade de assinatura
session_id	string	Chave identificadora interna da sessão

Objeto guarantor

Campo	Tipo	Descrição
contract_code	string	Código contratual
person_type	enum	Tipo de pessoa (PF, PJ)
document_number	string	Cpf/cnpj do garantidor
name	string	Nome do garantidor
social_name	string	Nome social do garantidor
second_document_number	string	Rg do garantidor
birth_date	string	Data de nascimento do garantidor
street	string	Logradouro
neighborhood	string	Bairro
city	string	Cidade
state	string	Estado
postal_code	string	CEP
phone	string	Número de telefone do garantidor
email	string	Endereço de email do garantidor
movement_type	enum	Tipo de operação realizada
consent_term_code	string	Código do termo de consentimento
consent_file_url	object	Dados da url do arquivo de consentimento
consent_file_hash	string	Hash do arquivo de consentimento
legal_representatives	object	Representantes legais

Objeto investment_funds

Campo	Tipo	Descrição
susep_process_number	string	Número do processo SUSEP
certificate	string	Certificado do produto de previdência
name	string	Nome do fundo
document_number	string	CNPJ do fundo
class	string	Classe do fundo
subclass	string	Subclasse do fundo
inquiry_id	string	Identificador da garantia
response_within_deadline	bool	Resposta realizada dentro do prazo
inquiry_processing_status	enum	Status do processamento do pedido de consulta
inquiry_status	enum	Status do pedido
rejection_reason	enum	Motivo de recusa da consulta
rejection_reason_description	string	Descrição do motivo de recusa da consulta
remuneration_criteria	string	Critério de remuneração
available_gross_amount	number	Valor bruto disponível
elegible_gross_amount	number	Valor bruto elegível
lock_gross_amount	number	Valor bruto para bloquear

Objeto consent_file_url

Campo	Tipo	Descrição
url	string	Url do arquivo de consentimento
duration	string	Duração de validade de acesso da url

Objeto legal_representatives

Campo	Tipo	Descrição
person_type	enum	Tipo de pessoa
document_number	string	Cpf/cnpj do representante legal
name	string	Nome do representante legal
social_name	string	Nome social do representante legal

Enumerador tax_regime

Enumerador	Descrição
indefinite	Regime tributário indefinido
progressive	Regime tributário progressivo
regressive	Regime tributário regressivo

Enumerador person_type

Enumerador	Descrição
natural_person	Pessoa Física
legal_person	Pessoa Jurídica

Enumerador movement_type

Enumerador	Descrição
supply	Consentimento para a trava
renegotiate	Consentimento para a repactuação

Enumerador inquiry_processing_status

Enumerador	Descrição
inquiry_nuclea_register	Pedido cadastrado pela Núclea
inquiry_sent_operating_entity	Pedido recebido pela entidade operadora
inquiry_returned_operating_entity	Pedido retornado pela entidade operadora

Enumerador inquiry_status

Enumerador	Descrição
success	Sucesso no pedido de consulta
failure	Falha no pedido de consulta
pending	Pedido de consulta pendente

Enumerador rejection_reason

Enumerador	Descrição
invalid_signature	Assinatura inválida
invalid_client_information	Informações do cliente inválidas
invalid_plan_information	Informações do plano inválidas
incomplete_information	Informações incompletas
others	Outros motivos de rejeição

Manual Previdência Privada

1. Consulta de garantias​

Request​

Objeto investment_funds​

Objeto authorization_term​

Objeto signature​

Objeto signer​

Objeto address​

Objeto phone​

Objeto authenticity​

Enumerador operating_entity​

Response​

2. Consulta do processamento de garantias​

Response​

3. Webhook de consulta de garantias​

Payload data​

Objeto guarantees​

Objeto operating_entity​

Objeto authenticity​

Objeto guarantor​

Objeto investment_funds​

Objeto consent_file_url​

Objeto legal_representatives​

Enumerador tax_regime​

Enumerador person_type​

Enumerador movement_type​

Enumerador inquiry_processing_status​

Enumerador inquiry_status​

Enumerador rejection_reason​

1. Consulta de garantias

Request

Objeto investment_funds

Objeto authorization_term

Objeto signature

Objeto signer

Objeto address

Objeto phone

Objeto authenticity

Enumerador operating_entity

Response

2. Consulta do processamento de garantias

Response

3. Webhook de consulta de garantias

Payload data

Objeto guarantees

Objeto operating_entity

Objeto authenticity

Objeto guarantor

Objeto investment_funds

Objeto consent_file_url

Objeto legal_representatives

Enumerador tax_regime

Enumerador person_type

Enumerador movement_type

Enumerador inquiry_processing_status

Enumerador inquiry_status

Enumerador rejection_reason