Manual Leilão de propostas Meu INSS

Atenção!

Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Introdução

Bem-vindo à API de Leilão de Propostas do Meu INSS.

O Leilão de Propostas do Meu INSS é um serviço que permite a consulta de Solicitações de Propostas, criadas pelos beneficiários, e a inclusão de Propostas, por parte dos consignatários, para assim oferecer oportunidades de Crédito ao aposentado/pensionista.

A API permite a criação, atualização, consulta e cancelamento de propostas dentro do Leilão. Que vença a melhor proposta!!!

Problemas?

Caso tenha algum problema entre em contato com o nosso suporte (suporte@qitech.com.br) e nós responderemos o mais rápido possível.

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api-auth.qitech.app/
• Sandbox - https://api-auth.sandbox.qitech.app/

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

ProposalRequest: Solicitação de Proposta de Crédito

A ProposalRequest é o objeto que representa a Solicitação de Proposta de Crédito realizada pelo beneficiário. Para que um pensionista ou aposentado possa fazer uma solicitação, é necessário que ele tenha saldo disponível, esteja apto, além de possuir o benefício ativo e desbloqueado.

Quando a QI Tech receber uma nova Solicitação de Proposta de Crédito, enviaremos um Webhook para o endpoint configurado.

Segue abaixo um exemplo do payload enviado:

{
    "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
        }
    }
}

Atenção

Esses são os dados iniciais da solicitação de proposta. Para visualizar TODAS AS INFORMAÇÕES dos beneficiários é necessário criar uma Proposta aceitando a respectiva ProposalRequest. Os demais dados consistem no CPF, Nome, Data de nascimento, número de benefício, tipo de benefício, entre outros...

Definição do Objeto ProposalRequest

Todas as trocas de informação de uma ProposalRequest utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

Nome	Tipo	Descrição
proposal_request_key	string	Identificador único da Solicitação de Proposta
proposal_request_data	object	Objeto que descreve os dados da Solicitação de Proposta
status	string	Status da Solicitação de Proposta (ongoing, finished, expired)
expiration_datetime	string	Data de expiração da Solicitação de Proposta no formato YYYY-MM-DDTHH:MM:SSZ
inclusion_limit_datetime	string	Data limite para inclusão de Propostas no leilão no formato YYYY-MM-DDTHH:MM:SSZ

Definição do Objeto ProposalRequestData

Nome	Tipo	Descrição
name	string	Nome completo do Beneficiário
state	string	Estado do Beneficiário
document_number	string	CPF do Beneficário
birth_date	string	Data de nascimento do Beneficiário no formato DDMMYYYY
benefit_number	integer	Número do benefício do Aposentado/Pensionista
benefit_status	string	Enumerador que descreve a situação do benefício
assistance_type	string	Enumerador do Tipo do benefício
benefit_situation	string	Enumerador que descreve a situação do benefício
max_total_balance	float	Valor comprometido possível para a respectiva espécie do benefício
used_total_balance	float	Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC
requested_disbursed_amount	float	Valor de desembolso solicitado pelo beneficiário
number_of_installments	integer	Número de parcelas solicitados pelo beneficiário
has_legal_representative	boolean	Indica se o beneficiário possui representante legal
has_power_of_attorney	boolean	Indica se o beneficiário possui procurador
has_entity_representation	boolean	Indica se o beneficiário possui entidade de representação
consigned_credit.balance	float	Valor disponível de saldo do beneficiário

Detalhamento dos Status da solicitação de proposta

O status da Solicitação de Proposta pode ser:

Status	Descrição
ongoing	Solicitação de Proposta em andamento, o leilão continua ativo.
finished	Solicitação de Proposta finalizada, o leilão foi encerrado e uma Proposta enviada foi aceita e incluída.
expired	Solicitação de Proposta expirada, o leilão foi encerrado sem a inclusão de nenhuma Proposta em tempo hábil.

Consultando uma Solicitação de Proposta após o envio do Webhook

