# QI Tech — Risk Solutions › Limites PIX Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 7 página(s). Índice: - Status HTTP (/documentation/caas/limits/http_status) - Introdução (/documentation/caas/limits/introduction) - Cadastro de Novo Limite (/documentation/caas/limits/limit_registration) - Criando uma lista de beneficiários (/documentation/caas/limits/recipient_list) - Padrões (/documentation/caas/limits/standards) - Dinâmica dos Status (/documentation/caas/limits/status_dynamics) - Webhook (/documentation/caas/limits/webhook) --- # Status HTTP URL: /documentation/caas/limits/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/limits/introduction Bem vindo à API de Limites Pix da QI Tech! Você pode utilizar a nossa API para gerenciar os seus limites pix: - Cadastrar novos limites pix; - Modificar limites pix pré-existentes; - Recuperar limites pix pré-existentes. 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/limits_pix/` * Sandbox - `https://api.sandbox.caas.qitech.app/limits_pix/` :::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 regras pré estabelecidas. Para a análise de uma transação, a seguinte regra é aplicada sobre o valor da transação: Mínimo | Máximo | Decisão ------ | ------ | ------- 0 | 1000 | Aprovado Automaticamente 1001 | 2000 | Derivado para análise manual - Posteriormente aprovado 2001 | 3000 | Derivado para análise manual - Posteriormente reprovado 3001 | 4000 | Reprovado Automaticamente 4001 | 5000 | Não analisado 5001 | - | Pendente ## 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. ::: --- # Cadastro de Novo Limite URL: /documentation/caas/limits/limit_registration Para realizar o cadastro de um novo limite, basta enviar um objeto do tipo _Account_ ao seguinte endpoint: `POST https://api.caas.qitech.app/limits_pix/account` > Exemplo ```json { "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "registration_date": "2019-12-20T15:23:12", "limit": { "withdraw": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "change": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "transaction_natural_person": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "transaction_legal_person": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } } } } ``` 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. limit | limit | Objeto do tipo _limit_. ## Objeto Limit ```json { "withdraw": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "change": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "transaction_natural_person": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "transaction_legal_person": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } } } ``` Este objeto representa os limites de valores aplicáveis aos diferentes tipos de transações em diferentes momentos do dia, levando em consideração a divisão de períodos diurno e noturno. O objeto está organizado em quatro categorias principais (ou tipos de limites): "withdraw" (referente a modalidade PIX Saque), "change" (referente a modalidade PIX troco), "transaction_natural_person" (referente a modalidade PIX transacional para pessoas físicas) e "transaction_legal_person" (referente a modalidade PIX transacional para pessoas jurídicas). Cada categoria contém 2 períodos, "daytime" e "nighttime", representando respectivamente os períodos diurno e noturno, descrevendo o horário de início e os respectivos limites de valores a ser aplicados para a modalidade. Vale citar que as 4 categorias de PIX do objeto limit são obrigatórias, devendo estar presentes no momento de criação da conta. Estrutura de uma Janela de Limite: nome | tipo | descrição :----: | :----: | --------- start_time | string (ISO 8601) | Indica o momento em que os limites de valor para transações PIX são aplicados. Atente-se para a configuração correta do início da Janela de Limite de acordo com o fuso horário que pretende utilizar. amount | inteiro | Valor do limite máximo permitido para a modalidade no período especificado pelo "start_time" em centavos de reais. Uma vez que, de acordo com as diretrizes do Banco Central, as janelas diurnas de limites PIX devem iniciar obrigatoriamente às 6AM, apenas o valor "06:00:00-03:00" será atualmente aceito para configuração do start_time destas janelas. De maneira similar, já que as janelas noturnas de limites PIX devem iniciar às 8PM ou às 10PM, apenas os valores "20:00:00-03:00" e "22:00:00-03:00" serão aceitos para configuração do start_time destas janelas. *Exemplo de Uso:* Suponhamos que o usuário esteja realizando uma transação PIX para pessoa física no horário 12:00:00-03:00. Ao consultar o objeto, localizamos a categoria "transaction_natural_person". Nessa categoria, encontramos os 2 períodos, "daytime" e "nighttime": o primeiro inicia em "06:00:00-03:00" e o segundo inicia em "20:00:00-03:00". Se a transação for realizada entre esses horários, o limite máximo de valor permitido é de 5.000,00 (cinco mil) reais, conforme especificado na primeira janela de limite. No entanto, caso a transação ocorra após "20:00:00-03:00" e antes do próximo horário de início (neste exemplo, às 06:00 do dia seguinte), o limite máximo de valor permitido será de 3.000,00 (três mil) reais, conforme indicado na segunda janela (janela noturna) de limite. # Criando uma Proposta de Modificação de Limite Para solicitar uma modificação de um limite, basta enviar um objeto do tipo Limit ao seguinte endpoint: `POST https://api.caas.qitech.app/limits_pix/account/{account_id}/limit_update_request` > Exemplo ```json { "withdraw": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } }, "change": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 550000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 350000 } }, "transaction_natural_person": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 500000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 300000 } } } ``` O retorno da requisição será composto por uma lista com todas as modificações que foram realizadas, separados por período e por categoria de limite PIX. No caso do exemplo acima, as alterações foram realizadas na categoria "change" (PIX Troco) com a requisição para aumento do limite de ambos os periodos. Portanto a resposta da requisição será a seguinte: ```json { "limit_update_requests" : [ { "limit_update_request_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "analysis_status": "automatically_approved", "client_notification_status": "not_applicable", "limit_update_request_status": "applied", "limit_update_request_type" : "change_daytime", "event_date": "2019-10-01T10:37:25-03:00" }, { "limit_update_request_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "analysis_status": "automatically_approved", "client_notification_status": "not_applicable", "limit_update_request_status": "applied", "limit_update_request_type" : "change_nighttime", "event_date": "2019-10-01T10:37:25-03:00" }, ] } ``` nome | tipo | descrição :----: | :----: | --------- limit_update_request_id | string | Identificador único da Proposta de Modificação de Limite analysis_status | string | Enumerador do analysis_status da proposta client_notification_status | string | Enumerador do client_notification_status da proposta limit_update_request_status | string | Enumerador do limit_update_request_status da proposta limit_update_request_type | string | Enumerador do limit_update_request_type da proposta event_date | string (ISO 8601) | Data e hora da criação da Proposta de Modificação de Limite Para um melhor entendimento dos status de retorno acesse dinâmica de status . --- # Criando uma lista de beneficiários URL: /documentation/caas/limits/recipient_list Conforme regulamentação de limites PIX do Banco Central, é possível realizar a criação de uma lista de beneficiários que utilizarão o mesmo limite diferenciado. Para solicitar a criação de uma lista de beneficiários para uma conta, basta enviar um objeto do tipo Limite ao seguinte endpoint: `POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list` ```json { "limit" : { "transaction": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 60000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 60000 } } } } ``` Que apresentará o seguinte retorno: ```json { "event_date": "2019-10-01T10:37:25-03:00" } ``` nome | tipo | descrição :----: | :----: | --------- event_date | string (ISO 8601) | Data e hora da criação da Lista de Beneficiários # Adicionando um novo Beneficiário a lista de Beneficiários Para adicionar um novo beneficiário a uma lista de beneficiários previamente criada, é necessário apenas realizar a seguinte requisição: `POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient` ```json { "document_number": "123.456.789-10" } ``` Que apresentará o seguinte retorno: ```json { "recipient_id": "c7a79970-b558-4425-998a-5cd6747c1c90", "analysis_status": "automatically_approved", "client_notification_status": "awaiting_notification_period", "recipient_status": "created", "event_date": "2019-10-01T10:37:25-03:00" } ``` nome | tipo | descrição :----: | :----: | --------- recipient_id | string | Identificador único do Beneficiário desta Proposta de Modificação de Limite analysis_status | string | Enumerador do analysis_status da proposta client_notification_status | string | Enumerador do client_notification_status da proposta recipient_status | string | Enumerador do recipient_status da proposta event_date | string (ISO 8601) | Data e hora da criação da Proposta de Modificação de Limite Para um melhor entendimento dos status de retorno acesse dinâmica de status . # Removendo um Beneficiário Para remover um beneficiário específico para uma conta, basta enviar uma requisição do tipo DELETE para o seguinte endereço: `DELETE https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient/{recipient_id}` # Editando os Limites de uma lista de Beneficiários Para solicitar a alteração dos limites de beneficiário de uma dada conta, basta realizar o envio da seguinte requisição: `POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/limit_update_request` ```json { "limit" : { "transaction": { "daytime" : { "start_time": "06:00:00-03:00", "amount": 70000 }, "nighttime" : { "start_time": "20:00:00-03:00", "amount": 70000 } } } } ``` O retorno da requisição será composto por uma lista com todas as modificações que foram realizadas, separados por período. No caso do exemplo acima, as alterações foram realizadas na categoria "transaction" com requisição para aumento do limite de ambos os periodos. Portanto a resposta da requisição será a seguinte: ```json { "recipient_list_limit_update_requests" : [ { "limit_update_request_id": "c7a79970-b558-4425-998a-5cd6747c1c90", "analysis_status": "automatically_approved", "client_notification_status": "awaiting_notification_period", "recipient_status": "created", "recipient_list_limit_update_request_type" : "transaction_daytime", "event_date": "2019-10-01T10:37:25-03:00" }, { "limit_update_request_id": "c7a79970-b558-4425-998a-5cd6747c1c90", "analysis_status": "automatically_approved", "client_notification_status": "awaiting_notification_period", "recipient_status": "created", "recipient_list_limit_update_request_type" : "transaction_nighttime", "event_date": "2019-10-01T10:37:25-03:00" }, ] } ``` nome | tipo | descrição :----: | :----: | --------- recipient_id | string | Identificador único do Beneficiário desta Proposta de Modificação de Limite analysis_status | string | Enumerador do analysis_status da proposta client_notification_status | string | Enumerador do client_notification_status da proposta recipient_status | string | Enumerador do recipient_status da proposta recipient_list_limit_update_request_type | string | Enumerador do recipient_list_limit_update_request_type da proposta event_date | string (ISO 8601) | Data e hora da criação da Proposta de Modificação de Limite --- # Padrões URL: /documentation/caas/limits/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-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: `##.###.###/####-##` ## 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/limits/status_dynamics ## Status de Análise (analysis_status) O "analysis_status" indica o status da decisão da Política de Limites. Os possíveis valores do "analysis_status" são os seguintes: analysis_status | Descrição :---------: | --------- automatically_approved | a Política de Limites aprovou automaticamente esta solicitação de modificação de limite. automatically_reproved | a Política de Limites reprovou automaticamente esta solicitação de modificação de limite. in_manual_analysis | a Política de Limites delegou esta solicitação de modificação de limite para análise manual de mesa. manually_approved | Após análise manual, o analista decidiu aprovar a modificação de limite. manually_reproved | Após análise manual, o analista decidiu reprovar a modificação de limite. reproved_by_time | A requisição foi reprovada pois o tempo de análise expirou. pending | A requisição está pendente para ser processada. ## Status de Notificação do Cliente (client_notification_status) O "client_notification_status" está relacionado ao período em que o cliente deve ser notificado sobre o andamento da solicitação de modificação de limite. client_notification_status | Descrição :---------: | --------- awaiting_notification_period | Indica que a Janela de tempo para notificação do cliente ainda não iniciou. in_notification_period | Indica que estamos na Janela de tempo para notificação do cliente. notification_period_expired | Indica que a Janela de tempo para notificação do cliente já expirou. ## Status de Alteração de Limite (limit_update_request_status) O "limit_update_request_status" está relacionado ao status da solicitação de modificação de limite. limit_update_request_status | Descrição :---------: | --------- created | Indica que a requisição de mudança de limite foi criada. applied | Indica que a requisição de mudança de limite foi aplicada. canceled | Indica que a requisição de mudança de limite foi cancelada. ## Status de Alteração na lista de Beneficiários (recipient_list_append_request_status) O "recipient_list_append_request_status" está relacionado ao status da solicitação de modificação na lista de beneficiários. recipient_list_append_request_status | Descrição :---------: | --------- created | Indica que a requisição de mudança na lista de beneficiários foi criada. applied | Indica que a requisição de mudança na lista de beneficiários foi aplicada. canceled | Indica que a requisição de mudança na lista de beneficiários foi cancelada. --- # Webhook URL: /documentation/caas/limits/webhook Atualizações no status de fraude (Para Orders que sejam derivados para análise manual ou que sejam respondidos como Pendente) e para Sellers bloqueados, 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 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. No caso da atualização do status do pedido, o cliente pode 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 Order para proceder com o polling. :::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 { "id": "123456", "analysis_status": "automatically_approved", "event_date": "2019-10-01T10:37:25-03:00" } ``` A requisição de atualização do status de análise de um evento possui o formato acima e notifica a mudança no status de fraude. 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