Pular para o conteúdo principal

Manual Leilão de propostas Consignado Privado

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 a API de Leilão de Propostas do Consignado Privado

Leilão de Propostas Consignado Privado é um serviço que permite a consulta de Solicitações de Propostas emitidas pelos trabalhadores, e a inclusão de Propostas por parte dos consignatários, além de comparar as ofertas e escolher a que oferece as melhores condições.

A API permite a criação, atualização, consulta de colocação no ranking e cancelamento de propostas dentro do Leilão.

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.

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

A IssuerProposalRequest representa a Solicitação de Proposta de Crédito realizada pelo trabalhador, o potencial tomador de crédito. Para que a solicitação seja válida, é necessário que o trabalhador tenha margem consignável disponível.


Fluxo de Webhook na Solicitação de Crédito

Quando uma Solicitação de Proposta de Crédito é recebida, existem dois cenários possíveis:

1. Existe uma Proposta Reservada Pré-Criada

  • Se a proposta estiver assinada, o contrato será efetivado imediatamente, sem passar pelo processo de leilão.
  • Caso a proposta não esteja assinada, ela será enviada ao trabalhador para análise.
  • Um webhook de Encerramento de Leilão será enviado ao cliente originador da proposta.
  • Reservas de propostas para o mesmo tomador podem ser criadas, desde que tenham vínculos empregatícios distintos.

⚖️ 2. Não Existe Proposta Reservada

  • Um webhook de Início de Leilão será enviado a todos os clientes.
  • A partir desse momento, os clientes terão 3 minutos para enviar propostas.
  • Ao final do tempo:
    • Se houver propostas dentro do prazo, a melhor proposta será enviada ao trabalhador.
    • Se nenhuma proposta for enviada dentro dos 3 minutos, a primeira proposta enviada posteriormente será considerada.
  • Assim que uma proposta for enviada ao trabalhador, um webhook de Encerramento de Leilão será disparado para todos os participantes.

Exemplo de Webhook - Início de Leilão

WEBHOOK_TYPE
laas.private_payroll_auction.new_issuer_proposal_request

{
"status": "ongoing",
"event_datetime": "2025-03-20T14:47:43Z",
"key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
"webhook_type": "laas.private_payroll_auction.new_issuer_proposal_request",
"data": {
"issuer_proposal_request_key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
"status": "ongoing",
"expiration_datetime": "2025-03-21T11:47:12Z",
"inclusion_limit_datetime": "2025-03-20T11:49:43Z",
"issuer_proposal_request_data": {
"issuer_registration_number": "TESTE123",
"birth_date": "1973-03-14",
"disbursed_issue_amount": 2100,
"admission_date": "2020-03-10",
"consigned_credit_balance": 10000,
"eligible": true,
"employer_document_type": "cnpj",
"document_number": "00737823780",
"employer_document_number": "29113956000181",
"number_of_installments": 10,
"political_exposition": "not_exposed",
"name": "VALENTINA SANTOS"
},
}
}

Exemplo do Webhook - Encerramento de Leilão

WEBHOOK_TYPE
laas.private_payroll_auction.end_of_auction

{
"key": "150cfaa5-99dc-4c80-be3e-2231350cf9a2",
"data": {
"auction_proposal_key": "250cfea5-99dc-4c80-be3e-2231350cf9a2",
"status": "won",
"type": "auction",
"rank_position": 1,
"signature_url": "https://sandbox.sign.qitech.com.br/r/3D1s523",
"credit_operation_key": "9e06ca79-3610-4794-8312-9663e0343f6b",
"issuer_proposal_request_key": "262d0584-9827-4652-9b27-6a46c9832f38"
},
"status": "won",
"event_datetime": "2025-03-20T14:48:43Z",
"webhook_type": "laas.private_payroll_auction.end_of_auction"
}

A chave da operação de crédito será enviada com valor null para as propostas perdedoras.

Definição do Objeto IssuerProposalRequest

Todas as trocas de informação de uma IssuerProposalRequest 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.

NomeTipoDescrição
issuer_proposal_request_keystringIdentificador único da Solicitação de Proposta
issuer_proposal_request_dataobjectObjeto que descreve os dados da Solicitação de Proposta
statusstringStatus da Solicitação de Proposta (ongoing, finished, expired)

