# QI Tech — Risk Solutions › Análise cadastral

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
12 página(s).

Índice:
- Autenticação (/documentation/caas/onboarding/authentication)
- Status HTTP (/documentation/caas/onboarding/http_status)
- Integrações (/documentation/caas/onboarding/integrations)
- Introdução (/documentation/caas/onboarding/introduction)
- Objeto Legal Person (/documentation/caas/onboarding/legal_person)
- Objeto Natural Person (/documentation/caas/onboarding/natural_person)
- Objetos Compartilhados (/documentation/caas/onboarding/objects)
- Recuperar um Cadastro (/documentation/caas/onboarding/query_registration)
- Padrões (/documentation/caas/onboarding/standards)
- Dinâmica dos Status (/documentation/caas/onboarding/status_dynamics)
- Atualizar um Cadastro (/documentation/caas/onboarding/update_registration)
- Webhook (/documentation/caas/onboarding/webhook)

---

# Autenticação

URL: /documentation/caas/onboarding/authentication

> 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' pela sua chave, que deve ser obtida através do nosso time de 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 pela sua chave, que deve ser obtida através do nosso time de suporte.
:::

---

# Status HTTP

URL: /documentation/caas/onboarding/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.

---

# Integrações

URL: /documentation/caas/onboarding/integrations

Nossas soluções mobile são compatíveis com as mais diversas tecnologias como Flutter, Ionic Cordova, Capacitor, React Native, Java, Swift entre outras. Caso tenha interesse em alguma dessas integrações, entre em contato com nosso suporte para liberarmos acesso aos nossos repositórios privados.

---

# Introdução

URL: /documentation/caas/onboarding/introduction

Bem vindo à API de Onboarding da QI Tech! Esta API dá acesso aos serviços de Prevenção a Fraudes, à lavagem de dinheiro e de KYC em um Cadastro da sua plataforma! 

Esta API pode ser utilizada para a validação cadastral de clientes para:

* Abertura de Contas Digitais ou Wallets
* Emissão de Cartão
* Validação de Usuários de Aplicativos
* Cadastro para Concessão de Crédito
* Cadastro para Contratação de Seguros
* Validação de Dados Cadastrais

Você pode utilizar a nossa API para acessar os endpoints para avaliar os seguintes tipos de Cadastro:

* **Natural Person** - utilizado para validação cadastral de Pessoas Físicas
* **Legal Person** - utilizado para validação cadastral de Pessoas Jurídicas

Os diferentes tipos de Cadastro acima possuem objetos e endpoints específicos com o intuito de cobrir as particularidades de cada entidade. 

## 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á notou), 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/onboarding/`
* Sandbox - `https://api.sandbox.caas.qitech.app/onboarding/`

:::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 e são respondidas de acordo com a seguinte regra baseada no primeiro dígito do documento - CPF para Pessoas Físicas e CNPJ para Pessoas Jurídicas:

Dígito | Decisão
------ | -------
0 | Em Análise Manual
1 | Em Análise Manual
2 | Em Análise Manual
3 | Em Análise Manual
4 | Contestado Automaticamente
5 | Derivado para Análise Manual - Com reprovação posterior
6 | Derivado para Análise Manual - Com aprovação posterior
7 | Pendente
8 | Reprovado Automaticamente
9 | Aprovado Automaticamente

Nos casos de CPF ou CNPJ com início nos dígitos 1 ou 2, deve-se entrar em contato com nosso suporte para que a tratativa manual seja feita corretamente.

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

---

# Objeto Legal Person

URL: /documentation/caas/onboarding/legal_person

Ao final do cadastro de uma empresa em sua plataforma, é necessário executar a avaliação de fraude e de KYC desta companhia, o que deve ser realizado através do endpoint de Legal Person. Os dados enviados deverão ser os dados finais, que não serão alterados em hipótese alguma, isto é, não deverá existir a possibilidade de após este processo se realizar uma alteração nos dados básicos de cadastro como CNPJ, Razão Social, Data de Constituição e outros. Isto é muito importante para garantir dois pontos:

* Consistência dos dados na base de dados do Antifraude
* Avaliação realista do risco, evitando fraudes em momentos posteriores da operação

## Definição do Objeto Legal Person

Request Body

