# QI Tech — Risk Solutions › Análise de crédito
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
12 página(s).
Índice:
- Fluxo de Desafio (/documentation/caas/credit_analysis/challenge_flow)
- Recuperar uma Análise de Crédito (/documentation/caas/credit_analysis/get_credit_analysis)
- Status HTTP (/documentation/caas/credit_analysis/http_status)
- Introdução (/documentation/caas/credit_analysis/introduction)
- Análise de Crédito - Pessoa Jurídica (/documentation/caas/credit_analysis/legal_person)
- Análise de Crédito - Pessoa Física (/documentation/caas/credit_analysis/natural_person)
- Objetos Compartilhados (/documentation/caas/credit_analysis/objects)
- Dados Sistema de Informações de Créditos (SCR - BACEN) (/documentation/caas/credit_analysis/scr)
- Padrões (/documentation/caas/credit_analysis/standards)
- Dinâmica dos Status (/documentation/caas/credit_analysis/status_dynamics)
- Atualizar o status de uma Análise de Crédito (/documentation/caas/credit_analysis/update_credit_analysis)
- Webhook (/documentation/caas/credit_analysis/webhook)
---
# Fluxo de Desafio
URL: /documentation/caas/credit_analysis/challenge_flow
É possível, após a execução da análise, ter como decisão desafiar o usuário para realizar uma nova ação em sua plataforma. Esse fluxo pode ser utilizado para, por exemplo, solicitar um comprovante de renda para um usuário que ainda não se tem certeza que deve ser aprovado ou reprovado na análise de crédito.
Com este fluxo você pode configurar uma regra cuja decisão desafia seu cliente a enviar informações adicionais para o sistema, como uma foto de um holerite ou qualquer outra informação relevante, e, depois de coletadas, utilização essas informações adicionais na execução de uma nova regra para reavaliação do usuário.
Há duas possibilidades de utilização deste fluxo, um deles de maneira automática, e outra fruto da decisão manual de um analista. Para o primeiro, o *analysis_status* retornado será *automatically_challenged* e para o segundo será *manually_challenged*. Abaixo temos a descrição do fluxo.
## Passo-a-passo da execução do fluxo
**1.** Proposta é submetida para análise (ver seção Análise de Crédito - Pessoa Física ou Análise de Crédito - Pessoa Jurídica ), e retornará o status *automatically_challenge* ou *in_manual_analysis*.
Request Body
```json
{
"id": "12345",
"registration_id":"12345",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "clean",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_challenge"
}
```
Caso a requisição retorne na resposta o status de *in_manual_analysis*, o analista poderá, através da dashboard, desafiar o usuário. Neste caso o status que será enviado na requisição de webhook é *manually_challenged*.
Response Body
```json
{
"id": "12345",
"analysis_status": "manually_challenged"
}
```
**2.** Após a primeira requisição de análise ter retornado um dos dois *analysis_status* de desafio, uma nova requisição deverá ser enviada com as informações adicionais coletadas do cliente, como por exemplo, uma novo imagem de documento enviada. Esta requisição deve conter o mesmo *registration_id* da requisição anterior, uma vez que este campo será utilizado para que a plataforma identifique que ambas as requsições se referem ao mesmo usuário, bem como vincular as informações adicionais coletadas do cliente.
Request Body: Envio com informações adicionais
```json
{
"id": "67890",
"registration_id":"12345",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "clean",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
"documents": {
"cnh": {
"ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
}
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_approved"
}
```
Atente-se para utilizar o mesmo registration_id utilizado na sua primeira análise.
---
# Recuperar uma Análise de Crédito
URL: /documentation/caas/credit_analysis/get_credit_analysis
A fim de recuperar uma Análise de Crédito específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Análise em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.
* **Natural Person:**
`GET https://api.caas.qitech.app/credit_analysis/natural_person/12345678`
* **Legal Person:**
`GET https://api.caas.qitech.app/credit_analysis/legal_person/12345678`
```shell
curl "https://api.caas.qitech.app/credit_analysis/natural_person/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> O comando acima retorna o JSON que representa um objeto de Natural Person.
```shell
curl "https://api.caas.qitech.app/credit_analysis/legal_person/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> O comando acima retorna o JSON que representa um objeto de Legal Person.
---
# Status HTTP
URL: /documentation/caas/credit_analysis/http_status
Todas as APIs da QI Tech 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.
---
# Introdução
URL: /documentation/caas/credit_analysis/introduction
Bem vindo à API de análise de crédito da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de executar uma análise de crédito, além de utilizar para atualizar a situação de um crédito concedido.
:::info **Atenção**
Atenção, esta API é direcionada a empresas que concedem crédito para Pessoas Físicas e Jurídicas. Ela tem como objetivo realizar toda a análise de crédito das operações do seu cliente, a partir dos dados enviados, dos dados de bureaus e fontes externas e dos dados do datalake da QI Tech, de maneira a tornar claro o retorno vs risco de cada uma das operações.
Esta API é projetada para pessoas físicas e jurídicas de pequeno porte. Não está preparada para calcular o risco de crédito de pessoas jurídicas de grande porte, onde é necessário um conhecimento aprofundado da operação e do mercado onde a empresa atua.
:::
## Problemas?
Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!
### Adoramos Feedback
Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!
## Ambientes
Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:
* Produção - `https://api.caas.qitech.app/credit_analysis/`
* Sandbox - `https://api.sandbox.caas.qitech.app/credit_analysis/`
:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::
No ambiente de Sandbox, as análises enviadas não são cobradas, são respondidas de acordo com regras pré estabelecidas e retornam dados fictícios, com o intuito exclusivo de simular o ambiente de produção para auxiliar o cliente no momento da integração.
Para a análise de uma operação de crédito, no ambiente de Sandbox, a decisão é aplicada sobre o valor total do crédito ( financial.amount ) a ser concedido, de acordo com a tabela abaixo:
Mínimo | Máximo | Decisão
------ | ------ | -------
10001 | - | Reprovado
8001 | 10000 | Análise Manual - Um webhook de reprovação manual é enviado após 1 minuto
6001 | 8000 | Análise Manual - Um webhook de aprovação manual é enviado após 1 minuto
4001 | 6000 | Aguardando Dados - Um webhook de aprovação automática é enviado após 1 minuto
2001 | 4000 | Pendente
0 | 2000 | Aprovado
## Somente HTTPS
Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Atenção**
Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::
---
# Análise de Crédito - Pessoa Jurídica
URL: /documentation/caas/credit_analysis/legal_person
Para realizar a análise de crédito de uma pessoa jurídica, utilize o endpoint de Legal Person.
No momento em que uma análise de crédito de pessoa jurídica for realizada, os seguintes dados deverão ser enviados para o nosso servidor.
## Definição do Objeto Legal Person
Request Body
```json
{
"id": "12345678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"legal_name": "QI Tech Tecnologia LTDA",
"trading_name": "QI Tech",
"document_number": "35.472.523/0001-15",
"constitution_date": "2019-11-11",
"constitution_type": "llc",
"email": "suporte.caas@qitech.com.br",
"monthly_revenue": 50000000,
"client_category": "Premium User",
"client_since": "2021-02-11",
"address": {
"country": "BRA",
"street": "Av. Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"uf": "SP",
"postal_code": "01452-905"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "32234611",
"type": "residential"
}
],
"shareholders": [
{
"name": "Anna Pinto Azevedo",
"document_number": "261.026.462-31",
"birthdate": "1972-08-22",
"email": "annapintoazevedo@sample.com",
"nationality": "BRA",
"mother_name": "Beatrice Rodrigues Pinto",
"father_name": "Luís Azevedo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Derviche Djouki",
"number": "598",
"complement": "Ap 857",
"neighborhood": "Chora Menino",
"city": "São Paulo",
"uf": "SP",
"postal_code": "02463-080"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "55988644",
"type": "mobile"
}
]
}
],
"guarantors": [
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"uf": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
],
"financial": {
"amount": 100000,
"currency": "BRL",
"interest_type": "cdi_plus",
"annual_interest_rate": 2.32,
"cdi_percentage": 100,
"number_of_installments": 4
},
"warrants": [
{
"warrant_type": "real_estate",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
],
"source": {
"channel": "website",
"ip": "132.23.161.75",
"session_id": "2bb684f9-6c00-4993-bcd7-18b9eccd7c9d"
},
"scr_parameters" : {
...
}
}
```
Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.
Os objetos utilizados na composição do objeto CreditProposal e não definidos nesta seção estão disponíveis na seção [Objetos Compartilhados](#objetos-compartilhados).
| nome | tipo | descrição |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string | Identificador da proposta de crédito no seu sistema.
**É essencial que este número seja único para cada processo de análise de crédito** |
|registration_id | string | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro, |
| credit_request_date | datetime | A data e hora quando o crédito foi requisitado pelo tomador |
| credit_type | enum | Tipo de crédito sendo concedido. No momento são suportados: **clean**, **student_loan**, **credit_card_limit** |
| legal_name | string | Razão social |
| trading_name | string | Nome fantasia |
| document_number | string | O CNPJ, formatado conforme padrão estabelecido nesta documentação |
| monthly_revenue | integer | Receita mensal bruta em centavos |
|client_category | string | Categoria do cliente de acordo com a classificação da sua plataforma ou seu programa de fidelidade |
|client_since | date | Data de início da prestação de serviços para este cliente
| constitution_date | data | A data de constituição da companhia, conforme junta comercial |
| constitution_type | enum | O tipo de constituição da empresa: **LLC**, **corp** |
| email | string | O email do representante da empresa |
| address | _Address_ | O endereço da matriz da companhia |
| phones | list of _Phones_ | Os telefones colhidos da companhia |
| shareholders | list of _NaturalPerson_ | Os sócios da companhia, no modelo de pessoa física (Objeto **NaturalPerson**) |
| guarantors | list of _Person_ | Garantidores da operação, Pessoa física (**NaturalPerson**) ou jurídica (**LegalPerson**) |
| financial.amount | integer | O valor total sendo requerido pelo tomador, que será liberado em caso de aprovação |
| financial.currency | enum | A unidade monetária referente ao valor total: **BRL**, **USD**, **EUR** |
| interest_type | enum | O indexador da dívida que será utilizado: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed** |
| annual_interest_rate | number | O valor da parte pré-fixada do juros, em percentual ao ano |
| cdi_percentage | number | O percentual do CDI (Pós) do juros a ser cobrado |
| number_of_installments | integer | Número de parcelas |
| warrants | _Warrant_ | Dados de garantias reais oferecidas na operação. Deverá ser acordada antes da entrada em produçao. Atualmente os seguintes tipos são aceitos: **real_estate** |
| source | _Source_ | O canal de venda do crédito. Atualmente são aceitos: **website** e **app** |
| scr_parameters| _ScrParameters_ | Objeto com as informações necessárias para a utilização das informações do SCR na análise de crédito |
## Enviar uma Proposta de Crédito - Pessoa Jurídica
Request Body
```json
{
"id": "12345678",
...
}
```
Response Body
```json
{
"id": "12345678",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo LegalPerson ao seguinte endpoint:
`POST https://api.caas.qitech.app/credit_analysis/legal_person`
---
# Análise de Crédito - Pessoa Física
URL: /documentation/caas/credit_analysis/natural_person
Para realizar a análise de crédito de uma pessoa física, utilize o endpoint de NaturalPerson.
No momento em que uma análise de crédito de pessoa física for realizada, os seguintes dados abaixo devem ser enviados para o nosso servidor.
## Definição do Objeto Natural Person
Request Body
```json
{
"id": "12345678",
"registration_id":"444",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
"birthdate": "1990-01-01",
"email": "exemplo@sample.com",
"nationality": "BRA",
"gender": "male",
"mother_name": "Ana Barbosa",
"father_name": "João Silva",
"monthly_income": 30000,
"declared_assets": 7500000,
"occupation": "pedagogy",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "32234611",
"type": "residential"
}
],
"guarantors": [
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"uf": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
],
"financial": {
"amount": 100000,
"currency": "BRL",
"interest_type": "cdi_plus",
"annual_interest_rate": 2.32,
"cdi_percentage": 100,
"number_of_installments": 4
},
"warrants": [
{
"warrant_type": "real_estate",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
],
"source": {
"channel": "website",
"ip": "145.25.145.32",
"session_id": "bec256b3-5265-4dcb-bc55-2e4fb43983e0"
},
"scr_parameters" : {
...
}
}
```
Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.
Os objetos utilizados na composição do objeto **CreditProposal** e não definidos nesta seção estão disponíveis na seção [Objetos Compartilhados](#objetos-compartilhados).
| nome | tipo | descrição |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string | Identificador da proposta de crédito no seu sistema.
**É essencial que este número seja único para cada processo de análise de crédito** *(obrigatório)*|
|registration_id | string | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro|
| credit_request_date | datetime | A data e hora quando o crédito foi requisitado pelo tomador *(obrigatório)*|
| credit_type | enum | Tipo de crédito sendo concedido. No momento são suportados: **clean**, **student_loan**, **credit_card_limit** |
| name | string | Nome completo do indivíduo sendo cadastrado |
| document_number | string | CPF do indivíduo sendo cadastrado, com pontos e hífens, de acordo com a padronização *(obrigatório)* |
| birthdate | date | Data de nascimento do indivíduo de acordo com a padronização
| gender | enum | Gênero do indivíduo: 'male', 'female' ou 'undefined'
| nationality | string | A nacionalidade do cadastro, em ISO 3166-1 alfa-3
| mother_name | string | Nome completo da mãe
| father_name | string | Nome completo do pai
| monthly_income | integer | Renda mensal bruta em centavos
| declared_assets | integer | Patrimônio declarado em centavos
|client_category | string | Categoria do cliente de acordo com a classificação da sua plataforma ou seu programa de fidelidade
|client_since | date | Data de início da prestação de serviços para este cliente
| occupation | string | Profissão do indivíduo sendo cadastrado
| email | string | O email da pessoa
| documents | Document | Objetos do tipo CNH e RG
| address | _Address_ | Objeto do tipo Address que descreve o endereço da moradia do indivíduo
| phones | Lista de _Phones_ | Lista de objetos do tipo phone que possui a lista de telefones do indivíduo
| guarantors | list of _Person_ | Garantidores da operação, Pessoa física (**NaturalPerson**) ou jurídica (**LegalPerson**) |
| financial.amount | integer | O valor total sendo requerido pelo tomador, que será liberado em caso de aprovação em centavos |
| financial.currency | enum | A unidade monetária referente ao valor total: **BRL**, **USD**, **EUR** |
| interest_type | enum | O indexador da dívida que será utilizado: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed** |
| annual_interest_rate | number | O valor da parte pré-fixada do juros, em percentual ao ano |
| cdi_percentage | number | O percentual do CDI (Pós) do juros a ser cobrado |
| number_of_installments | integer | Número de parcelas |
| warrants | _Warrant_ | Dados de garantias reais oferecidas na operação. Deverá ser acordada antes da entrada em produção. Atualmente os seguintes tipos são aceitos: **real_estate** |
| source | _Source_ | O canal de venda do crédito. Atualmente são aceitos: **website** e **app** |
| scr_parameters| _ScrParameters_ | Objeto com as informações necessárias para a utilização das informações do SCR na análise de crédito |
:::info **Atenção**
A propriedade scr_parameters é obrigatória apenas se o cliente contratou e deseja utilizar a consulta SCR na análise de crédito.
:::
## Enviar uma Proposta de Crédito - Pessoa Física
Request Body
```json
{
"id": "12345678",
...
}
```
Response Body
```json
{
"id": "12345678",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo **NaturalPerson** ao seguinte endpoint:
`POST https://api.caas.qitech.app/credit_analysis/natural_person`
---
# Objetos Compartilhados
URL: /documentation/caas/credit_analysis/objects
Abaixo as definições de outros objetos utilizados ao longo da documentação.
## Objeto _Address_
Request Body
```json
{
"street": "Rua do Exemplo",
"number": "111" ,
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "Apt 903",
"postal_code": "00000-000"
}
```
O objeto _Address_ é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:
| nome | tipo | descrição |
| ------------ | :----: | -------------------------------------------------------------------------------------------- |
| street | string | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações *(obrigatório)*. |
| number | string | Número do imóvel, incluindo letras caso possua *(obrigatório)*. |
| neighborhood | string | Bairro, sem abreviações *(obrigatório)*.
**e.g.: Santa Felicidade** |
| city | string | Nome completo da cidade, sem abreviações *(obrigatório)*. |
| uf | string | A unidade federativa, com duas letras maiúsculas *(obrigatório)*.
**e.g.: SP** |
| complement | string | Quaisquer complementos para localizar o imóvel.
**e.g.: Apartamento 101, Conjunto 12** |
| postal_code | string | O código postal da localidade, contendo o hífen *(obrigatório)*. |
| country | string | Código ISO 3166-1 alfa-3 do país do endereço *(obrigatório)*. |
No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.
## Objeto _Phone_
Request Body
```json
{
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile"
}
```
Um objeto _Phone_ representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:
| nome | tipo | descrição |
| ----------------------- | :----: | ---------------------------------------------------------------- |
| international_dial_code | string | Código de discagem internacional, sem zero ou +, somente números *(obrigatório)*. |
| area_code | string | Código de área, sem zero, somente números *(obrigatório)*. |
| number | string | Número do telefone, sem o hífen *(obrigatório)*. |
| type | enum | Tipo de número: celular, residencial, comercial, etc. |
Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial`, `mobile`
## Objeto _cnh_
Request Body
```json
{
"register_number": "05163811694",
"issuer_state": "PR",
"first_issuance_date":"2011-03-21",
"issuance_date":"2016-06-29",
"expiration_date":"2021-06-25",
"category": "AB",
"validation_type":"zaig_sdk",
"ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```
O objeto *cnh* é utilizado para representar as CNHs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:
nome | tipo | descrição
---- | :----: | ---------
register_number | string | Número do registro da CNH cadastrada.
issuer_state | enum | Enumerador do estado onde a CNH foi emitida
first_issuance_date | date | Data de primeira habilitação.
issuance_date | date | Data de emissão
expiration_date | date | Data de vencimento
category | enum | Categoria da CNH em letras maiúsculas
validation_type | enum | Tipo de validação utilizada durante o cadastro do documento.
ocr_key | guid | Id retornado pela API de [validação de documento da QI Tech](https://docs.zaig.com.br/ocr/#introducao).
Existem os seguintes enumeradores para *validation_type*: `zaig_api` e `zaig_sdk`.
## Objeto _rg_
Request Body
```json
{
"number": "4.366.477-8",
"issuer": "II",
"issuer_state": "PR",
"issuance_date":"2002-01-12",
"validation_type":"zaig_sdk",
"ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
"ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```
O objeto *rg* é utilizado para representar os RGs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:
nome | tipo | descrição
---- | :----: | ---------
number | string | Número do documento cadastrado, incluindo formatação (Pontos, Hífens, Barras e outros).
issuer | string | Órgão emissor do documento (Sigla, e.g.: II, SESP...)
issuer_state | enum | UF emissor do documento.
issuance_date | date | Data de emissão do documento.
validation_type | enum | Tipo de validação utilizada durante o cadastro do documento.
ocr_key | guid | Id retornado pela API de validação de documento da QI Tech.
Existem os seguintes enumeradores para *validation_type*: `zaig_api` e `zaig_sdk`.
## Objeto _NaturalPerson_
Request Body
```json
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"gender": "female",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"state": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
```
O objeto _NaturalPerson_ representa os dados de uma pessoa que pode ser o próprio tomador, um garantidor ou um sócio de uma empresa tomadora. Ele é composto por:
| nome | tipo | descrição |
| ---------------- | :--------------: | ---------------------------------------------------------------------------------------------- |
| name | string | Nome completo *(obrigatório)*. |
| document_number | string | O CPF, formatado adequadamente *(obrigatório)*. |
| birthdate | date | A data de nascimento da pessoa. |
| email | string | O email da pessoa. |
| gender | enum | O gênero da pessoa, de acordo com a lista de enumeradores. |
| address | _Address_ | O endereço residencial da pessoa. |
| phones | list of _Phone_ | Os telefones colhidos da pessoa. |
Enumeradores de gênero:
- `male`
- `female`
- `undefined`
## Objeto _LegalPerson_
Request Body
```json
{
"legal_name": "QI Tech Tecnologia LTDA",
"trading_name": "QI Tech",
"document_number": "35.472.523/0001-15",
"constitution_date": "1990-01-01",
"constitution_type": "llc",
"email": "exemplo@sample.com",
"address": { ... },
"phones": [ { ... } ],
"shareholders": [ { ... }]
}
```
O objeto _LegalPerson_ representa os dados de uma empresa que está tomando crédito ou garantindo o crédito (Fiador). Ele é composto por:
| nome | tipo | descrição |
| ----------------- | :---------------------: | ------------------------------------------------------------------------------ |
| legal_name | string | Razão social *(obrigatório)*. |
| trading_name | string | Nome fantasia |
| document_number | string | O CNPJ, formatado conforme padrão estabelecido nesta documentação *(obrigatório)*. |
| constitution_date | data | A data de constituição da companhia, conforme junta comercial |
| constitution_type | enumerador | O tipo de constituição da empresa: **LLC**, **corp** |
| email | string | O email do representante da empresa |
| address | _Address_ | O endereço da matriz da companhia |
| phones | list of _Phone_ | Os telefones colhidos da companhia |
| shareholders | list of _NaturalPerson_ | Os sócios da companhia, no modelo de pessoa física (Objeto **NaturalPerson**) |
## Objeto _Source_
Request Body: Pedidos de crédito realizados por meio do site próprio
```json
{
"channel": "website",
"ip": "201.81.161.86",
"session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```
Request Body: Pedidos de crédito realizados por meio de aplicativo próprio
```json
{
"channel": "app",
"platform": "android",
"ip": "201.81.161.86",
"session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```
O objeto source representa o local onde o pedido de crédito foi realizado.
Atenção, caso o canal de venda desejado não se enquadre em nenhuma destas categorias, entrar em contato com a equipe de suporte
## Objeto _Warrant_
> Para análises de crédito que possuam algum tipo de garantia, o objeto warrant pode ser utilizado para informá-lo à nossa API. No momento, somente garantias de imóvel são aceitas e caso seja necessário outro tipo de garantia, basta entrar em contato com o nosso suporte
Request Body
```json
{
"warrant_type": "real_estate",
"address": { ... },
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
```
Para a garantia do tipo **real_estate**, o objeto é formado pelos seguintes campos:
| nome | tipo | descrição |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| warrant_type | enum | Define o tipo de garantia. No momento somente **real_estate** está implementado. |
| address | _Address_ | Objeto do tipo Address que identifica o imóvel dado como garantia |
| property_type | enum | O tipo de imóvel em questão, no momento estão disponíveis: **house**, **commercial_building**, **office**, **appartment** |
| estimated_value | integer | O valor estimado do imóvel |
| forced_selling_value | integer | O valor de venda forçada estimado do imóvel |
Atenção, caso a garantia desejada não se enquadre em nenhuma destas categorias, entrar em contato com a equipe de suporte
## Objeto _ScrParameters_
Request Body
```json
{
"scr_parameters": {
"signers": [
{
"document_number": "111.222.333-44",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
],
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque
et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
| nome | tipo | descrição |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| signers | Lista de _Signer_ | Lista de pessoas que vão assinar ou assinaram a autorização de consentimento para consulta SCR. Este objeto só deve ser enviado no caso de análises de crédito de pessoas jurídicas. |
| signature_evidence | _SignatureEvidence_ | Objeto que para envio das informações coletadas no momento da autorização de consentimento quando a autorização é solicitada na plataforma do cliente. |
## Objeto *Signer*
Request Body
```json
{
"document_number": "111.222.333-44",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
```
| nome | tipo | descrição |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| document_number | string | Número do documento do assinante. |
| name | string | Nome do assinante. |
| email | string | Email do assinante. |
| phone | _Phone_ | Telefone do assinante. |
## Objeto *Signature_Evidence*
Request Body
```json
{
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque
et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
```
| nome | tipo | descrição |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| ip_address | string | IP do assinante |
| session_id | string | Identificador de sessão do usuário na sua plataforma, deve ser algum identificador que permita solicitar auditoria de um OptIn feito na sua plataforma através deste identificador. |
| access_token | string | Identificador do usuário logado na sua plataforma, deve ser possível solicitar auditoria de cadastro deste usuário através deste identificador. |
| additional_data | objeto | Objeto JSON configurável para acomodar informações adicionais que o parceiro julgar relevantes que adicionem fidelidade/credibilidade/autent icidade na assinatura realizada dentro de sua plataforma. |
| signed_term | _SignedTerm_ | Objeto que traz informações sobre o termo que está sendo utilizado para coleta de consentimento. |
## Objeto *SignedTerm*
Request Body
```json
{
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
```
| nome | tipo | descrição |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| raw_text | string | Texto plano do termo que está sendo assinado. |
---
# Dados Sistema de Informações de Créditos (SCR - BACEN)
URL: /documentation/caas/credit_analysis/scr
Caso o cliente contrate, temos a opção da utilização dos dados disponíveis no SCR da pessoa física ou jurídica no momento da análise de crédito. Para utilização dos dados do SCR, é primordial que o consentimento do consultado seja coletado. Esse consentimento pode ser coletado pela QI Tech ou pelo próprio cliente e isso influencia no fluxo de consentimento, bem como nos dados que devem ser enviados para a API, conforme abaixo:
**1. Coleta de consentimento via QI Tech -** Caso opte pela coleta do consentimento via QI Tech, um link para assinatura eletrônica é enviado diretamente, via e-mail, da QI Tech para o usuário consultado e, quando o usuário assina o link e finaliza o processo, a informação do SCR automaticamente torna-se disponível para uso. Para utilização deste fluxo, é necessário que, na integração, sejam enviados os dados do usuário final que irá assinar o termo de consentimento.
**2. Coleta do consentimento pelo próprio cliente -** É possível coletar a assinatura do termo de consentimento em seu próprio ambiente ou esteira de crédito (pode ser feito por documento assinado ou opt-in box do termo). Para que isso seja possível, o termo de consentimento utilizado deve ser validado pelo time jurídico da QI Tech e se faz necessário o envio de informações que comprovem de maneira auditável que o consentimento para acesso à informação de SCR foi coletado através do objeto *scr_parameters*.
Atenção, ambas configurações de acesso as informações de SCR, incluindo qual fluxo será utilizado, devem ser acordadas durante contratação do produto para que a funcionalidade esteja disponível para uso.
## Coleta do Consentimento via QI Tech - Pessoa Física
No caso de uma pessoa física, para que a QI Tech envie o pedido de consentimento, basta o preenchimento dos dados pessoais do consultado no objeto de CreditProposal . Com isso, a QI Tech irá enviar o pedido de consentimento ao consultado via e-mail e, automaticamente, realizar a consulta (após autorizaçao), disponibilizando os resultados para análise de crédito.
É obrigatório o envio dos campos _document_number_ , name , email e do objeto phone para coleta do consentimento de pessoa física via QI Tech.
## Coleta do Consentimento via QI Tech - Pessoa Jurídica
Request Body
```json
{
"id": "32199d0s",
"legal_name": "QI CAAS LTDA",
"trading_name": "QI Tech",
...
"scr_parameters": {
"signers": [
{
"document_number": "372.989.950-30",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
},
{
"document_number": "440.896.050-08",
"name": "Claudio Mattos",
"email": "claudiomattos@sample.com",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
]
}
}
```
No caso de uma pessoa jurídica, para que a QI Tech envie o pedido de consentimento, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, será necessário adicionar a lista de responsáveis legais da empresa para os quais serão enviados os pedidos de assinatura eletrônica via e-mail. Essa lista deve ser enviada dentro da propriedade signers . Após a assinatura de todos os representantes legais, a QI Tech realizará a consulta, disponibilizando os resultados para análise de crédito. Acima temos um exemplo do objeto scr_parameters para o caso descrito.
## Coleta do Consentimento pelo Próprio Cliente - Pessoa Física
Request Body
```json
{
"id": "678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
"scr_parameters": {
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
No caso de uma pessoa física, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta. Essas informações devem ser enviadas dentro da propriedade signature_evidence . Acima temos um exemplo do objeto scr_parameters para o caso descrito.
## Coleta do Consentimento pelo Próprio Cliente - Pessoa Jurídica
Request Body
```json
{
"id": "678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
"scr_parameters": {
"signers": [
{
"document_number": "372.989.950-30",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
},
{
"document_number": "440.896.050-08",
"name": "Claudio Mattos",
"email": "claudiomattos@sample.com",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
],
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
No caso de uma pessoa jurídica, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta, bem como adicionar a lista de responsáveis legais da empresa que autorizaram a consulta. As informações de autorização deverão ser enviadas dentro da propriedade signature_evidence e a lista de pssoas que autorizaram a consulta dentro da propriedade signers . Acima temos um exemplo do objeto scr_parameters para o caso descrito.
---
# Padrões
URL: /documentation/caas/credit_analysis/standards
Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.
## Valores Monetários
> Exemplos:
```
10000
12345
98741
1223
1
0
```
As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.
## Data e Hora com Fuso Horário
> Alguns exemplos:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.
A máscara utilizada para validação é a seguinte:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Data e Hora sem Fuso Horario
> Alguns exemplos:
```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```
É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:
`YYYY-MM-ddThh:mm:ssZ`
## Data
> Alguns exemplos
```
2019-10-15
2019-01-01
2017-03-20
```
No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:
`YYYY-MM-dd`
## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.
## CPF
> Exemplos de CPFs válidos contra a máscara definida:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Exemplos de CPFs inválidos contra a máscara definida:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
O CPF é sempre definido como uma string e será validado conta a máscara:
`###.###.###-##`
## CNPJ
> Exemplos de CNPJs válidos contra a máscara definida:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Exemplos de CNPJs inválidos contra a máscara definida:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
O CNPJ é sempre definido como uma string e será validado conta a máscara:
`##.###.###/####-##`
## IP
> Exemplos de IPs válidos contra a máscara definida:
```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```
> Exemplos de IPs inválidos:
```
201.81..86
358.81.161.86
201.81.161
```
IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:
`###.###.###.###`
---
# Dinâmica dos Status
URL: /documentation/caas/credit_analysis/status_dynamics
O processo de análise de crédito consiste em enviar uma requisição, tanto de **NaturalPerson** como de **LegalPerson** no respectivo endpoint e esperar a resposta.
Após a QI Tech realizar a análise de crédito, ela retornará uma resposta com um status referente a análise. Esse status tem o nome de **analysis_status**, que representa o resultado da analise de crédito realizado pela QI Tech.
Além do **analysis_status** a QI Tech também possui o **credit_proposal_status** que tem como objetivo representar o status do crédito analisado em cada momento de sua vida na sua plataforma.
## **analysis_status**
Conforme descrito anteriormente, a QI Tech possui sete **analysis_status** que indicam o status da decisão da análise de crédito e possui uma máquina de estados bastante simples:
analysis_status | Descrição
:---------: | ---------
automatically_approved | Os algoritmos da QI Tech recomendam que este cadastro seja aprovado
automatically_reproved | Os algoritmos da QI Tech recomendam que este cadastro seja reprovado
in_manual_analysis | Os algoritmos da QI Tech enviaram este cadastro para a análise manual
manually_approved | Após análise manual, o analista decidiu aprovar o cadastro
manually_reproved | Após análise manual, o analista decidiu reprovar o cadastro
waiting_for_data | A análise de crédito está aguardado o retorno de alguma informação de bureau ou provedor de dados e será respondido por meio de Webhook
automatically_challenged | Os algoritmos da QI Tech recomendam que este cadastro seja desafiado
manually_challenged | Após análise manual, o analista decidiu desafiar o cadastro
pending | A análise de crédito está demorando mais do que o esperado, este cadastro entrou em uma fila de análise automática e será respondido por meio de Webhook
:::info **Atenção**
Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::
## **credit_proposal_status**
O **credit_proposal_status** indica o status da operação do cliente, ou seja, o status da proposta de crédito na sua empresa ou plataforma. Os seguintes enumeradores existem para este status:
credit_proposal_status | Descrição
:---------: | ---------
created | A proposta de crédito foi criada na sua plataforma
disbursed | O proposta de crédito foi desembolsada na sua plataforma
paid | O cliente realizou o pagamento integral do crédito
defaulted | O cliente está inadimplente na sua plataforma
---
# Atualizar o status de uma Análise de Crédito
URL: /documentation/caas/credit_analysis/update_credit_analysis
Request Body: Para marcar o crédito como concedido
```json
{
"credit_proposal_status": "disbursed",
"event_date": "2021-11-05T13:34:12-03:00"
}
```
Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as operações são efetivadas. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:
* **Natural Person:**
`PUT https://api.caas.qitech.app/credit_analysis/natural_person/12345678`
* **Legal Person:**
`PUT https://api.caas.qitech.app/credit_analysis/legal_person/12345678`
---
# Webhook
URL: /documentation/caas/credit_analysis/webhook
Atualizações no status (Para cadastros que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também um *secret_token* que será utilizado para assinar a requisição.
O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling.
## Assinatura
> Exemplo de cálculo de assinatura em Python
```python
hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
return hmac_obj.hexdigest()
```
Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação.
Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.
## Requisição
```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"natural_person_id": "538509", "analysis_status": "manually_approved", "event_date": "2024-11-13T17:52:50Z", "reason": "manually_approved"}'
```
A requisição possui o formato acima e notifica a mudança no status. É importante ressaltar que a requisição utiliza o verbo HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.
## Retentativas
A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:
* 30 segundos
* 60 segundos
* 120 segundos
* 240 segundos
* 360 segundos