# QI Tech — Risk Solutions › Eventos de Conta Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 8 página(s). Índice: - Autenticação (/documentation/caas/account_event/authentication) - Objeto Device Validation (/documentation/caas/account_event/device_validation) - Status HTTP (/documentation/caas/account_event/http_status) - Introdução (/documentation/caas/account_event/introduction) - Pre PIX Transaction (/documentation/caas/account_event/pre_pix_transaction) - Recuperar um Evento de Conta (/documentation/caas/account_event/query_registration) - Padrões (/documentation/caas/account_event/standards) - Dinâmica dos Status (/documentation/caas/account_event/status_dynamics) --- # Autenticação URL: /documentation/caas/account_event/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 à 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. ::: --- # Objeto Device Validation URL: /documentation/caas/account_event/device_validation A validação de um dispositivo por identificação única deve ser realizada através do endpoint de Event Type Device Validation. Os dados enviados deverão ser os dados gerados na API de Cadastro de Dispositivos, juntamente com um id de sessão de Device Scan, isto é, para realizar uma validação de dispositivo a aplicação deve utilizar o SDK para gerar um identificador único e deve ser realizado o cadastro do dispositivo para que ele possa ser identificado posteriormente. ### Dinâmica dos Status - **analysis_status** O status **analysis_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples: * automatically_approved * automatically_reproved * in_manual_analysis * manually_approved * manually_reproved * pending ## Definição do Objeto Device Validation Request Body ```json { "id": "12345678", "account_id": "12345678", "person_id": "12345678", "session_id": "12345678", "event_date": "2019-12-11T11:37:15.12-03:00" } ``` Todas as trocas de informação de uma validação utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do evento. **É essencial que este número seja único para cada requisição** *(obrigatório)* account_id | string | Identificador da conta cadastrada no sistema de cadastro de dispositivo. Para realizar mais de uma análise referente a um mesmo cadastro, apenas utilize o mesmo account_id nas diferentes análises.*(obrigatório)* person_id | string | Identificador do usuário associado a conta cadastrada no sistema de cadastro de dispositivo. Para realizar mais de uma análise referente a um mesmo cadastro, apenas utilize o mesmo person_id nas diferentes análises.*(obrigatório)* session_id | string | Identificador da sessão de análise da Device Scan.*(obrigatório)* face_recognition_key | string | Identificador da imagem gerada no SDK para identificação facial. event_date | datetime | Data e hora o evento *(obrigatório)* ## Enviar um Device Validation Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "id": "12345", "analysis_status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a validação de um Dispositivo, basta enviar um objeto do tipo Device Validation ao seguinte endpoint: `POST https://api.caas.qitech.app/account_event/event_type/device_validation/event` --- # Status HTTP URL: /documentation/caas/account_event/http_status Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, conforme a RFC 7231 : Status HTTP | Significado | Descrição ---------- | ------- | --------------------------------- 400 | Bad Request | A requisição enviada possui algum erro de formatação. Geralmente, 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, conforme 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/account_event/introduction Bem vindo à API de Eventos de Conta da QI Tech! Esta API dá acesso aos serviços de monitoramento e regras para eventos dentro de contas da sua plataforma! Esta API pode ser utilizada para a validação de dispositivos juntamente com a api de Device Scan e Cadastro de Dispositivos, mas pode ser usada para outras validações como: * Login. * Acesso a telas. * Alteração de senha. * Alteração de dados cadastrais. * Validações pré-transações. * Validações de liveness. Você pode utilizar a nossa API para acessar os endpoints para avaliar os seguintes tipos de eventos: * **Device Validation** - utilizado para validação de identificação única de um dispositivo. * **Pre Pix Transaction** - utilizado para a pré-validação de transações Pix. * **Registration Data Validation** - utilizado para a validação de dados cadastrais. Diferentes tipos de eventos podem ser implementados dependendo das necessidades do seu sistema. Ao lado, você pode observar a implementação da API utilizando curl. Com isso, você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência. ## 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/account_event/` * Sandbox - `https://api.sandbox.caas.qitech.app/account_event/` :::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 conforme a regra configurada para o evento. ## 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. --- # Pre PIX Transaction URL: /documentation/caas/account_event/pre_pix_transaction No momento em que o pagador tiver a intenção de iniciar um pagamento, os dados da transação poderão ser avaliados previamente pelo nosso servidor. Deste modo, será possível realizar uma análise prévia do risco envolvido na transação, baseado naquele conjunto de dados. ## Definição do Objeto de Pre Pix Transactions Request Body ```json { "id": "082373263", "transaction_direction": "received", "client": { "id": "123456", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "type": "natural_person", "address": { "street": "Avenida 13", "number": "704", "neighbourhood": "Centro", "city": "Ituiutaba", "uf": "MG", "complement": "Apt 1101", "postal_code": "38300-140" }, "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "amount": 13725, "dict_key": { "key_type": "cpf", "key_value": "09991222669", "assignment_date": "2020-01-15T18:00:00-03:00" }, "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "source_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "owner": { "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA." }, "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_account": { "participant": "60701190", "branch": "3675", "account_number": "10442", "account_digit": "6", "owner": { "type": "natural_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti" }, "account_type": "SLRY", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_statistics": { "person":{ "settlements":{ "d90":4, "m12":67, "m60":618 }, "application_frauds":{ "d90":0, "m12":4, "m60":9 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "rejected_reports":{ "d90":0, "m12":0, "m60":0 }, "registered_accounts":0 }, "owner":{ "settlements":{ "d90":0, "m12":0, "m60":0 }, "application_frauds":{ "d90":0, "m12":0, "m60":0 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "registered_accounts":0 }, "key":{ "settlements":{ "d90":0, "m12":0, "m60":0 }, "application_frauds":{ "d90":0, "m12":0, "m60":0 }, "mule_accounts":{ "d90":0, "m12":0, "m60":0 }, "scammer_accounts":{ "d90":0, "m12":0, "m60":0 }, "other_frauds":{ "d90":0, "m12":0, "m60":0 }, "unknown_frauds":{ "d90":0, "m12":0, "m60":0 }, "total_frauds_transaction_amount":{ "d90":0, "m12":0, "m60":0 }, "distinct_fraud_reporters":{ "d90":0, "m12":0, "m60":0 }, "open_reports":0, "open_reports_distinct_reporters":0, "rejected_reports":{ "d90":0, "m12":0, "m60":0 }, "distinct_accounts":{ "d90":0, "m12":0, "m60":0 } } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065.098", "session_id": "7839jdqd9a8wd9" }, "event_date": "2019-12-11T11:37:15.12-03:00" } ``` Uma transação deve ser enviada para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude. O status da transação representa a decisão retornada pelo modelo sobre aquela transação. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` * `automatically_challenged` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvidas na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que esta transação seja aprovada. automatically_reproved | Recomenda-se que esta transação seja reprovada. automatically_challenged | Os algoritmos da QI Tech recomendam que esta transação seja desafiado. pending | A transação está sendo processada. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do pagamento no sistema do cliente. **É essencial que este número seja único para cada processo de pagamento** *(obrigatório)* transaction_direction | enumerador | Tipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. *(obrigatório)* client | *client* | Objeto que representa os dados do cliente, seja ele o pagador ou o recebedor. *(obrigatório)* amount | inteiro | O valor do pagamento, em centavos- conforme descrição da seção "Padrões". *(obrigatório)* pix_modality | string | Tipo de transação cadastrada. Indica se representa uma transferência, um troco ou um saque. dict_key | *dict_key* | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na transação. face_recognition_key | string | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial. source_account | *source_account* | Objeto que representa os dados da conta debitada. *(obrigatório)* destination_account | *destination_account* | Objeto que representa os dados da conta creditada. *(obrigatório)* destination_statistics | *destination_statistics* | Objeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN. source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento event_date | datetime | A data e hora de início da transação, com fuso horário. *(obrigatório)* Existem os seguintes enumeradores para *transaction_direction*: `sent` e `received`. Existem os seguintes enumeradores para *pix_modality*: `transacation`, `change` e `withdraw`. ## Enviar uma Pré Transação Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "id": "12345", "analysis_status": "automatically_approved", "reason": "rule_decision_enum", "reason_desciption": "Descrição da regra" } ``` Para realizar a avaliação de uma pre transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint: `POST https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction` ## Fluxo de Desafio É 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 2FA, como uma análise facial, para o usuário. ## Passo-a-passo da execução do fluxo **1.** O Evento é submetido para análise, e retornará o status *automatically_challenged*. Request Body ```json { "id": "082373263", ... "event_date": "2019-12-11T11:37:15.12-03:00" } ``` Response Body ```json { "id": "082373263", "analysis_status": "automatically_challenge" ... } ``` **2.** Após a primeira requisição de análise ter retornado um *analysis_status* de desafio, uma nova requisição pode ser enviada com o resultado do processo do cliente caso o mesmo tenha sido finalizado. Esta requisição deve ser feita no mesmo *event_id* da requisição anterior e o status atual deve ser obrigatoriamente *automatically_challenged*. Os possíveis status para essa atualização são: * `approved_by_client` * `reproved_by_client` `PATCH https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction/{event_id}` Request Body: Envio com informações adicionais ```json { "analysis_status": "approved_by_client" } ```` Response Body ```json { "id": "082373263", "analysis_status": "approved_by_client" ... } ``` Atente-se para utilizar o mesmo event_id utilizado na sua primeira análise. --- # Recuperar um Evento de Conta URL: /documentation/caas/account_event/query_registration A fim de recuperar um evento de conta específico, basta realizar uma requisição GET. O resultado retornado é o JSON mais atualizado do evento em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado. ## Possiveis eventos: - device_validation - pre_pix_transaction `GET https://api.caas.qitech.app/event_type/{event_name}/event/{event_id}` ```shell curl "https://api.caas.qitech.app/event_type/device_validation/event/12345678" -H "Authorization: EXAMPLE-OF-API-KEY" ``` --- # Padrões URL: /documentation/caas/account_event/standards Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões 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 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 defini-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 à 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/account_event/status_dynamics O processo de análise consiste em enviar um evento, como de Device Validation, por exemplo, no endpoint adequado e esperar a resposta. Após a QI Tech realizar a análise do evento, ela retornará uma resposta com um status referente à análise. O campo **analysis_status** representa o resultado da análise de evento realizada pela QI Tech. ### **analysis_status** Conforme descrito anteriormente, a QI Tech possui oito **analysis_status** que indicam o status da decisão do motor de eventos de conta e possui uma máquina de estados bastante simples: analysis_status | Descrição :---------: | --------- automatically_approved | Os algoritmos da QI Tech recomendam que este evento seja aprovado. automatically_reproved | Os algoritmos da QI Tech recomendam que este evento seja reprovado. automatically_challenge | Os algoritmos da QI Tech recomendam que o usuário tome uma ação para adquirir mais informações para a análise. in_manual_analysis | Os algoritmos da QI Tech enviaram este evento para a análise manual. manually_approved | Após análise manual, o analista decidiu aprovar o evento. manually_reproved | Após análise manual, o analista decidiu reprovar o evento. in_queue | O evento está sendo realizado de forma assíncrona. O resultado do evento será respondido via Webhook. pending | As consultas estão demorando mais do que o esperado, este evento entrou em uma fila de análise automática e será respondido por meio de Webhook. not_analysed | O evento foi enviado com a flag de análise falsa, o que significa que nossos sistemas não retornarão uma recomendação.