```json
{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "client_category" : "Premium Account",
  "legal_name": "John's Company",
  "trading_name": "John's Barbershop",
  "document_number": "11.111.111/0001-11",
  "foundation_date": "1992-09-15",
  "website": "www.johnsbarbershop.com.br",
  "activity": "Barber Shops",
  "activity_code": "96.02-5-01",
  "merchant_category_code": "0742",
  "tier" : "epp",
  "annual_revenues": 72000000,
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "ccc4b4b4-f91c-4475-8290-07152550aefc"
    }
  ],
  "documents": {
    "ie": {
      "number": "388.108.598.269",
      "issuer": "JUCESP",
      "issuer_state": "SP",
      "issuance_date":"2002-01-12",
      "validation_type": "zaig_api",
      "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
    },
    "company_statute": {
      "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
    }
  },
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Bairro do Exemplo",
    "city": "Aparecida de Goiânia",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000",
    "country": "BRA",
    "validation_type": "visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82473dec-8e14-4570-997a-59652818c908"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip":"201.6.142.66",
    "session_id": "c90ad2df-7307-4f82-8938-1da81dff2be6"
  },
  "legal_representatives": [
    {
      "name": "Frederic Attorney",
      "document_number": "111.111.111-11",
      "birthdate": "1987-06-12",
      "gender": "male",
      "nationality": "BRA",
      "mother_name": "Jackie Attorney Mother",
      "occupation": "Accountant",
      "emails":[
        {
          "email": "frederic@attorney.com",
          "validation_type":"zaig_api",
          "validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
        }
      ],
      "documents": {
        "letter_of_attorney": {
          "ocr_key": "6972894d-d2ef-4b5f-b54f-10f178bf3e5d"
        },
        "cnh": {
          "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"
        }
      },
      "address": {
        "street": "Avenida de Exemplo",
        "number": "99",
        "neighborhood": "Vila do Exemplo",
        "city": "Jundiaí",
        "uf": "SP",
        "complement": "Ap 82",
        "postal_code": "00000-000",
        "country": "BRA",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "999998877",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
        }
      ],
      "source": {
        "channel": "app",
        "platform": "ios",
        "ip":"175.92.122.2",
        "session_id": "93c68588-7a41-472f-95b3-835ea6ee1ede"
      },
      "face":
      {
        "type":"zaig_sdk",
        "registration_key":"d2677a8c-d575-44e1-a54d-ec00f9310f34"
      }
    }
  ],
  "partners": [
    {
      "name": "John Partner",
      "document_number": "111.111.111-11",
      "birthdate": "1992-09-15",
      "gender": "male",
      "nationality": "BRA",
      "mother_name": "Maria Partner's Mother",
      "occupation": "Teacher",
      "emails":[
        {
          "email": "johnsample@test.com",
          "validation_type":"zaig_api",
          "validation_key": "1fac6f8c-1a16-4a12-9afc-9a2d9ae0a31e"
        }
      ],
      "documents": {
        "rg": {
          "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"
        },
        "cnh": {
          "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"
        }
      },
      "address": {
        "street": "Rua do Teste",
        "number": "111",
        "neighborhood": "Bairro do Exemplo",
        "city": "Aparecida de Goiânia",
        "uf": "GO",
        "complement": "Térreo",
        "postal_code": "00000-000",
        "country": "BRA",
        "validation_type":"visit",
        "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
      },
      "phones": [
        {
          "international_dial_code": "1",
          "area_code": "11",
          "number": "999999999",
          "type": "mobile",
          "validation_type": "zaig_sms",
          "validation_key": "d1713959-4ae4-4180-befc-6931c658e908"
        }
      ],
      "source": {
        "channel": "app",
        "platform": "android",
        "ip":"255.201.26.1",
        "session_id": "79d5e442-2cb7-4a9e-82c5-7fa3717d7ada"
      },
      "face":
      {
        "type":"zaig_sdk",
        "registration_key":"a2b6ae92-1394-4f9b-b8ee-5be188f93609"
      }
    }
  ]
}
```

