Análise de Risco

Versão preliminar

Esta é a primeira versão da documentação do Análise de Risco e pode sofrer pequenas alterações. Recomendamos acompanhar esta página para futuras atualizações.

O endpoint de Análise de Risco permite realizar uma análise de crédito completa para o tomador, combinando onboarding, análise de crédito e consulta de balanço do consignado privado em uma única requisição.

A operação é assíncrona: ao enviar a requisição, a API retorna uma resposta síncrona com o status pending_analysis. O resultado final da análise é entregue via webhook quando o processamento é concluído.

Fluxo

O cliente envia um POST para /lending_analysis com os dados do tomador e as consultas desejadas.
A API retorna uma resposta síncrona com a lending_analysis_key e status pending_analysis.
Ao finalizar o processamento, a API envia um webhook com o resultado completo da análise.

Request

ENDPOINT

/lending_analysis

MÉTODO

POST

Request Body

{
    "request_identifier_key": "12345678901",
    "document_number": "46276658812",
    "lending_analysis_type": "private_payroll",
    "purchaser_document_number": "12345678000199",
    "private_payroll": {
        "employer_document_number": "12345678000199",
        "registration_number": "12345678901"
    },
    "authorization_term": {
        "legal_representative_document_number": "98765432100",
        "signature": {
            "signer": {
                "document_number": "46276658812",
                "name": "João da Silva",
                "email": "joao.silva@email.com",
                "phone": {
                    "number": "912345678",
                    "area_code": "11",
                    "country_code": "55"
                }
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2026-03-12T10:00:00Z",
                "ip_address": "192.168.1.100",
                "fingerprint": {},
                "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            }
        }
    },
    "analysis_data": {
        "name": "João da Silva"
    }
}

Body Params

Campo	Tipo	Descrição	Caracteres
`request_identifier_key`	string	Chave idempotente da requisição. Deve ser única por análise.	-
`document_number`	string	CPF do tomador (apenas dígitos).	11
`lending_analysis_type`	string	Tipo da análise de crédito.	Enumeradores Análise de Risco Type
`purchaser_document_number`	string	CNPJ do comprador/cessionário. (opcional)	14
`private_payroll`	object	Dados do consignado privado do tomador.	Private Payroll Object
`authorization_term`	object	Termo de autorização do tomador.	Authorization Term Object
`analysis_data`	object	Dados adicionais do tomador para a análise.	Analysis Data Object

Private Payroll Object

Campo	Tipo	Descrição	Caracteres
`employer_document_number`	string	CNPJ do empregador.	14
`registration_number`	string	Número de matrícula do trabalhador.	-

Authorization Term Object

Atenção

Nos casos em que houver representante legal, é necessário preencher o campo legal_representative_document_number com o CPF do representante legal, e os dados do objeto signer devem ser preenchidos com os dados do representante.

Para mais informações sobre o objeto authorization_term, consulte a documentação oficial: Consultas do Trabalhador - Consulta de Balanço

Campo	Tipo	Descrição	Caracteres
`legal_representative_document_number`	string	CPF do representante legal (obrigatório apenas quando houver representante legal).	11
`signature.signer.document_number`	string	CPF do assinante.	11
`signature.signer.name`	string	Nome do assinante.	-
`signature.signer.email`	string	Email do assinante. (opcional)	-
`signature.signer.phone.number`	string	Número de telefone do assinante. (opcional)	-
`signature.signer.phone.area_code`	string	DDD do assinante. (opcional)	2
`signature.signer.phone.country_code`	string	Código do país (ex: `"55"`). (opcional)	3
`signature.authentication_type`	string	Tipo de autenticação. Deve ser `"opt_in"`.	-
`signature.authenticity.timestamp`	string	Data e hora do aceite (formato ISO 8601: `2026-03-12T10:00:00Z`).	-
`signature.authenticity.ip_address`	string	IP da sessão do usuário (IPv4 ou IPv6).	-
`signature.authenticity.fingerprint`	object	Evidências adicionais de rastreabilidade (pode ser objeto vazio `{}`).	-
`signature.authenticity.session_id`	string	Identificador da sessão do usuário (min. 10, máx. 50 caracteres).	50

Analysis Data Object

Campo	Tipo	Descrição	Caracteres
`name`	string	Nome do tomador. (opcional)	-

Response

STATUS

202

Response Body

{
    "analysis_status": "pending_analysis",
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
}

Campo	Tipo	Descrição
`analysis_status`	string	Status atual da análise. Retorna `pending_analysis` na resposta síncrona.
`lending_analysis_key`	string	Chave UUID da análise, utilizada para correlacionar com o webhook.

STATUS

400

Response Body

{
    "title": "Bad Request",
    "description": "Invalid or missing required fields in the request body. Check 'document_number', 'lending_analysis_type', 'private_payroll', and 'authorization_term'.",
    "translation": "Campos obrigatórios ausentes ou inválidos no corpo da requisição. Verifique 'document_number', 'lending_analysis_type', 'private_payroll' e 'authorization_term'.",
    "extra_fields": {},
    "code": "LAS000001"
}

STATUS

409

Retornado quando o campo request_identifier_key já foi utilizado em uma requisição anterior.

Response Body

{
    "title": "Conflict",
    "description": "A lending analysis with the provided 'request_identifier_key' already exists. Each analysis must use a unique identifier.",
    "translation": "Já existe uma análise de crédito com o 'request_identifier_key' informado. Cada análise deve utilizar um identificador único.",
    "extra_fields": {
        "existing_lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
    },
    "code": "LAS000002"
}

Webhooks

Atenção!

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

Webhook type: laas.lending_analysis.lending_analysis_status_change

O webhook é enviado para a URL configurada no ambiente do cliente quando a análise é concluída.

Webhook de análise concluída

Response Body

{
    "key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.lending_analysis_status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "12345678901",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis",
                "analysis_step_status": "reproved",
                "reason": "Score do Serasa menor que 500",
                "output_data": {
                    "analysis_score": 100,
                    "credit_model_score": 100,
                    "maximum_monthly_interest_rate": 0.00,
                    "minimum_monthly_interest_rate": 0.00,
                    "maximum_installments_number": 10,
                    "minimum_installments_number": 1,
                    "maximum_disbursed_issue_amount": 4500.00,
                    "minimum_disbursed_issue_amount": 0.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "JOÃO SILVA",
                    "gender": "male",
                    "birth_date": "1985-07-20",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 5000.00,
                    "base_margin_amount": 4500.00,
                    "total_due_amount": 8207.54,
                    "admission_date": "2020-03-15",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "MARIA DA SILVA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 724325,
                        "description": "SOLDADOR ELETRICO"
                    },
                    "economic_activity": {
                        "code": 2833000,
                        "description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2010-05-12",
                    "legacy_loans": [],
                    "alerts": [
                        {
                            "alert_type": "leave",
                            "reference_date": "2025-02-11",
                            "event_id": 123456,
                            "leave_reason_code": 3,
                            "leave_start_date": "2025-02-11",
                            "leave_end_date": "2025-03-11"
                        },
                        {
                            "alert_type": "termination",
                            "reference_date": "2025-02-11",
                            "event_id": 789012,
                            "termination_reason_code": 1,
                            "termination_date": "2025-02-11",
                            "notice_period_start_date": "2025-01-11",
                            "notice_period_end_date": "2025-02-11"
                        }
                    ]
                }
            }
        ]
    }
}

