# QI Tech — Risk Solutions › Gerenciador de Sessões KYC Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 5 página(s). Índice: - Criação de Sessão (/documentation/caas/auth_session_manager/auth_session) - Autenticação (/documentation/caas/auth_session_manager/authentication) - Status HTTP (/documentation/caas/auth_session_manager/http_status) - Introdução (/documentation/caas/auth_session_manager/introduction) - Gestão de Sessão (/documentation/caas/auth_session_manager/retrieve_session) --- # Criação de Sessão URL: /documentation/caas/auth_session_manager/auth_session O objeto de sessão de autenticação é uma entidade que representa o fluxo de autenticação do usuário. Através desse elemento, você poderá gerenciar o processo de coleta das informações de cadastro. ## Definição do Objeto Sessão de Autenticação Request Body ```json { "id": "12345678", "document_number": "111.111.111-11", "settings": { "steps": [ { "step": "device_scan" }, { "step":"face_recognition", }, { "step":"personal_document", "show_success_screen": true, "show_introduction_screen": true, "document_templates":[ "rg", "cnh", "cnh_digital" ] } ], "session_expiration_time_in_minutes": 120, "token_expiration_seconds": 3600, "open_mode": "iframe" } } ``` Todas as trocas de informação de uma sessão utilizam a seguinte definição para este objeto nome | tipo | descrição :----: | :----: | --------- id | string | Identificador da sessão. **É essencial que este número seja único para cada sessão** *(obrigatório)* document_number | string | CPF do indivíduo sendo cadastrado, com pontos e hífens, de acordo com a padronização. *(obrigatório)* settings | objeto | Objeto com as configurações personalizadas da sessão de autenticação. Caso não seja enviada, será utilizada a configuração padrão da empresa. ## Objeto settings O objeto settings contém o campo `steps` que contempla a sequência das etapas de autenticação e suas respectivas configurações: Os possíveis steps aceitos são: * device_scan * face_recognition * personal_document Além disso são aceitos os seguintes campos: nome | tipo | descrição :----: | :----: | --------- session_expiration_time_in_minutes | integer | Data de expiração da sessão. Após essa data, a sessão não será válida. token_expiration_seconds | interger | Tempos de expiração do token de sessão em segundos. (deve esstar entre 1 e 172800, máximo de 48 horas. O valor padrão é 1800) open_mode | string | Define o modo de abertura da sessão, para a mensagem e botões do fuxo de finalização. (deve ser: "iframe" ou "link"). ### device_scan O step de device_scan indica a execução da coleta das informações do dispositivo. **Não possui configurações adicionais** ### face_recognition O step de face_recognition indica a execução da coleta do fluxo de prova de vida através da biometria facial. **Não possui configurações adicionais** ### personal_document O step de personal_document indica a execução da coleta do fluxo de OCR para leitura de documentos. nome | tipo | descrição :----: | :----: | --------- document_templates | array | Lista de documentos que podem ser coletados no fluxo de cadastro. *(obrigatório)* show_success_screen | boolean | Define a existência da tela de sucesso no fluxo de captura de documentos. Valor padrão `true`. show_introduction_screen | boolean | Define a existência da tela de introdução no fluxo de captura de documentos. Valor padrão `true`. Possíveis `document_templates` aceitos: Nome | Tipo | Descrição ---- | ---- | --------- cnh | string | Captura de CNH física FRENTE e VERSO (**fechada**), em duas etapas rg | string | Captura de RG físico FRENTE e VERSO (**fechado**), em duas etapas cnh_digital | string | Envio de CNH **digital** (pdf) passport | string | Envio de Passapore FRENTE e VERSO (**fechada**), em duas etapas. rne | string | Envio de Registro Nacional de Estrangeiros FRENTE e VERSO (**fechada**), em duas etapas. crnm | string | Envio de Carteira de Registro Nacional Migratório FRENTE e VERSO (**fechada**), em duas etapas. ctps | string | Envio de Carteira de Trabalho e Previdência Social FRENTE e VERSO (**fechada**), em duas etapas. others | string | Envio de qualquer documento **isento de validação** FRENTE e VERSO (**fechada**), em duas etapas. ## Enviar um Auth Session Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "id": "12345678", "status": "pending", "expiration_date": "2025-12-11T11:37:15.12-03:00", "settings": { ... }, "auth_session_hash": "1cFL1vM", "step": "device_scan", "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b", "token": "fc0bae39-1c41-4bc2-a5a1-39a7ca01121b", "token_expiration_date": "2025-12-10T11:37:15.12-03:00", } ``` Para realizar a criação de uma sessão, basta enviar um objeto do tipo Auth Session ao seguinte endpoint: `POST https://api.caas.qitech.app/auth_session_manager/auth_session` --- # Autenticação URL: /documentation/caas/auth_session_manager/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/auth_session_manager/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/auth_session_manager/introduction Bem vindo à API de Gerenciamento de Sessões de Autenticação da QI Tech! Esta api foi projetada para controlar o fluxo completo de KYC do usuário! Este serviço organiza o processo de autenticação. Possibilitando a criação de sessões de cadastro KYC com fluxos personalizados e uso dos demais serviços de autenticação da QI Tech: * Device Scan * Face Recognition * OCR Desse modo, é possível iniciar o fluxo de coleta das informações de cadastro através do link retornado pela API. Assim que iniciada, a página web será responsável por guiar o usuário a executar as etapas de KYC definidas naquela sessão. Além disso, por estar diretamente integrada com os demais serviços descritos acima, ela é capaz de coletar as informações necessárias para a finalização do fluxo de autenticação. Com essas informações, será possível efetuar a análise desejada nos demais serviços da QI Tech, como o cadastro de pessoa física ou uma análise pré transacional, por exemplo. ## 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/auth_session_manager/` * Sandbox - `https://api.sandbox.caas.qitech.app/auth_session_manager/` :::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 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. --- # Gestão de Sessão URL: /documentation/caas/auth_session_manager/retrieve_session Ao criar uma sessão de autenticação, basta utilizar o link gerado para iniciar o fluxo de cadastro do usuário. Isso pode ser feito através do envio do link ou do uso dele diretamente em seu website, com ferramentas como `iframe`. ## Objeto de retorno O objeto de retorno da criação e resgate de uma `auth_session` contém as seguintes informações: Response Body ```json { "id": "12345678", "status": "pending", "expiration_date": "2025-12-11T11:37:15.12-03:00", "step_data": { "face_recognition": { "image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7", "event_date": "2025-12-11T11:37:15.12-03:00" }, "personal_document": { "document_template": "rg", "ocr_keys": [ "e13c71d0-ae0e-48e2-8c42-26f997412039", "3991b716-0980-409f-8e33-e3a8dd9a671c" ], "event_date": "2025-12-11T11:37:15.12-03:00" }, "device_scan": { "session_id": "4d450227-c77c-4487-830b-42dcd127798a", "event_date": "2025-12-11T11:37:15.12-03:00" } } "settings": { ... }, "auth_session_hash": "1cFL1vM", "step": "device_scan", "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b", "token": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b", "token_expiration_date": "2025-12-10T11:37:15.12-03:00", } ``` Esse objeto é retornado no enpoint de resgate da sessão: `GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}` Descrição do campos de resposta: nome | tipo | descrição :----: | :----: | --------- id | string | Id da sessão. status | string | Status da sessão. expiration_date | date | Data de expiração da sessão. Após essa data, a sessão é invalidada. step_data | object | Objeto de retorno dos eventos da sessão. settings | object | Objeto de configuração da sessão. auth_session_hash | string | Hash de identificação da sessão. step | string | Etapa atual do usuário. auth_session_url | string | Url capaz de coletar as informações do cadastro. token | string | Token de autenticação da sessão. token_expiration_date | date | Data de expiração do token temporário de autenticação. Padrão definido para 2 horas após a geração da sessão. ### Status Possíveis status: * pending * completed * expired ### Objeto step_data Objeto que contém os dados coletados de cada step. :::info Informação Caso o step não esteja listado nas settings da sessão, o mesmo não estará presente como campo do objeto `step_data` ::: `face_recognition` Nome | Tipo | Descrição ---- | ---- | --------- image_key | string | Chave de identificação da etapa de face_recognition. event_date | date | Data de finalização da etapa. `personal_document` Nome | Tipo | Descrição ---- | ---- | --------- document_template | string | Template selecionado pelo usuário no momento da coleta do documento. ocr_keys | list | Lista com as chaves de identificação de cada documento coletado. event_date | date | Data de finalização da etapa. `device_scan` Nome | Tipo | Descrição ---- | ---- | --------- session_id | string | Chave de identificação da etapa de scan do dispositivo. event_date | date | Data de finalização da etapa. ## Autenticação do fluxo web Para garantir mais segurança para a aplicação, retornamos um token temporário para a página web. É possível resgatar o token, ou gerar um novo através do endpoint: `POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token` Request Body ```json { "token_expiration_seconds": 3600 } ``` O objeto de token tem somente um campo opcional: Nome | Tipo | Descrição ---- | ---- | --------- token_expiration_seconds | interger | Tempos de expiração do token de sessão em segundos. (deve esstar entre 1 e 172800, máximo de 48 horas. O valor padrão é 1800) Response Body ```json { "id": "12345678", "token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3", "token_expiration_date": "2025-12-10T13:37:15.12-03:00", } ``` Assim, caso o token tenha expirado, é possível seguir com a sessão de autenticação gerando um novo token. # Webhook A finalização da sessão será notificada por meio do envio 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 uma *signature_key* que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint. :::info **Atenção** Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS. ::: ## Comunicação com a página web A página web poderá ser integrada através de uma ferramenta chamada `iframe`. Da seguinte maneira: ```html ``` > ⚠️ **Configuração Obrigatória** > > Para que o iframe funcione corretamente em **produção** (`auth-session.caas.qitech.app`) e **sandbox** (`auth-session.sandbox.caas.qitech.app`), é necessário configurar o seguinte header de Permissions-Policy: > > **Configuração com URLs específicas (recomendado):** > ```json > { > "key": "Permissions-Policy", > "value": "geolocation=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), microphone=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), camera=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), fullscreen=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\")" > } > ``` > > **Configuração alternativa (menos restritiva):** > ```json > { > "key": "Permissions-Policy", > "value": "geolocation=*, microphone=*, camera=*, fullscreen=()" > } > ``` > > Essa configuração deve ser aplicada no servidor que hospeda a página que contém o iframe para garantir que as permissões necessárias sejam concedidas. Caso o link seja chamado dessa maneira, a página web irá enviar mensagens de retorno para a página que a requisitou. As possíveis mensagens de retorno são: * success * canceled * invalid_token * expired Que podem ser acessadas da seeguinte maneira: ```javascript window.addEventListener("message", (event) => { if (event.data === "canceled") { //close iframe } if (event.data === "invalid_token") { //close iframe } if (event.data === "success") { //close iframe } if (event.data === "expired") { //close iframe } }); ``` ## Finalização do fluxo Este serviço irá gerenciar o fluxo de coleta de dados de autenticação, que poderão ser utilizados nos demais serviços. Para mais informações de como utilizar as chaves retornadas nos demais produtos, segue o exemplo da análise cadastral de pessoa física [Análise Cadastral](/documentation/caas/onboarding/query_registration)