Todas as trocas de informação de um cadastro 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 | restrições | descrição
:----: | :----: | :----: | ---------
id | string | 1–50 caracteres | Identificador da análise. **É essencial que este número seja único para cada requisição** *(obrigatório)*
registration_id | string | 1–50 caracteres | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro, utilize o mesmo _registration_id_ nas diferentes análises. Terá o mesmo valor do _id_ quando não enviado.
registration_date | datetime | ISO 8601 com fuso horário | Data e hora do cadastro. Formato: `YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` ou `...Z`. Exemplo: `2019-12-11T11:37:15.12-03:00` *(obrigatório)*
client_category | string | 1–100 caracteres | Categoria do cliente de acordo com a classificação da sua plataforma ou programa de fidelidade
legal_name | string | 1–1000 caracteres | Razão Social da empresa sendo cadastrada
trading_name | string | 1–1000 caracteres | Nome fantasia da empresa sendo cadastrada
document_number | string | Formato `XX.XXX.XXX/XXXX-XX` | CNPJ da empresa. Deve conter exatamente 18 caracteres, incluindo pontos, barra e hífen *(obrigatório)*
foundation_date | date | Formato `YYYY-MM-DD` | Data de fundação da empresa
website | string | até 10.000 caracteres | Website da empresa sendo cadastrada
activity | string | 1–1000 caracteres | Ramo de atividade da empresa sendo cadastrada
activity_code | string | Formato `XX.XX-X-XX` | Código CNAE da atividade da empresa. Deve conter exatamente 10 caracteres. Exemplo: `96.02-5-01`
merchant_category_code | string | enum (ver lista abaixo) | Código MCC (Merchant Category Code) para o ramo de atividade, conforme padrão das bandeiras de cartões
tier | string | 1–10 caracteres | Porte da empresa (ex.: `mei`, `epp`, `me`, `medio`, `grande`)
annual_revenues | integer | 0 a 10.000.000.000.000 | Receita bruta anual da empresa em **centavos** de reais
monthly_revenues | integer | 0 a 10.000.000.000.000 | Receita bruta mensal da empresa em **centavos** de reais
emails | Lista de Email | — | Lista de objetos do tipo Email com os endereços de e-mail da empresa
documents | Document | — | Objetos dos tipos Inscrição Estadual (`ie`) e Contrato Social (`company_statute`)
address | Address | — | Objeto do tipo Address com o endereço da empresa
phones | Lista de Phone | — | Lista de objetos do tipo Phone com os telefones da empresa
source | Source | — | Objeto do tipo Source com informações da aplicação utilizada para envio do cadastro
partners | Lista de Partner | — | Lista de objetos do tipo Partner com informações de cada sócio da empresa
legal_representatives | Lista de LegalRepresentative | — | Lista de objetos do tipo LegalRepresentative com informações de cada representante legal da empresa

### Formatos de Campo

#### `registration_date`

Deve seguir o formato ISO 8601 com fuso horário obrigatório. Exemplos de valores aceitos:

```
2019-12-11T11:37:15-03:00        (sem fração de segundos, offset)
2019-12-11T11:37:15.123456-03:00 (com fração de segundos, até 6 dígitos)
2019-12-11T14:37:15Z             (UTC)
```

> O campo **não aceita** datas sem o componente de fuso horário (ex.: `2019-12-11T11:37:15` é inválido).

#### `document_number` — CNPJ

O CNPJ deve ser enviado **com pontuação**, no formato `XX.XXX.XXX/XXXX-XX`, onde cada `X` é um dígito numérico. O campo possui exatamente **18 caracteres**.

Exemplo válido: `11.222.333/0001-81`

#### `foundation_date`

Data no formato `YYYY-MM-DD` (ano-mês-dia), conforme ISO 8601.

Exemplo válido: `1992-09-15`

#### `activity_code` — CNAE

O código CNAE deve ser enviado no formato `XX.XX-X-XX`, com exatamente **10 caracteres** incluindo os separadores.

Exemplo válido: `96.02-5-01`

#### `annual_revenues` e `monthly_revenues`

Ambos os campos são inteiros que representam valores monetários em **centavos de reais**. Para converter de reais para o formato esperado, multiplique por 100.

Exemplo: R$ 720.000,00 → `72000000`

## Enviar um Legal Person

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de um Cadastro, basta enviar um objeto do tipo Legal Person ao seguinte endpoint com a flag setada adequadamente:

`POST https://api.caas.qitech.app/onboarding/legal_person?analyze=true`