Descrição dos campos do webhook

Campo	Tipo	Descrição
`key`	string	`lending_analysis_key` retornada na resposta síncrona.
`status`	string	Status do webhook.
`webhook_type`	string	Tipo do webhook.
`event_datetime`	string	Data e hora do evento (ISO 8601).
`data.request_identifier_key`	string	Chave idempotente informada na requisição original.
`data.analysis_status`	string	Status final da análise. Status da análise
`data.analysis_steps`	array	Lista de etapas da análise realizadas. Analysis Steps Object
`data.inquiries`	array	Dados retornados das consultas realizadas. Consulte a seção Dados de inquiry (inquiry_data).

Analysis Steps Object

Campo	Tipo	Descrição
`analysis_step_type`	string	Tipo da etapa. Tipos de análise individual
`analysis_step_status`	string	Status da etapa individual (`approved` ou `reproved`).
`reason`	string	Razão da aprovação ou reprovação, definida em regra pelo cliente.
`output_data`	object	Dados de saída específicos da etapa.

`output_data` para `credit_analysis`

Importante

Todos os campos do output_data são configuráveis nas regras de análise. Caso a regra não esteja configurada para retornar um determinado campo, ele será retornado vazio ou não estará presente no payload.

Campo	Tipo	Descrição
`analysis_score`	number	Score da análise de crédito.
`credit_model_score`	number	Score do modelo de crédito.
`maximum_monthly_interest_rate`	number	Taxa de juros mensal máxima.
`minimum_monthly_interest_rate`	number	Taxa de juros mensal mínima.
`maximum_installments_number`	number	Número máximo de parcelas.
`minimum_installments_number`	number	Número mínimo de parcelas.
`maximum_disbursed_issue_amount`	number	Valor máximo de desembolso.
`minimum_disbursed_issue_amount`	number	Valor mínimo de desembolso.