Definição do Objeto IssuerProposalRequestData

NomeTipoDescrição
namestringNome completo do Tomador
document_numberstringCPF do Tomador
birth_datestringData de nascimento do Tomador no formato YYYY-MM-DD
disbursed_amountfloatValor de desembolso solicitado pelo tomador
number_of_installmentsintegerNúmero de parcelas solicitados pelo tomador
consigned_credit_balancefloatMargem consignável disponível de saldo do tomador
admission_datestringData de admissão do trabalhador no cargo atual no formato YYYY-MM-DD
issuer_registration_codestringMatricula eSocial do empregado
employer_document_numberstringCNPJ do empregador
eligiblebooleanTrue se elegivel, False se não elegivel
employer_document_typestringCNPJ ou CPF

Detalhamento dos Status da solicitação de proposta

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

StatusDescrição
ongoingSolicitação de Proposta em andamento, o leilão continua ativo.
finishedSolicitação de Proposta finalizada, o leilão foi encerrado e uma Proposta enviada foi aceita e incluída.
expiredSolicitação de Proposta expirada, o leilão foi encerrado sem a inclusão de nenhuma Proposta em tempo hábil.

Detalhamento dos níveis de exposição política

Os valores da Exposição Politica podem ser:

StatusDescrição
not_exposedPessoa não exposta politicamente.
level_1Pessoa exposta politicamente nível 1
level_2Pessoa exposta politicamente nível 2
not_informedNão há informação sobre a exposição política

Tipo da proposta

O type representa o tipo da proposta, no caso se ela passou por um leilão ou se foi pré reservada. Será enviado no webhook de fim de leilão