O parâmetro *analyze* existe para identificar se o cadastro enviado deve ou não ser analisado pelos algoritmos da QI Tech. Caso um cadastro seja enviado com o parâmetro com o valor **false**, ele não será analisado nem cobrando, mas seus dados serão considerados pelos algoritmos da QI Tech para uma análise futura. O valor padrão deste parâmetro é **true**, de maneira que somente cadastros que forem explicitamente enviados com a flag **false** não serão analisados.

---

# Objeto Natural Person

URL: /documentation/caas/onboarding/natural_person

Ao final do cadastro de uma pessoa física em sua plataforma, é necessário executar a avaliação de fraude e de KYC deste cliente, o que deve ser realizado através do endpoint de Natural Person. Os dados enviados deverão ser os dados finais, que não serão alterados em hipótese alguma, isto é, não deverá existir a possibilidade de se realizar uma alteração nos dados básicos de cadastro como CPF, Nome, Data de Nascimento e outros após este processo. Isto é muito importante para garantir dois pontos:

* Consistência dos dados na base de dados do Antifraude
* Avaliação realista do risco, evitando fraudes em momentos posteriores da operação

## Definição do Objeto Natural Person

Request Body

```json
{
  "id": "12345678",
  "registration_id": "12345678",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "client_category": "Premium User",
  "name": "John Sample",
  "document_number": "111.111.111-11",
  "birthdate": "1992-09-15",
  "gender": "male",
  "nationality": "BRA",
  "mother_name": "Maria Sample",
  "father_name": "John Sample",
  "monthly_income": 500000,
  "declared_assets": 7500000,
  "occupation": "Teacher",
  "emails":[
    {
      "email": "johnsample@test.com",
      "validation_type":"zaig_api",
      "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
    }
  ],
  "documents": {
    "rg": {
      "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"
    },
    "cnh": {
      "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"
    }
  },
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Bairro do Exemplo",
    "city": "Aparecida de Goiânia",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000",
    "country": "BRA",
    "validation_type":"visit",
    "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
  },
  "phones": [
    {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile",
      "validation_type": "zaig_sms",
      "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip":"255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },
  "face":
  {
    "type":"zaig_sdk",
    "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}
```

Todas as trocas de informação de um cadastro 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 | restrições | descrição
:----: | :----: | :----: | ---------
id | string | 1–50 caracteres | Identificador da análise. **É essencial que este número seja único para cada requisição** *(obrigatório)*
registration_id | string | 1–50 caracteres | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro, utilize o mesmo _registration_id_ nas diferentes análises. Terá o mesmo valor do _id_ quando não enviado.
registration_date | datetime | ISO 8601 com fuso horário | Data e hora do cadastro. Formato: `YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM` ou `...Z`. Exemplo: `2019-12-11T11:37:15.12-03:00` *(obrigatório)*
client_category | string | 1–100 caracteres | Categoria do cliente de acordo com a classificação da sua plataforma ou programa de fidelidade
name | string | 1–500 caracteres | Nome completo do indivíduo sendo cadastrado
document_number | string | Formato `XXX.XXX.XXX-XX` | CPF do indivíduo. Deve conter exatamente 14 caracteres, incluindo pontos e hífen *(obrigatório)*
birthdate | date | Formato `YYYY-MM-DD` | Data de nascimento do indivíduo
gender | enum | `male` ou `female` | Gênero do indivíduo
nationality | string | 3 letras maiúsculas | Nacionalidade em código ISO 3166-1 alfa-3. Exemplo: `BRA`
mother_name | string | 1–500 caracteres | Nome completo da mãe
father_name | string | 1–500 caracteres | Nome completo do pai
monthly_income | integer | 1 a 100.000.000.000 | Renda mensal bruta em **centavos** de reais
declared_assets | integer | 1 a 100.000.000.000.000 | Patrimônio declarado em **centavos** de reais
occupation | string | 1–100 caracteres | Profissão do indivíduo sendo cadastrado
emails | Lista de Email | — | Lista de objetos do tipo Email com os endereços de e-mail do indivíduo
documents | Document | — | Objetos dos tipos CNH, RG e outros documentos de identificação
address | Address | — | Objeto do tipo Address com o endereço de moradia do indivíduo
phones | Lista de Phone | — | Lista de objetos do tipo Phone com os telefones do indivíduo
source | Source | — | Objeto do tipo Source com informações da aplicação utilizada para envio do cadastro
face | Face | — | Objeto do tipo Face com informações da validação facial, caso haja

### Formatos de Campo

#### `registration_date`

