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 é o objeto que representa a Solicitação de Proposta de Crédito realizada pelo trabalhador, o potencial tomador de crédito. Para que o trabalhador possa fazer uma solicitação, é necessário que ele tenha margem consignável.

Processo de Envio de Webhook na Solicitação de Proposta de Crédito

Ao receber uma Solicitação de Proposta de Crédito, existem dois cenários possíveis, dependendo do status do empregador do tomador:

📌 Empregador Conveniado

• Se o empregador do tomador estiver cadastrado como conveniado a clientes específico, a QI Tech enviará um Webhook apenas para esses cliente, utilizando o endpoint configurado.
• Esse cliente terá um prazo de 1 minuto para enviar uma proposta referente a essa solicitação.
• Caso nenhuma proposta seja recebida dentro desse prazo, a solicitação será disponibilizada para todos os clientes, por meio de um novo Webhook.

📌 Empregador Não Conveniado

• Se o empregador do tomador não estiver cadastrado como conveniado a nenhum cliente, a QI Tech enviará um Webhook imediatamente para todos os clientes, utilizando o endpoint configurado.

• Isso iniciará o processo de Leilão, permitindo que qualquer cliente envie uma proposta.

• Após a solicitação os clientes terão 2 minutos para fazer propostas, no final desse intervalo, a melhor proposta será enviada ao tomador. Caso nenhuma proposta seja enviada nesse intervalo, a primeira proposta enviada posteriormente será enviada ao tomador.

📋 Fornecimento da Lista de Empregadores Conveniados

A relação de empregadores conveniados deve ser fornecida à QI Tech diretamente pelos clientes, assim como os documentos de convênio. Com base nessa lista, a QI Tech direcionará corretamente os Webhooks durante o processo de solicitação de crédito.

Segue abaixo um exemplo do payload enviado nos webhooks:

{
    "issuer_proposal_request_key": "24e9625a-e264-4d33-8b59-a5238001b12f",
    "status": "ongoing",
    
    "issuer_proposal_request_data": {
        "document_number": 99972299910,
        "name": "Teste Homo_722999",
        "birth_date": "1990-10-20",
        "requested_disbursed_amount" : 5000.5,   
        "number_of_installments": 12,
        "consigned_credit_balance" : 1000.5,
        "admission_date": "25092014",
        "issuer_registration_code" : "MATCEN722",
        "employer_document_number" : 42422253000101,
    },

}

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.

Nome	Tipo	Descrição
issuer_proposal_request_key	string	Identificador único da Solicitação de Proposta
issuer_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, exclusive)

Definição do Objeto IssuerProposalRequestData

Nome	Tipo	Descrição
name	string	Nome completo do Tomador
document_number	string	CPF do Tomador
birth_date	string	Data de nascimento do Tomador no formato YYYY-MM-DD
requested_disbursed_amount	float	Valor de desembolso solicitado pelo tomador
number_of_installments	integer	Número de parcelas solicitados pelo tomador
consigned_credit_balance	float	Margem consignável disponível de saldo do tomador
admission_date	string	Data de admissão do trabalhador no cargo atual no formato YYYY-MM-DD
issuer_registration_code	string	Matricula eSocial do empregado
employer_document_number	string	CNPJ do empregador

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.
exclusive	Solicitação de Proposta em andamento, porém o empregador do trabalhador é conveniado a um cliente, portanto não há leilão interno e a proposta já foi enviada ao tomador.

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

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

Response

A resposta retornada será a mesma que foi enviada no webhook enviado anteriormente.

RequesterProposal – Proposta de Crédito

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

Para que a QI Tech inclua uma nova Proposta para o tomador, dada uma determinada Solicitação de Proposta, será realizado um Leilão, onde a melhor oferta de crédito será levada adiante.

🎯 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.

Atenção

Se o empregador do tomador estiver conveniado a outro cliente, a Proposta não poderá ser criada.

Atenção

Será considerada somente uma única Proposta por Solicitação de Proposta - sendo essa a mais recente entre as propostas enviada pelo cliente para uma dada solicitação de proposta.

Definição do Objeto RequesterProposal

Todas as trocas de informação de uma RequesterProposal 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
issuer_proposal_request_key	string	Identificador único da Solicitação de Proposta.
requester_proposal_control_key	string	Chave única de identificação da RequesterProposal incluída no formato uuid v4.
proposal_data	object	Objeto que descreve os dados da RequesterProposal enviados pelo paceiro.
status	string	Status da Proposta no Leilão (bid, lost, won, cancelled).
proposal_score	float	Nota da proposta incluída no Leilão, a comparação dos proposal_score determina o rank_position.
updated_at	string	Data da inclusão ou última 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 Proposta

O status da Proposta pode ser:

Status	Descrição
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.
awaiting_issuer_proposal_request	Proposta pré cadastrada, aguardando Solicitação de Proposta.

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 de criação da operação de crédito.

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

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}/requester_proposal

MÉTODO

- POST

Request Body: Incluindo uma RequesterProposal no leilão

{
    "requester_proposal_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
    "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"
}

Caso o cliente enviar outra proposta para a mesma solicitação de proposta, a proposta anterior será cancelada.

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 tomador	Sim
contacts.contact_type	string	Tipo de canal de contato registrado na Proposta. Os possíveis valores são website, whatsapp, email e phone	Sim
contacts.contact	string	Contato do parceiro, que será enviado para o tomador.	Sim
expiration_datetime	string	Data de expiração da Proposta enviada ao tomador, no formato YYYY-MM-DDTHH:MM:SSZ	Sim

Response

STATUS

- 202 (Accepted)

Response Body: Proposta criada

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

Response Body Params

Campo	Tipo	Descrição
requester_proposal_control_key	string	Chave única de identificação da RequesterProposal 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

Encerramento do Leilão

Quando o leilão for encerrado e a proposta vencedora for enviada ao tomador, os clientes receberão uma atualização via Webhook.

Segue abaixo um exemplo do payload enviado nos webhooks:

{
    "status": "won",
    "issuer_proposal_request_key": "900b3ab2-4080-4cae-a853-8e12812817ea",
    "requester_proposal_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
    "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"
}

Nesse caso o status será "won", "lost" ou "exclusive".

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/requester_proposal/{requester_proposal_control_key}/cancel

MÉTODO

- PATCH

Campo	Tipo	Descrição	Caracteres	Obrigatório
issuer_proposal_request_key	uuidv4	Chave única de identificação da IssuerProposalRequest utilizada no formato uuid v4.	36	Sim
requester_proposal_control_key	uuidv4	Chave única de identificação da RequesterProposal incluída no formato uuid v4.	36	Sim

Response

STATUS

- 202 (Accepted)

Response Body: Proposta cancelada

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

Atenção!

Caso a proposta já tenha sido enviada ao tomador ela não pode mais ser cancelada.

Response no caso de proposta já enviada

STATUS

- 403 (Forbidden)

Response Body: Proposta já foi enviada e não pode ser cancelada

{
  "requester_proposal_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "won"
}

Response Body Params

Campo	Tipo	Descrição
requester_proposal_control_key	string	Chave única de identificação da RequesterProposal 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

- /private_payroll_auction/requester_proposal/{requester_proposal_control_key}

MÉTODO

- GET

Path Params

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

Response

STATUS

- 200

Response Body: Consulta da Proposta

{
    "issuer_proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "bid",
    "requester_proposal_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
    },
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "rank_position": 1
}

OBS: O detalhamento dos campos devolvidos no Response Body estão descritos na definição do Objeto RequesterProposal 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.