TypeDescrição
"auction"Proposta passou pelo leilão interno
"pre-auction"Proposta foi pré reservada

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 tomador de crédito (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.

ENDPOINT
- /private_payroll_auction/issuer_proposal_request/{issuer_proposal_request_key}
MÉTODO
- GET

Path Params

CampoTipoDescriçãoCaracteresObrigatório
issuer_proposal_request_keyuuidv4Chave única de identificação da IssuerProposalRequest utilizada no formato uuid v4.36Sim

Response

A resposta retornada será a mesma que foi enviada no webhook de Inicio de Leilão.

AuctionProposal – Proposta de Crédito

A AuctionProposal é o objeto que representa a Proposta de Crédito realizada pelo consignatário ao trabalhador.

Existem duas possibilidades de realização de proposta, uma com reserva pré leilão, e outra pelo leilão normal.

🎯 Reserva de Proposta

  • Caso o cliente esteja em contato com o tomador, pode criar e assinar uma operação de crédito com colateral de "private_payroll". Depois, pode reservar uma proposta, que terá tempo de expiração de 24 horas.

  • Se houver uma Solicitação de Proposta para esse tomador dentro desse período, um Webhook de encerramento do leilão será enviado ao cliente, a operação de crédito será desembolsada e a margem averbada imediatamente.

  • Caso contrário, a proposta expirará e não terá mais validade.

Definição do Objeto AuctionProposal

Todas as trocas de informação de uma AuctionProposal 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.

NomeTipoDescrição
issuer_proposal_request_keystringIdentificador único da Solicitação de Proposta.
auction_proposal_keystringChave única de identificação da AuctionProposal incluída no formato uuid v4.
proposal_dataobjectObjeto que descreve os dados da AuctionProposal enviados pelo paceiro.
statusstringStatus da Proposta no Leilão (bid, lost, won, cancelled, awaiting_issuer_proposal_request).
proposal_scorefloatNota da proposta incluída no Leilão, a comparação dos proposal_score determina o rank_position.
inclusion_datestringData da inclusão ou última da Proposta no formato YYYY-MM-DDTHH:MM:SSZ.
rank_positionintegerPosiçã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 Proposta

O status da Proposta pode ser:

StatusDescrição
bidProposta foi incluída no leilão com suas condições - ainda passível de alterações.
awaiting_issuer_proposal_requestProposta pré cadastrada, aguardando Solicitação de Proposta.
lostProposta perdeu o Leilão daquela Solicitação de Proposta. O Leilão foi encerrado sem a inclusão desta Proposta.
wonProposta ganhou o Leilão daquela Solicitação de Proposta. O Leilão foi encerrado com a inclusão desta Proposta.
cancelledProposta cancelada pelo participante.

Criando uma reserva de Proposta no leilão

Para reservar uma Proposta no Leilão de Crédito, realize uma chamada via API com os dados pertinentes da Proposta no endpoint como no exemplo a seguir:

ENDPOINT
/debt
MÉTODO
POST
Request Body
{
"borrower": {
"name": "Nome devedor",
"phone": {
"number": "999538380",
"area_code": "84",
"country_code": "055"
},
"gender": "female",
"is_pep": false,
"address": {
"city": "Natal",
"state": "RN",
"number": "1984",
"street": "Rua",
"complement": "complemento",
"postal_code": "59065720",
"neighborhood": "bairro"
},
"role_type": "issuer",
"birth_date": "1959-07-08",
"mother_name": "NOME DA MAE",
"nationality": "Brasileiro",
"person_type": "natural",
"marital_status": "single",
"attached_documents_list": [],
"individual_document_number": "14471835092",
"document_identification_date": "2015-10-02",
"document_identification_type": "rg",
"document_identification_number": "003709888"
},
"financial": {
"interest_type": "pre_price_days",
"first_due_date": "2023-09-21",
"disbursement_date": "2024-11-07",
"fine_configuration": {
"monthly_rate": 0.0166,
"interest_base": "calendar_days",
"contract_fine_rate": 0
},
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"monthly_interest_rate": 0.0166,
"installment_face_value": 101.84,
"limit_days_to_disburse": 7,
"number_of_installments": 10,
"principal_grace_period": 0,
"rebates": [ // Opcional
{
"amount": 20,
"rebate_bank_account": {
"name": "Teste Ltda",
"document_number": "18533555000164",
"account_digit": "0",
"account_number": "4290001",
"branch_number": "0001",
"bank_code": "329"
},
"amount_type": "percentage",
"fee_type": "spread"
}
]
},
"simplified": true,
"collaterals": [
{
"collateral_data": {
"employer_document_number": "07940839000159",
"registration_number": "99999999999-A"
},
"collateral_type": "private_payroll"
}
],
"additional_data": {
"contract": {
"contract_number": "TST0000644799"
}
},
"purchaser_document_number": "32402502000135",
"disbursement_bank_accounts": [
{
"name": "NOME DEVEDOR",
"bank_code": "001",
"account_digit": "0",
"branch_number": "2874",
"account_number": "000057555",
"document_number": "14471835092",
"transfer_method": "pix",
"percentage_receivable": 100
}
]
}

Request Body

Atenção

Se o tomador solicitar uma proposta antes do cliente criar a reserva, sua solicitação será enviada a todos os clientes e o leilão irá acontecer normalmente.

Criando uma nova Proposta no leilão

O cliente pode fazer uma única Proposta para uma dada solicitação de proposta.

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

ENDPOINT
- /private_payroll_auction/issuer_proposal_request/{issuer_proposal_request_key}/auction_proposal
MÉTODO
- POST
Request Body: Incluindo uma AuctionProposal no leilão
{
"request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
"disbursed_issue_amount": 15000,
"installment_face_value": 400.00,
"number_of_installments": 48,
}
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.

Caso o cliente enviar outra proposta para a mesma solicitação de proposta, será retornado um erro com a auction proposal key da proposta já enviada e a request control key dessa última requisição

Erro:

{
"code" : "PPA000006",
"title" : "Conflict",
"description" : "Proposal already exists for Proposal Request and Requester",
"translation" : "Proposta para Solicitação de Proposta e Solicitante já existe."
}

e status 409.

Body Params

CampoTipoDescriçãoObrigatório
issuer_proposal_request_keystringChave única de identificação da IssuerProposalRequest incluída no formato uuid v4.Sim
auction_proposal_keystringChave única de identificação da AuctionProposal incluída no formato uuid v4.Sim
disbursed_issue_amountfloatValor de desembolso pretendido pela Proposta.Sim
monthly_interest_ratefloatTaxa de juros mensal da Proposta no intervalo de 0 a 1 (0% a 100%, respectivamente).Não
installment_face_valuefloatValor da parcela pretendida pela Proposta.Não
number_of_installmentsintegerNúmero de parcelas da proposta.Sim

Response

STATUS
- 202 (Accepted)
Response Body: Proposta criada
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
"request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
"status": "bid",
"proposal_score" : 0.4,
"inclusion_date" : "2025-03-18T14:52:07.123456",
"rank_position" : null,
"proposal_data": {
"simulation": {
"total_iof": 15.46,
"annual_cet": 0.0603,
"monthly_cet": 0.0049,
"issue_amount": 1015.46,
"annual_interest_rate": 0.0180272568,
"monthly_interest_rate": 0.00149,
"disbursed_issue_amount": 1000.0,
"installment_face_value": 102.25,
"number_of_installments" : 48
},
"monthly_interest_rate": null,
"disbursed_issue_amount": 15000,
"installment_face_value": 102.25,
"number_of_installments": 48
},
}

