# QI Tech — Risk Solutions › Cadastro de Dispositivos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 9 página(s). Índice: - Objeto Account (/documentation/caas/device_manager/account) - Autenticação (/documentation/caas/device_manager/authentication) - Objeto Device (/documentation/caas/device_manager/device_registration) - Status HTTP (/documentation/caas/device_manager/http_status) - Introdução (/documentation/caas/device_manager/introduction) - Objeto Person (/documentation/caas/device_manager/person) - Recuperar ou Desativar uma Account, Person ou Device (/documentation/caas/device_manager/query_registration) - Padrões (/documentation/caas/device_manager/standards) - Dinâmica dos Status (/documentation/caas/device_manager/status_dynamics) --- # Objeto Account URL: /documentation/caas/device_manager/account A account (conta) é uma entidade organizacional que permite o cadastramento de dispositivos. Esta API foi projetada para atender a [Normativa 491 do BACEN](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491), portanto, dados de account devem seguir um padrão para as informações definidas pelo Banco Central, mas quaisquer outros campos necessários podem ser adicionados aos dados da account. ## Definição do Objeto Account Request Body ```json { "account_id": "12345678", "account_type": "natural_person", "registration_date": "2019-12-11T11:37:15.12-03:00", "account_data": { "account_number": "12345678", "agency_number": "1234" ... } } ``` Todas as trocas de informação de uma account 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 :----: | :----: | --------- account_id | string | Identificador da account. **É essencial que este número seja único para cada account** *(obrigatório)* account_type | string | Identificador do tipo de account cadastrada no sistema de cadastro de dispositivo. As accounts podem ser do tipo pessoa física `natural_person` ou pessoa jurídica `legal_person` .*(obrigatório)* registration_date | datetime | Data e hora do registro da account, com fuso horário. *(obrigatório)* account_data | object | objeto que pode conter quaisquer dados da account, mas se contiver o número da account `account_number` e agência `agency_number` os dois devem ser obrigatoriamente do tipo string. ## Enviar um Account Request Body ```json { "account_id": "12345", ... } ``` Response Body ```json { "account_id": "12345678", "account_type": "natural_person", "registration_date": "2019-12-11T11:37:15.12-03:00", "account_data": { "account_number": "12345678", "agency_number": "1234" ... } } ``` Para realizar a criação de uma account, basta enviar um objeto do tipo Account ao seguinte endpoint: `POST https://api.caas.qitech.app/device_manager/account` --- # Autenticação URL: /documentation/caas/device_manager/authentication > Para autenticar uma chamada, utilize o código a seguir: ```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 com o nosso time de suporte. ::: --- # Objeto Device URL: /documentation/caas/device_manager/device_registration O registro de um device (dispositivo) com identificação única deve ser realizado por meio do endpoint de Device. Para que o cadastro seja efetivado, é necessária a utilização da Device Scan para que a identificação desse device seja registrada para reconhecimento posterior. ### Dinâmica dos Status - **status** O status **status** refere-se ao status atual do device. Os seguintes status estão disponíveis: * registered * not_registered * deactivated ### Dinâmica dos Status - **analysis_status** O status **analysis_status** indica o status da decisão do motor de fraude e possui o seguinte fluxo de estados: * automatically_approved * automatically_reproved * pending ## Definição do Objeto Device Request Body ```json { "device_id": "12345678", "session_id": "12345678", "face_recognition_key": "12345678", "document_number": "111.111.111-11", "mfa_status": "approved", "registration_date": "2019-12-11T11:37:15.12-03:00" } ``` 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 | descrição :----: | :----: | --------- device_id | string | Identificador do device. **É essencial que este número seja único para cada device** *(obrigatório)* session_id | string | Identificador da sessão na Device Scan. *(obrigatório)* face_recognition_key | string | Identificador da imagem para biometria facial caso o produto seja contratado como 2FA do cadastro. document_number | string | Documento do usuário para validação de rosto. Só deve ser enviado caso não tenha sido informado no momento do cadastro do objeto person. mfa_status | string | Status do MFA do cadastro podendo estar entre os seguintes valores: *approved* *reproved* registration_date | datetime | A data e hora de início do cadastro, com fuso horário. *(obrigatório)* :::warning Atenção O campo `document_number` é necessário para a validação do rosto na base, então, caso não tenha sido informado no momento do cadastro do usuário, ele é obrigatório. Ele nunca deve ser diferente do cadastrado na person. ::: ## Enviar um Device Registration Request Body ```json { "device_id": "12345", ... } ``` Response Body ```json { "device_id": "12345", "status": "registered", "analysis_status": "automatically_approved", "reason": "rule_decision_enum", "reason_description": "Descrição da regra" } ``` Para realizar o registro de um device, basta enviar um objeto do tipo Device ao seguinte endpoint: `POST https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device` --- # Status HTTP URL: /documentation/caas/device_manager/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 com 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 a este endpoint. 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 | Indica uma indisponibilidade temporária, planejada ou não, de infraestrutura dos nossos servidores. --- # Introdução URL: /documentation/caas/device_manager/introduction Bem-vindo à API de Cadastro de Dispositivos da QI Tech! Esta api foi projetada para atender a [Normativa 491 do BACEN](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491). Em conjunto com a Device Scan, essa API é capaz de gerar uma identificação única para cada dispositivo. Esta API administra o processo de identificação de dispositivos, possibilitando que, posteriormente, você possa validar esse mesmo aparelho. Este fluxo é estruturado por meio das entidades a seguir: * Account - Conta * Person - Pessoa * Device - Dispositivo Você pode utilizar a nossa API para criar e recuperar cadastros de dispositivos por meio de do seguinte serviço: * **Device Registration** - utilizado para associar um dispositivo a uma pessoa. Por meio desse cadastro, será possível realizar as validações de dispositivo para os demais acessos desta mesma pessoa. ## Ambientes Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são: * Produção - `https://api.caas.qitech.app/device_manager/` * Sandbox - `https://api.sandbox.caas.qitech.app/device_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 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 garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas. ## 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 (como um erro de digitação ou uma organização inadequada), envie-nos um e-mail. Assim, nós tornamos a documentação cada vez mais prática para evitar que outros desenvolvedores encontrem as mesmas dificuldades. --- # Objeto Person URL: /documentation/caas/device_manager/person A conta pode ter mais de um usuário a acessando, logo, cada usuário deve ter seu registro para segregar ações em contas conjuntas. As informações citadas abaixo devem seguir os padrões estabelecidos, mas quaisquer campos podem ser adicionados aos dados da conta caso seja necessário. ## Definição do Objeto Person Request Body ```json { "person_id": "12345678", "document_number": "111.111.111-11", "registration_date": "2019-12-11T11:37:15.12-03:00", "person_data": { "name": "Joao da Silva", "email": "person@email.com", "phone": { "number": "999999999", "international_dial_code": "55", "area_code": "11" } } } ``` Todas as trocas de informação de uma pessoa 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 :----: | :----: | --------- person_id | string | Identificador da pessoa. **É essencial que este número seja único para cada pessoa** *(obrigatório)* document_number | string | número do documento, podendo ser CPF ou CNPJ com pontuação. registration_date | datetime | Data e hora do registro da pessoa associada à conta, com fuso horário. *(obrigatório)* person_data | object | objeto que pode conter quaisquer dados da pessoa. Se contiver o nome `name`, email `email`, e telefone `phone` (com seus campos `number`, `international_dial_code` e `area_code`), todos os objetos citados devem ser do tipo string. ## Criar um Person Request Body ```json { "person_id": "12345678", ... } ``` Response Body ```json { "person_id": "12345678", "document_number": "111.111.111-11", "registration_date": "2019-12-11T11:37:15.12-03:00", "person_data": { "name": "Joao da Silva", "email": "person@email.com", "phone": { "number": "999999999", "international_dial_code": "55", "area_code": "11" } } } ``` Para realizar a criação de uma pessoa, basta enviar um objeto do tipo Person ao seguinte endpoint: `POST https://api.caas.qitech.app/device_manager/account/{account_id}/person` --- # Recuperar ou Desativar uma Account, Person ou Device URL: /documentation/caas/device_manager/query_registration ## Buscar Device específico A fim de recuperar um Device específico, basta realizar uma requisição GET. O resultado retornado é o JSON mais atualizado do Device em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado. `GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}` ```shell curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}" -H "Authorization: EXAMPLE-OF-API-KEY" ``` ## Buscar Lista de Devices Para recuperar vários devices, basta realizar uma requisição GET. O resultado retornado é o JSON com uma lista de informações básicas de todos os devices de um usuário. `GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices` ```shell curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices" -H "Authorization: EXAMPLE-OF-API-KEY" ``` ## Desativar Device específico Para desativar um Device específico, basta realizar uma requisição DELETE. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado. Um device após ser desativado não pode mais ser validado. `DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}` ```shell curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}" \ -H "Authorization: EXAMPLE-OF-API-KEY" ``` ## Buscar Conta específica Permite recuperar os dados de uma conta pelo seu identificador. Retorna os detalhes da conta, ou 404 caso não exista. `GET https://api.caas.qitech.app/device_manager/account/{account_id}` ```shell curl "https://api.caas.qitech.app/device_manager/account/{account_id}" \ -H "Authorization: EXAMPLE-OF-API-KEY" ``` ## Buscar Pessoa específica Permite recuperar os dados de uma pessoa específica dentro de uma conta. Retorna os dados atualizados da pessoa, ou 404 caso não exista. `GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}` ```shell curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \ -H "Authorization: EXAMPLE-OF-API-KEY" ``` --- ## Desativar Conta Realiza a desativação de uma conta. Após desativada, a conta não poderá mais ser utilizada para registro ou validação de devices. `DELETE https://api.caas.qitech.app/device_manager/account/{account_id}` ```shell curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}" \ -H "Authorization: EXAMPLE-OF-API-KEY" ``` ## Desativar Pessoa Realiza a desativação de uma pessoa dentro de uma conta. Após desativada, a pessoa não poderá mais registrar ou validar devices. `DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}` ```shell curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \ -H "Authorization: EXAMPLE-OF-API-KEY" ``` --- # Padrões URL: /documentation/caas/device_manager/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 números inteiros representando 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 Horário > 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 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, ela 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/device_manager/status_dynamics O processo de análise consiste em enviar um evento, como de Device Validation, por exemplo, no endpoint adequado e aguardar 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 três **analysis_status** que indicam o status da decisão do motor de análise e possui a seguinte máquina de estados: 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. 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 assim que possível.