Deve seguir o formato ISO 8601 com fuso horário obrigatório. Exemplos de valores aceitos:

```
2019-12-11T11:37:15-03:00        (sem fração de segundos, offset)
2019-12-11T11:37:15.123456-03:00 (com fração de segundos, até 6 dígitos)
2019-12-11T14:37:15Z             (UTC)
```

> O campo **não aceita** datas sem o componente de fuso horário (ex.: `2019-12-11T11:37:15` é inválido).

#### `document_number` — CPF

O CPF deve ser enviado **com pontuação**, no formato `XXX.XXX.XXX-XX`, onde cada `X` é um dígito numérico. O campo possui exatamente **14 caracteres**.

#### `birthdate`

Data no formato `YYYY-MM-DD` (ano-mês-dia), conforme ISO 8601.

Exemplo válido: `1992-09-15`

#### `nationality`

Código de país de 3 letras **maiúsculas**, seguindo o padrão ISO 3166-1 alfa-3.

Exemplos: `BRA` (Brasil), `USA` (Estados Unidos), `ARG` (Argentina).

#### `monthly_income` e `declared_assets`

Ambos os campos são inteiros que representam valores monetários em **centavos de reais**. Para converter de reais para o formato esperado, multiplique por 100.

Exemplo: R$ 5.000,00 → `500000`

## Enviar um Natural Person

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de um Cadastro, basta enviar um objeto do tipo Natural Person ao seguinte endpoint com a flag setada adequadamente:

`POST https://api.caas.qitech.app/onboarding/natural_person?analyze=true`

O parâmetro *analyze* existe para identificar se o cadastro enviado deve ou não ser analisado pelos algoritmos da QI Tech. Caso um cadastro seja enviado com o parâmetro com o valor **false**, ele não será analisado nem cobrando, mas seus dados serão considerados pelos algoritmos da QI Tech para uma análise futura. O valor padrão deste parâmetro é **true**, de maneira que somente cadastros que forem explicitamente enviados com a flag **false** não serão analisados.

---

# Objetos Compartilhados

URL: /documentation/caas/onboarding/objects

Boa parte dos dados são compartilhados entre várias APIs. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

## Objeto *email*

Request Body

```json
{
  "email": "johnsample@test.com",
  "validation_type":"zaig_api",
  "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
}
```

O objeto *email* é utilizado para representar os e-mails 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 | restrições | descrição
---- | :----: | :----: | ---------
email | string | 1–100 caracteres | Endereço de e-mail cadastrado. *(obrigatório)*
validation_type | enum | `zaig_api` ou `company_email` | Tipo de validação utilizada durante o cadastro do e-mail.
validation_key | guid | UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | Id retornado pela API de validação de e-mail da QI Tech.

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

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 *ie*

Request Body

```json
{
  "number": "388.108.598.269",
  "issuer": "JUCESP",
  "issuer_state": "SP",
  "issuance_date":"2002-01-12",
  "validation_type": "zaig_api",
  "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
}
```