Caso queira, ainda é possível consultar novamente a Solicitação de Proposta feita pelo beneficiário (mesmo após o envio do Webhook automático). Realize uma chamada via API utilizando o ID da Solicitação de Proposta enviado via Webhook automático.

Atenção

A Consulta completa dos dados do beneficiário também só será permitida caso o Parceiro Aceite a Solicitação de Proposta e Crie uma Proposta.

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}

MÉTODO

- GET

Path Params

Campo	Tipo	Descrição	Caracteres	Obrigatório
proposal_request_key	uuidv4	Chave única de identificação da ProposalRequest utilizada no formato uuid v4.	36	Sim

Response - Consulta Parcial

STATUS

- 200

Response Body: Consulta parcial da PropostaRequest

{
    "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: Consulta completa da PropostaRequest

{
    "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"
}

OBS: O detalhamento dos campos do Response Body estão descritos na definição do Objeto ProposalRequest acima.

Proposal: Proposta de Crédito ao Beneficiário

A Proposal é o objeto que representa a Proposta de Crédito realizada pelo consignatário ao beneficiário. Para a QI Tech incluir uma nova Proposta para o aposentado/pensionista, dada uma determinada Solicitação de Proposta, será realizado um Leilão onde a melhor Oferta de Crédito será levada adiante.

Atenção

Será aceito somente uma única Proposta por Solicitação de Proposta - possibilidando apenas a alteração da mesma, conforme interesse do parceiro.

Definição do Objeto Proposal

Todas as trocas de informação de uma Proposal utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

Nome	Tipo	Descrição
proposal_request_key	string	Identificador único da Solicitação de Proposta.
request_control_key	string	Chave única de identificação da Proposal incluída no formato uuid v4.
proposal_data	object	Objeto que descreve os dados da Proposta enviados pelo paceiro.
status	string	Status da Proposta (created, bid, lost, won, cancelled).
cet	float	Valor do CET calculado para a proposta incluída no Leilão (calculado posteriormente).
updated_at	string	Data da inclusão ou atualização da Proposta no formato YYYY-MM-DDTHH:MM:SSZ.
rank_position	integer	Posição atual da Proposta no ranking do Leilão para sua respectiva Solicitação de Proposta equivalente.

OBS: O conteúdo do objeto proposal_data é composto por informações enviadas pelo Participante em requisição descrita posteriormente.

Detalhamento dos Status da solicitação de proposta

O status da Proposta pode ser:

Status	Descrição
created	Proposta foi criada, porém não foi incluída no Leilão da sua respectiva Solicitação de Proposta em andamento.
bid	Proposta foi incluída no leilão com suas condições - ainda passível de alterações.
lost	Proposta perdeu o Leilão daquela Solicitação de Proposta. O Leilão foi encerrado sem a inclusão desta Proposta.
won	Proposta ganhou o Leilão daquela Solicitação de Proposta. O Leilão foi encerrado com a inclusão desta Proposta.
cancelled	Proposta cancelada pelo participante.

Aceitando uma Solicitação de Proposta e Criando uma Proposta

Para aceitar a Solicitação de Proposta criada pelo beneficiário e conseguir consultar os seus dados completos, realize uma chamada via API com o ID recebido da Solicitação de Proposta via Webhook automático ou consulta posterior, conforme o exemplo abaixo:

ENDPOINT

- /social_security_auction/proposal_request/{proposal_request_key}/proposal

MÉTODO

- POST

Path Params

Campo	Tipo	Descrição	Caracteres	Obrigatório
proposal_request_key	uuidv4	Chave única de identificação da ProposalRequest utilizada no formato uuid v4.	36	Sim

Response

STATUS

- 201 (Created)

Response Body: Proposta criada

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

Response Body Params

Campo	Tipo	Descrição	Caracteres	Obrigatório
request_control_key	uuidv4	Chave única de identificação da Proposal incluída no formato uuid v4.	36	Sim

Incluindo uma Proposta no leilão

Para efetivamente incluir ou atualizar sua proposta no Leilão de Crédito, realize uma chamada via API com os dados pertinentes da Proposta conforme o exemplo abaixo:

ENDPOINT

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

MÉTODO

- PATCH

Request Body: Incluindo uma Proposal no leilão

{
    "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"
}

Atenção

Para os campos monthly_interest_rate e installment_face_value APENAS 1 destes 2 campos devem ser informados na requisição. O outro não precisa estar incluído dentro do Payload enviado, caso esteja, deve-se colocar valor nulo.

Body Params

Campo	Tipo	Descrição	Obrigatório
disbursed_issue_amount	float	Valor de desembolso pretendido pela Proposta.	Sim
monthly_interest_rate	float	Taxa de juros mensal da Proposta no intervalo de 0 a 1 (0% a 100%, respectivamente).	Não
installment_face_value	float	Valor da parcela pretendida pela Proposta.	Não
number_of_installments	integer	Número de parcelas da proposta.	Sim
contacts	array	Lista de contatos da Proposta que será enviado ao beneficiário	Sim
contacts.contact_type	string	Tipo de canal de contato registrado na Proposta. Os possíveis valores são email, phone e website.	Sim
contacts.contact	string	Contato do parceiro, que será enviado para o beneficiário.	Sim
expiration_datetime	string	Data de expiração da Proposta enviada ao beneficiário, no formato YYYY-MM-DDTHH:MM:SSZ	Sim

Response

STATUS

- 202 (Accepted)

Response Body: Proposta criada

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

Response Body Params

Campo	Tipo	Descrição
request_control_key	string	Chave única de identificação da Proposal incluída no formato uuid v4.
status	string	Status da proposta
rank_position	integer	Posição da proposta no Ranking do Leilão para a sua respectiva Solicitação de Proposta

Cancelando a Proposta

Caso queira excluir uma Proposta criada ou incluída no Leilão, basta realizar uma chamada via API, com os dados pertinentes da Proposta:

Atenção!

Só é possível Criar/Incluir UMA Proposta por Solicitação de Proposta. Dado ao caráter dinâmico do Leilão, caso cancele sua Proposta não é possível voltar atrás e/ou incluir uma nova para esta mesma Solicitação de Proposta.

ENDPOINT

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

MÉTODO

- PUT

Campo	Tipo	Descrição	Caracteres	Obrigatório
proposal_request_key	uuidv4	Chave única de identificação da ProposalRequest utilizada no formato uuid v4.	36	Sim
request_control_key	uuidv4	Chave única de identificação da Proposal incluída no formato uuid v4.	36	Sim

Response

STATUS

- 202 (Accepted)

Response Body: Proposta cancelada

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

Response Body Params

Campo	Tipo	Descrição
request_control_key	string	Chave única de identificação da Proposal incluída no formato uuid v4.
status	string	Status da proposta

Consultando a Proposta

Caso queira consultar a sua Proposta, basta apenas realizar uma chamada via API utilizando o ID retornado na hora da criação da Proposta:

ENDPOINT

- /social_security_auction/proposal/{request_control_key}

MÉTODO

- GET

Path Params

Campo	Tipo	Descrição	Caracteres	Obrigatório
request_control_key	uuidv4	Chave única de identificação da Proposal incluída no formato uuid v4.	36	Sim

Response

STATUS

- 200

Response Body: Consulta da Proposta Incluída no Leilão

{
    "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: Consulta da Proposta Criada e não incluida no Leilão

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

OBS: O detalhamento dos campos devolvidos no Respose Body estão descritos na definição do Objeto Proposal acima.

Status HTTP

A API de assinatura utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231:

Status HTTP	Significado	Descrição
400	Bad Request	A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401	Unauthorized	Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação.
403	Forbidden	O endpoint acessado é de uso interno e não está disponível para esta API Key.
404	Not Found	O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405	Method Not Allowed	O método HTTP utilizado não se aplica ao endpoint utilizado.
406	Not Acceptable	Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409	Conflict	O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500	Internal Server Error	Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503	Service Unavailable	Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.