Dados de inquiry (`inquiry_data`)

O array inquiries no webhook contém os dados retornados das consultas realizadas durante a análise. Cada item possui os campos inquiry_type (tipo da consulta) e inquiry_data (dados retornados).

Para o tipo private_payroll, o objeto inquiry_data segue o mesmo padrão de resposta da Consulta de dados do trabalhador do consignado privado, incluindo dados pessoais, margem consignável, histórico do vínculo, empréstimos ativos e alertas.

A documentação completa dos campos, enumeradores e exemplos de resposta do inquiry_data está disponível em:

Consultas do Trabalhador — 2. Consulta de dados do trabalhador

Enumeradores

Enumeradores Lending Analysis Type

Campo	Descrição
`private_payroll`	Análise de crédito consignado privado

Status da análise

analysis_status (resposta síncrona e webhook data.analysis_status)

Status	Descrição
`pending_analysis`	A análise está em processamento
`approved`	A análise foi aprovada
`reproved`	A análise foi reprovada

Status do webhook

status (campo raiz do webhook)

Status	Descrição
`completed`	O processamento foi concluído
`failed`	O processamento falhou

Tipos de análise individual

analysis_step_type (dentro do array analysis_steps)

Enumerador	Descrição
`onboarding`	Análise de onboarding/cadastro
`credit_analysis`	Análise de crédito

Status da análise individual

analysis_step_status (dentro do array analysis_steps)

Status	Descrição
`approved`	Análise individual aprovada
`reproved`	Análise individual reprovada

Sandbox — Casos de teste

Aviso Importante!

Não utilize dados pessoais reais (CPF, CNPJ, etc.) em ambientes de sandbox.

No ambiente de sandbox, o resultado da análise é determinado pelo valor do campo analysis_data.name no body da requisição. Utilize os nomes abaixo para simular diferentes cenários:

Nome (`analysis_data.name`)	Resultado do onboarding	Resultado da credit_analysis	Status final (`analysis_status`)
`Ana Santos`	`approved`	`approved`	`approved`
`Carlos Oliveira`	`approved`	`reproved`	`reproved`
`Mariana Costa`	`reproved`	—	`reproved`
`Pedro Almeida`	`approved`	—	`approved`
`Fernanda Lima`	`reproved`	—	`reproved`

Como funciona

Onboarding approved + Credit analysis approved (Ana Santos): a análise completa é aprovada. O webhook retorna analysis_status: "approved" com ambas as etapas aprovadas.
Onboarding approved + Credit analysis reproved (Carlos Oliveira): o onboarding é aprovado mas a análise de crédito reprova. O webhook retorna analysis_status: "reproved".
Onboarding reproved (Mariana Costa, Fernanda Lima): o onboarding reprova e a análise de crédito não é executada. O webhook retorna analysis_status: "reproved" com apenas a etapa de onboarding.
Only onboarding approved (Pedro Almeida): apenas o onboarding é executado e aprovado, sem análise de crédito. O webhook retorna analysis_status: "approved" com apenas a etapa de onboarding.