O objeto *ie* é utilizado para representar as Inscrições Estaduais dentro do objeto de *documents* no endpoint de *legal_person*, bem como se foi utilizado algum meio de validação do mesmo. Ele é representado 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.: JUCESP, JUCEGO...)
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`.

## Objeto *company_statute*

Request Body

```json
{
  "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
}
```

O objeto *company_statute* é utilizado para representar documentos de constituição de empresas, como por exemplo um Contrato Social dentro do objeto de *documents* no endpoint de *legal_person*. Ele é representado da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
ocr_key | guid | Id retornado pela API de OCR da QI Tech após envio da imagem ou PDF de um documento de constuição de uma empresa.

## Objeto *letter_attorney*

Request Body

```json
{
  "ocr_key": "13571175-b1d9-4507-82e0-d266516fc5ae"
}
```

O objeto *letter_attorney* é utilizado para representar procurações que instituem poderes a representantes legais dentro do objeto de *documents* no endpoint de *legal_person*. Ele é representado da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
ocr_key | guid | Id retornado pela API de OCR da QI Tech após envio da imagem ou PDF de uma procuração.
## Objeto *address*

Request Body

```json
{
  "street": "Rua do Teste",
  "number": "111",
  "neighborhood": "Bairro do Exemplo",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "Térreo",
  "postal_code": "00000-000",
  "country": "BRA",
  "validation_type":"visit",
  "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
}
```

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 | restrições | descrição
---- | :----: | :----: | ---------
street | string | 1–100 caracteres | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações.
number | string | 1–50 caracteres | Número do imóvel, incluindo letras caso possua.
neighborhood | string | 1–100 caracteres | Bairro, sem abreviações. **e.g.: Santa Felicidade**
city | string | 1–100 caracteres | Nome completo da cidade, sem abreviações
uf | enum | sigla UF (2 letras) | A unidade federativa brasileira. **e.g.: SP, GO, MG**
complement | string | 1–500 caracteres | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12**
postal_code | string | Formato `XXXXX-XXX` | CEP brasileiro com hífen, exatamente 9 caracteres. Exemplo: `01310-100` *(obrigatório)*
country | string | 3 letras maiúsculas | Código ISO 3166-1 alfa-3 do país do endereço. Exemplo: `BRA`
validation_type | enum | `visit` ou `zaig_ocr` | Tipo de validação utilizada durante o cadastro do endereço.
ocr_key | guid | UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | Id retornado pela API ou SDK de OCR da QI Tech após o envio da imagem do comprovante de residência.

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",
  "validation_type": "zaig_sms",
  "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
}
```

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 | restrições | descrição
---- | :----: | :----: | ---------
international_dial_code | string | 1–7 caracteres, somente dígitos | Código de discagem internacional, sem zero ou `+`. Exemplo: `55` para Brasil *(obrigatório)*
area_code | string | 1–10 caracteres, somente dígitos | Código de área, sem zero. Exemplo: `11` *(obrigatório)*
number | string | 1–20 caracteres | Número do telefone, sem o hífen *(obrigatório)*
type | enum | `residential`, `commercial` ou `mobile` | Tipo de número telefônico.
validation_type | enum | `zaig_sms`, `zaig_call`, `company_sms` ou `company_call` | Tipo de validação utilizada durante o cadastro do telefone.
validation_key | guid | UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | Id retornado pela API de validação de telefone da QI Tech.

## Objeto *source*

Request Body

```json
  {
    "channel": "app",
    "platform": "android",
    "ip":"211.7.142.62",
    "session_id": "733adf2c-a994-4113-aa59-beb646091fea",
  }
```

Um objeto *source* representa o conjunto de informações da plataforma utilizada pelo cliente para seu cadastramento. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
channel | string | Canal de venda/cadastro do cliente
platform | string | Plataforma utilizada pelo cliente para realizar seu cadastro
ip | string | IP coletado do device que o cliente foi cadastrado
session_id | string | Identificador único da sessão, utilizado para fazer o cruzamento do device scan com o cadastro em questão

## Objeto *face*

Request Body

```json
  {
    "type":"zaig_face_sdk",
    "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
```

Um objeto *face* representa uma validação de reconhecimento facial feita através das APIs ou SDKs da QI Tech por você para verificar a autenticidade do cliente prévio ao envio do cadastro. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
validation_type | enum | Tipo da validação de reconhecimento facial realizada.
registration_key | guid | Identificador que a API ou SDK da QI Tech retornou para identificar aquele registro.
validation_key | guid | Identificador que a API ou SDK da QI Tech retornou para identificar aquela validação.

Existem os seguintes enumeradores para as validações de face: `zaig_api` e `zaig_sdk`.

## Objeto *partner*

Request Body

```json
  {
    "name": "John Partner",
    "document_number": "111.111.111-11",
    "birthdate": "1992-09-15",
    "gender": "male",
    "nationality": "BRA",
    "mother_name": "Maria Partner's Mother",
    "occupation": "Teacher",
    "emails":[
      {
        "email": "johnsample@test.com",
        "validation_type":"zaig_api",
        "validation_key": "e9f0de49-16fb-431e-be1a-ee4bf1096eda"
      }
    ],
    "documents": {
      "rg": {
        "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"
      },
      "cnh": {
        "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"
      }
    },
    "address": {
      "street": "Rua do Teste",
      "number": "111",
      "neighborhood": "Bairro do Exemplo",
      "city": "Aparecida de Goiânia",
      "uf": "GO",
      "complement": "Térreo",
      "postal_code": "00000-000",
      "country": "BRA",
      "validation_type":"visit",
    },
    "phones": [
      {
        "international_dial_code": "1",
        "area_code": "11",
        "number": "999999999",
        "type": "mobile",
        "validation_type": "zaig_sms",
        "validation_key": "82589b39-e34f-44f9-b0fe-d8fc0ee6129c"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "android",
      "ip":"255.321.321.1",
      "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
    },
    "face":
    {
      "type":"zaig_sdk",
      "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
    }
  }
```