Response Body Params

CampoTipoDescrição
auction_proposal_keystringChave única de identificação da AuctionProposal incluída no formato uuid v4.
statusstringStatus da Proposta

Cancelando a Proposta

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

Atenção!

Apenas a última Proposta incluída no leilão para cada Solicitação de Proposta participa do leilão, as outras são automaticamente canceladas.

ENDPOINT
- /private_payroll_auction/auction_proposal/{auction_proposal_key}/cancel
MÉTODO
- PATCH
CampoTipoDescriçãoCaracteresObrigatório
issuer_proposal_request_keyuuidv4Chave única de identificação da IssuerProposalRequest utilizada no formato uuid v4.36Sim
auction_proposal_keyuuidv4Chave única de identificação da AuctionProposal incluída no formato uuid v4.36Sim

Response

STATUS
- 202 (Accepted)
Response Body: Proposta cancelada
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "cancelled"
}
Atenção!

Caso o leilão já tenha encerrado a proposta não pode mais ser cancelada.

Response no caso de proposta já enviada

STATUS
- 403 (Forbidden)
Response Body: Leilão encerrado e Proposta não pode ser cancelada
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "won"
}

Response Body Params

CampoTipoDescrição
auction_proposal_keystringChave única de identificação da AuctionProposal incluída no formato uuid v4.
statusstringStatus 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
- /private_payroll_auction/auction_proposal/{auction_proposal_key}
MÉTODO
- GET

Path Params

CampoTipoDescriçãoCaracteresObrigatório
auction_proposal_keyuuidv4Chave única de identificação da AuctionProposal incluída no formato uuid v4.36Sim

Response

STATUS
- 200
Response Body: Consulta da Proposta
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
"request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
"status": "bid",
"proposal_score" : 0.4,
"inclusion_date" : "2025-03-18T14:52:07.123456",
"rank_position" : null,
"proposal_data": {
"simulation": {
"total_iof": 15.46,
"annual_cet": 0.0603,
"monthly_cet": 0.0049,
"issue_amount": 1015.46,
"annual_interest_rate": 0.0180272568,
"monthly_interest_rate": 0.00149,
"disbursed_issue_amount": 1000.0,
"installment_face_value": 102.25,
"number_of_installments" : 48
},
"monthly_interest_rate": null,
"disbursed_issue_amount": 15000,
"installment_face_value": 102.25,
"number_of_installments": 48
}
}

Sendo o rank_position enviado tambem caso o leilão tenha encerrado.

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

Caso a proposta seja do tipo "pre-auction", o campo "proposal_data" terá formato:

{
"proposal_data": {
"total_iof": 7.69,
"annual_cet": 0.2553,
"monthly_cet": 0.0191,
"issue_amount": 332.2,
"annual_interest_rate": 0.1984483148,
"monthly_interest_rate": 0.0152,
"disbursed_issue_amount": 322.85,
"number_of_installments": 12,
"installment_face_value": 31.0
}
}

Status HTTP

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

Status HTTPSignificadoDescrição
400Bad RequestA 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.
401UnauthorizedHouve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação.
403ForbiddenO endpoint acessado é de uso interno e não está disponível para esta API Key.
404Not FoundO dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405Method Not AllowedO método HTTP utilizado não se aplica ao endpoint utilizado.
406Not AcceptableOs 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.
409ConflictO id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500Internal Server ErrorTivemos 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.
503Service UnavailableVocê se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.