# QI Tech — Risk Solutions › Monitoramento de Conta Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 7 página(s). Índice: - Criação de Conta (/documentation/caas/account_monitoring/account_registration) - authentication (/documentation/caas/account_monitoring/authentication) - Status HTTP (/documentation/caas/account_monitoring/http_status) - Introdução (/documentation/caas/account_monitoring/introduction) - Criação de Pessoas (/documentation/caas/account_monitoring/person_registration) - Padrões (/documentation/caas/account_monitoring/standards) - Webhook (/documentation/caas/account_monitoring/webhook) --- # Criação de Conta URL: /documentation/caas/account_monitoring/account_registration O Produto de Monitoramento de Conta é dividido entre Conta Pessoa Física e Conta Pessoa Jurídica, onde uma Conta Pessoa Física pode possuir apenas pessoas físicas, enquanto a Conta Pessoa Júridica pode possuir tanto pessoas jurídicas quanto físicas. Para realizar a criação de uma conta basta enviar um objeto do tipo _Account_ para um dos seguintes endpoints: - Conta Pessoa Física `POST https://api.caas.qitech.app/account_monitoring/natural_person_account` > Exemplo ```json { "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "registration_date": "2019-12-20T15:23:12" } ``` - Conta Pessoa Jurídica `POST https://api.caas.qitech.app/account_monitoring/legal_person_account` > Exemplo ```json { "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "registration_date": "2019-12-20T15:23:12" } ``` 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 :----: | :----: | --------- account_id | string | Identificador único da conta. **É essencial que este número seja único para cada requisição** registration_date | string (ISO 8601) | Data e hora do cadastro. ## Desativação e Reativação de Conta Para realizar a desativação de contas dentro do produto de monitoramento de contas, deve-se realizar uma requisição no seguinte endpoint com o seguinte payload, passando o campo de new_account_status como 'deactivated': - Conta Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}` > Exemplo ```json { "new_account_status" : "deactivated" } ``` - Conta Pessoa Jurídica `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}` > Exemplo ```json { "new_account_status" : "deactivated" } ``` Isso desativará a conta e interromperá seu monitoramento. Para reativar uma conta, e consequentemente retomar seu monitoramento, basta realizar uma requisição no seguinte endpoint com o seguinte payload, passando agora o new_account_status como 'active': - Conta Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}` > Exemplo ```json { "new_account_status" : "active" } ``` - Conta Pessoa Jurídica `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}` > Exemplo ```json { "new_account_status" : "active" } ``` Ao se realizar a reativação de uma conta, os interavalos de monitoramento dos tópicos da conta serão reiniciados. Por exemplo, caso todos os tópicos sejam monitorados de 24 em 24 horas, no momento da reativação da conta, as atualizações serão realizadas 24 horas após a reativação. --- # authentication URL: /documentation/caas/account_monitoring/authentication ## Autenticação > Para autenticar uma chamada, utilize o código seguinte: ```shell # No shell, você somente precisa adicionar o header adequado em cada requisição curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte. Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br . Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo: `Authorization: EXAMPLE_API_KEY` :::info **Atenção** Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte. ::: --- # Status HTTP URL: /documentation/caas/account_monitoring/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/account_monitoring/introduction Bem vindo à API de Monitoramento de Conta da QI Tech! Você pode utilizar a nossa API para monitorar contas e pessoas em cima de diversos tópicos de monitoramento, respeitando intervalos de monitoramento totalmente personalizáveis de acordo com as demandas e necessidades do cliente. Hoje o produto possúi os seguintes tópicos de monitoramento: - Para Pessoas Físicas; - Lista OFAC - Lista de Sanções do Escritório de Controle de Ativos Estrangeiros (Office of Foreign Assets Control) - Lista UNSC - Lista de Sanções do Conselho de Segurança das Nações Unidas (United Nations Security Council) - Lista IBAMA - Lista de Penalidades Ambientais do Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renováveis - Lista PEP - Lista de Pessoas Expostas Politicamente - Status Receita Federal - Situação Cadastral na Receita Federal do Brasil - Para Pessoas Jurídicas; - Lista OFAC - Lista de Sanções do Escritório de Controle de Ativos Estrangeiros (Office of Foreign Assets Control) - Lista UNSC - Lista de Sanções do Conselho de Segurança das Nações Unidas (United Nations Security Council) - Lista IBAMA - Lista de Penalidades Ambientais do Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renováveis - Lista CEIS - Cadastro de Empresas Inidôneas e Suspensas - Lista CNEP - Cadastro Nacional de Empresas Punidas - Status Receita Federal - Situação Cadastral na Receita Federal do Brasil Lembrando que os intervalos são definidos por tópico de monitoramento e por tipo de pessoa monitorada, podendo por exemplo a Lista OFAC ser monitorada de 10 em 10 dias para Pessoas Físicas e de 30 em 30 dias para Pessoas Jurídicas Os intervalo de monitoramento de cada tópico segue o padrão ISO 8601, podendo ser qualquer um dos intervalos abaixo apresentados, ou uma combinação dos mesmos: ### Dias, Semanas, Meses e Anos | Notação | Significado | |----------|------------| | `"P1D"` | 1 dia | | `"P7D"` | 7 dias | | `"P1W"` | 1 semana | | `"P1M"` | 1 mês | | `"P1Y"` | 1 ano | --- ### Horas, Minutos e Segundos | Notação | Significado | |-------------|----------------------------------| | `"PT1H"` | 1 hora | | `"PT30M"` | 30 minutos | | `"PT45S"` | 45 segundos | | `"PT2H30M"` | 2 horas e 30 minutos | | `"PT1H15M10S"` | 1 hora, 15 minutos e 10 segundos | --- ### Exemplos Personalizados | Notação | Significado | |----------------|----------------------------------------| | `"P1DT12H"` | 1 dia e 12 horas | | `"P2W3DT4H30M"` | 2 semanas, 3 dias, 4 horas e 30 minutos | Abaixo, 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á entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu! ## Ambientes Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são: * Produção - `https://api.caas.qitech.app/account_monitoring/` * Sandbox - `https://api.sandbox.caas.qitech.app/account_monitoring/` No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas. ## Somente HTTPS Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas. ## Autenticação > Para autenticar uma chamada, utilize o código seguinte: ```shell # No shell, você somente precisa adicionar o header adequado em cada requisição curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte. Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br . Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo: `Authorization: EXAMPLE_API_KEY` :::info **Atenção** Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte. ::: --- # Criação de Pessoas URL: /documentation/caas/account_monitoring/person_registration Para criar as pessoas de suas respectivas contas, deve-se manter a segregação entre endpoints de natural_person_account e legal_person_account. Para solicitar a criação de uma para uma conta, basta enviar um objeto do tipo Person a um dos seguintes endpoints, respeitando a segregação feita no momento de criação de contas: ### Conta Pessoa Física - Criação de Pessoa Física `POST https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > Exemplo ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "John Doe", "document_number": "123.456.789-09", "birthdate": "2000-07-13" } } ``` ### Conta Pessoa Jurídica - Criação de Pessoa Física `POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > Exemplo ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "John Doe", "document_number": "123.456.789-09", "birthdate": "2000-07-13" } } ``` O campo birthdate é obrigatório apenas para as contas que possuam monitoramento de status na receita federal, sendo necessário para consulta de pessoas menores de 18 anos. - Criação de Pessoa Jurídica `POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > Exemplo ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "Empresa das Tampas", "document_number": "12.482.243/0001-34" } } ``` ## Desativação e Reativação de Pessoas Para desativar pessoas, a operação é análoga a realizada para contas, nos seguintes endpoints: ### Conta Pessoa Física - Criação de Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > Exemplo ```json { "new_person_status" : "deactivated" } ``` ### Conta Pessoa Jurídica - Criação de Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > Exemplo ```json { "new_person_status" : "deactivated" } ``` - Criação de Pessoa Jurídica `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > Exemplo ```json { "new_person_status" : "deactivated" } ``` Para reativar pessoas previamente desativadas, a operação é a mesma realizada para desativar pessoas, porém com o envio do new_person_status como 'active nos seguintes endpoints: ### Conta Pessoa Física - Criação de Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > Exemplo ```json { "new_person_status" : "active" } ``` ### Conta Pessoa Jurídica - Criação de Pessoa Física `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > Exemplo ```json { "new_person_status" : "active" } ``` - Criação de Pessoa Jurídica `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > Exemplo ```json { "new_person_status" : "active" } ``` --- # Padrões URL: /documentation/caas/account_monitoring/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. ## Data e Hora com Fuso Horário > Alguns exemplos: ``` 2019-10-15T22:35:12-03:00 2018-05-01T13:32:11+00:00 2019-05-01T00:00:00+00:00 ``` É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00. A máscara utilizada para validação é a seguinte: `YYYY-MM-ddThh:mm:ss±hh:mm` ## Data e Hora sem Fuso Horario > Alguns exemplos: ``` 2019-10-15T22:35:12Z 2018-05-01T13:32:11Z 2019-05-01T00:00:00Z ``` É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado: `YYYY-MM-ddThh:mm:ssZ` ## Data > Alguns exemplos ``` 2019-10-15 2019-01-01 2017-03-20 ``` No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato: `YYYY-MM-dd` ## Documentos Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados. ## CPF > Exemplos de CPFs válidos contra a máscara definida: ``` 123.456.789-12 321.987.543-23 111.283.333-00 ``` > Exemplos de CPFs inválidos contra a máscara definida: ``` 8.577.477-8 08.104.627/0001-23 123.456.789-1 23.456.789-01 ``` O CPF é sempre definido como uma string e será validado conta a máscara: `###.###.###-##` ## CNPJ > Exemplos de CNPJs válidos contra a máscara definida: ``` 08.104.627/0001-02 01.079.210/0114-67 32.402.502/0001-35 ``` > Exemplos de CNPJs inválidos contra a máscara definida: ``` 8.577.477-8 123.456.789-12 321.987.543-23 32.402.502/0001-3 032.402.502/0001-3 ``` O CNPJ é sempre definido como uma string e será validado conta a máscara: `##.###.###/####-##` --- # Webhook URL: /documentation/caas/account_monitoring/webhook Atualizações nos tópicos de monitoramento serão notificadas por meio do envio de webhooks. 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. ::: ## Assinatura > Exemplo de cálculo de assinatura em Python ```python hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + 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*, de maneira 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. ## Webhook de Atualização de Evento Request Body ```json { "person_type" : "natural_person", "account_type" : "natural_person_account", "person_id" : "22f5d028-0ce7-46f7-9b63-e7e38171b485", "account_id" : "e49ac344-f941-4668-9afb-a52ce4e5754a", "monitoring_topic" : "OFAC", "event" : "entered" } ``` Abaixo está o significado de cada campo: | Nome | Tipo | Descrição |:----------------:|:-----------------:|------------------------------------------------------------------------- | person_type | string | Tipo de pessoa (natural_person ou legal_person). | account_type | string | Tipo de conta (natural_person_account ou legal_person_account). | person_id | strin | Identificador único da pessoa, passado na requisição de criação. | account_id | string | Identificador único da conta, passado na requisição de criação. | monitoring_topic | string | Tópico monitorado em que ocorreu a mudança. | event | string | Tipo de evento ocorrido, como "entered" (entrada) ou "exited" (saída) para os tópicos de listas restritivas. A requisição de atualização do tópico de monitoramento possui o formato acima e notifica a mudança no status de um dos tópico de monitoramento dentro da conta. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que 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 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem: * 10 segundos * 40 segundos * 160 segundos * 640 segundos * 2560 segundos * 10240 segundos * 40960 segundos