Um objeto *partner* representa os dados de um sócio da empresa que está sendo cadastrada, bem como informações referentes às validações que o sócio foi submetido durante seu processo de cadastro. Para isso, os campos são:

nome | tipo | descrição
:----: | :----: | ---------
name | string | Nome completo do sócio sendo cadastrado
document_number | string | CPF do sócio sendo cadastrado, com pontos e hífens, de acordo com a padronização *(obrigatório)*
birthdate | date | Data de nascimento do sócio de acordo com a padronização
gender | enum | Gênero do sócio: 'male' ou 'female'
nationality | string | A nacionalidade do sócio, em ISO 3166-1 alfa-3
mother_name | string | Nome completo da mãe do sócio
occupation | string | Profissão do sócio sendo cadastrado
emails | Email | Lista de objetos do tipo Email que descreve o endereço de e-mail do sócio
documents | Document | Objeto do tipo Document de quaisquer documentos enviados no momento do cadastro do sócio
address | Address | Objeto do tipo Address que descreve o endereço da moradia do sócio
phones | Lista de Phone | Lista de objetos do tipo phone que possui a lista de telefones do sócio
source | Source | Objeto do tipo Source que descreve as características da aplicação utilizada para envio do cadastro
face | Face | Objeto do tipo Face que descreve as informações da validação facial 

## Objeto *legal_representative*

Request Body

```json
  {
    "name": "Frederic Attorney",
    "document_number": "111.111.111-11",
    "birthdate": "1987-06-12",
    "gender": "male",
    "nationality": "BRA",
    "mother_name": "Jackie Attorney Mother",
    "occupation": "Accountant",
    "emails":[
      {
        "email": "frederic@attorney.com",
        "validation_type":"zaig_api",
        "validation_key": "d174d522-6003-4b05-adb2-e92e92632c67"
      }
    ],
    "documents": {
      "letter_of_attorney": {
        "ocr_key": "6972894d-d2ef-4b5f-b54f-10f178bf3e5d"
      },
      "cnh": {
        "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"
      }
    },
    "address": {
      "street": "Avenida de Exemplo",
      "number": "99",
      "neighborhood": "Vila do Exemplo",
      "city": "Jundiaí",
      "uf": "SP",
      "complement": "Ap 82",
      "postal_code": "00000-000",
      "country": "BRA",
      "validation_type":"proof_of_address",
      "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "999998877",
        "type": "mobile",
        "validation_type": "zaig_sms",
        "validation_key": "e390d2b3-cb71-4991-9d94-1b7f8b43a04e"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "ios",
      "ip":"175.92.122.2",
      "session_id": "93c68588-7a41-472f-95b3-835ea6ee1ede"
    },
    "face":
    {
      "type":"zaig_sdk",
      "registration_key":"d2677a8c-d575-44e1-a54d-ec00f9310f34"
    }
  }
```

Um objeto *legal_representative* representa os dados de um representante legal da empresa que está sendo cadastrada, bem como informações referentes às validações que o representante legal foi submetido durante seu processo de cadastro. Para isso, os campos são:

nome | tipo | descrição
:----: | :----: | ---------
name | string | Nome completo do representante legal sendo cadastrado
document_number | string | CPF do representante legal sendo cadastrado, com pontos e hífens, de acordo com a padronização
birthdate | date | Data de nascimento do representante legal de acordo com a padronização
gender | enum | Gênero do representante legal: 'male' ou 'female'
nationality | string | A nacionalidade do representante legal, em ISO 3166-1 alfa-3
mother_name | string | Nome completo da mãe do representante legal
occupation | string | Profissão do representante legal sendo cadastrado
emails | Email | Lista de objetos do tipo Email que descreve o endereço de e-mail do representante legal
documents | Document | Objeto do tipo Document de quaisquer documentos enviados no momento do cadastro do representante legal
address | Address | Objeto do tipo Address que descreve o endereço da moradia do representante legal
phones | Lista de Phone | Lista de objetos do tipo phone que possui a lista de telefones do representante legal
source | Source | Objeto do tipo Source que descreve as características da aplicação utilizada para envio do cadastro
face | Face | Objeto do tipo Face que descreve as informações da validação facial