Webhook — Sandbox com nome "Ana Santos"

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.lending_analysis_status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-001",
        "analysis_status": "approved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis",
                "analysis_step_status": "approved",
                "reason": "Score acima do mínimo",
                "output_data": {
                    "analysis_score": 750,
                    "credit_model_score": 720,
                    "maximum_monthly_interest_rate": 0.0449,
                    "minimum_monthly_interest_rate": 0.0199,
                    "maximum_installments_number": 24,
                    "minimum_installments_number": 3,
                    "maximum_disbursed_issue_amount": 15000.00,
                    "minimum_disbursed_issue_amount": 500.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "ANA SANTOS",
                    "gender": "female",
                    "birth_date": "1990-05-15",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 8000.00,
                    "base_margin_amount": 6500.00,
                    "total_due_amount": 3200.00,
                    "admission_date": "2018-09-01",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "LUCIA SANTOS",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 411010,
                        "description": "AUXILIAR DE ESCRITORIO"
                    },
                    "economic_activity": {
                        "code": 6499999,
                        "description": "OUTRAS ATIVIDADES DE SERVICOS FINANCEIROS"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2005-01-10",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}

Webhook — Sandbox com nome "Carlos Oliveira" (credit_analysis reproved)

{
    "key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.lending_analysis_status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-002",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis",
                "analysis_step_status": "reproved",
                "reason": "Score do Serasa menor que 500",
                "output_data": {
                    "analysis_score": 100,
                    "credit_model_score": 100,
                    "maximum_monthly_interest_rate": 0.00,
                    "minimum_monthly_interest_rate": 0.00,
                    "maximum_installments_number": 10,
                    "minimum_installments_number": 1,
                    "maximum_disbursed_issue_amount": 4500.00,
                    "minimum_disbursed_issue_amount": 0.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "CARLOS OLIVEIRA",
                    "gender": "male",
                    "birth_date": "1988-11-22",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 3500.00,
                    "base_margin_amount": 3000.00,
                    "total_due_amount": 12500.00,
                    "admission_date": "2019-06-10",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "ROSA OLIVEIRA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 724325,
                        "description": "SOLDADOR ELETRICO"
                    },
                    "economic_activity": {
                        "code": 2833000,
                        "description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2010-05-12",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}

Webhook — Sandbox com nome "Mariana Costa" (onboarding reproved)

{
    "key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.lending_analysis_status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-003",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding",
                "analysis_step_status": "reproved",
                "reason": "Documentação inválida",
                "output_data": {}
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "MARIANA COSTA",
                    "gender": "female",
                    "birth_date": "1992-03-08",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 6000.00,
                    "base_margin_amount": 5000.00,
                    "total_due_amount": 2100.00,
                    "admission_date": "2021-01-15",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "PAULA COSTA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 252305,
                        "description": "ANALISTA DE SISTEMAS"
                    },
                    "economic_activity": {
                        "code": 6201500,
                        "description": "DESENVOLVIMENTO DE PROGRAMAS DE COMPUTADOR SOB ENCOMENDA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2015-08-20",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}

Referências

Consultas do Trabalhador — Consignado Privado — Documentação completa sobre consulta de vínculos e consulta de balanço, incluindo detalhamento do authorization_term.

Request​

Body Params​

Private Payroll Object​

Authorization Term Object​

Analysis Data Object​

Response​

Webhooks​

Webhook de análise concluída​

Descrição dos campos do webhook​

Analysis Steps Object​

output_data para credit_analysis​

Dados de inquiry (inquiry_data)​

Enumeradores​

Enumeradores Lending Analysis Type​

Status da análise​

Status do webhook​

Tipos de análise individual​

Status da análise individual​

Sandbox — Casos de teste​

Referências​

Request

Body Params

Private Payroll Object

Authorization Term Object

Analysis Data Object

Response

Webhooks

Webhook de análise concluída

Descrição dos campos do webhook

Analysis Steps Object

`output_data` para `credit_analysis`

Dados de inquiry (`inquiry_data`)

Enumeradores

Enumeradores Lending Analysis Type

Status da análise

Status do webhook

Tipos de análise individual

Status da análise individual

Sandbox — Casos de teste

Referências