---

# Recuperar um Cadastro

URL: /documentation/caas/onboarding/query_registration

## Buscar Cadastro específico

A fim de recuperar um Cadastro específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do Cadastro 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/onboarding/natural_person/12345678`

* **Legal Person:**

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678`

```shell
curl "https://api.caas.qitech.app/onboarding/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/onboarding/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o JSON que representa um objeto de Legal Person.

## Buscar PDF

A fim de recuperar um PDF de um cadastro, basta realizar uma requisição GET. O resultado retornado é o arquivo PDF resultante da análise. Caso seja desejado, basta adicionar uma query string denominada base64 com o valor true para que o arquivo PDF seja retornado em base64.

:::info **Atenção**

A geração de PDF pela plataforma é assíncrona e toma alguns segundos, caso o GET seja realizado antes da geração efetiva do PDF, um erro 404 será retornado com uma descrição que aponta esta situação. Basta retentar após alguns segundos e o PDF será retornado.
:::

* **Natural Person:**

`GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf`

`GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf?base64=true`

* **Legal Person:**

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf`

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf?base64=true`

```shell
curl "https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o arquivo PDF gerado pela consulta.

```shell
curl "https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o arquivo PDF gerado pela consulta.

---

# Padrões

URL: /documentation/caas/onboarding/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.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+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.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss.sss±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:ss.sssZ`

## 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 contra 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 contra 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/onboarding/status_dynamics

O processo de análise consiste em enviar um cadastro, tanto de Natural Person como de Legal Person no endpoint adequado e esperar a resposta.

Após a QI Tech realizar a análise do cadastro, 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 cadastro realizado pela QI Tech.

Além do **analysis_status** a QI Tech também possui o **client_status** que tem como objetivo representar o status que o cliente possui 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 do motor de onboarding 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
in_queue | O cadastro está sendo realizado de forma assíncrona. O resultado do cadastro será respondido via Webhook
pending | As consultas estão demorando mais do que o esperado, este cadastro entrou em uma fila de análise automática e será respondido por meio de Webhook
not_analysed | O cadastro foi enviado com a flag de análise falsa, o que significa que nossos sistemas não retornarão uma recomendação

### **client_status**

O **client_status**  indica a situação cadastral do cliente, ou seja, o status do indivíduo ou empresa na sua plataforma. Os seguintes enumeradores existem para este status:

client_status | Descrição
:---------: | ---------
registered | O cliente foi registrado na sua plataforma mas ainda não foi tomada a decisão de aprovação ou reprovação
approved | O cliente está aprovado na sua plataforma
reproved | O cliente está reprovado na sua plataforma
fraud_blocked | O cliente foi bloqueado de usar a sua plataforma devido a supeita ou confirmação de fraude
default_blocked | O cliente foi bloqueado de usar a sua plataforma devido a inadimplência
canceled | O cliente cancelou o uso do seu serviço

---

# Atualizar um Cadastro

URL: /documentation/caas/onboarding/update_registration

Request Body: No bloqueio de um cadastro por fraude ou suspeita de fraude

```json
{
  "client_status": "fraud_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Request Body: No bloqueio de um cadastro por inadimplência

```json
{
  "client_status": "default_blocked",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Request Body: No cancelamento de um cadastro por solicitação do cliente

```json
{
  "client_status": "cancelled",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Para garantir a retroalimentação das regras e do modelo de inteligência artificial, é necessário informar ao sistema quando os Cadastros sofrem alterações, como por exemplo quando são bloqueados, ou quando são cancelados. O status utilizado para essas alterações é o **client_status**, que deve ser alterado sempre que houver alterações no ciclo de vida do cliente. Para isso, requisições com o método PUT, autenticadas normalmente, devem ser utilizadas e os status devem seguir o padrão detalhado anteriomente:

* **Natural Person:**

`PUT https://api.caas.qitech.app/onboarding/natural_person/123456`

* **Legal Person:**

`PUT https://api.caas.qitech.app/onboarding/legal_person/123456`

---

# Webhook

URL: /documentation/caas/onboarding/webhook

Atualizações no status de fraude (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 de fraude. É 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