# QI Tech — Risk Solutions › Antifraude banking Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 13 página(s). Índice: - Boleto (/documentation/caas/banking/bankslips) - Pagamento de Contas (/documentation/caas/banking/bill_payments) - Depósitos (/documentation/caas/banking/deposits/introduction) - Status HTTP (/documentation/caas/banking/http_status) - Introdução (/documentation/caas/banking/introduction) - Objetos Compartilhados (/documentation/caas/banking/objects) - PIX Dict Operation (/documentation/caas/banking/pix_dict_operations) - PIX Infraction Report (/documentation/caas/banking/pix_infraction_reports) - PIX Transaction (/documentation/caas/banking/pix_transactions) - Padrões (/documentation/caas/banking/standards) - Webhook (/documentation/caas/banking/webhook) - Transferências (/documentation/caas/banking/wire_transfers) - Saques (/documentation/caas/banking/withdrawals) --- # Boleto URL: /documentation/caas/banking/bankslips No momento em que um usuário efetuar ou receber um pagamento por boleto, os dados do pagamento deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados. ## Definição do Objeto de Boleto Request Body ```json { "id": "082373263", "bankslip_direction": "received", "document_amount": 13725, "discount_amount": 1000, "other_deduction_amount": 0, "interest_amount": 254, "amount": 12979, "bankslip_payment_date": "2020-10-07T15:06:25-03:00", "bankslip_due_date": "2020-10-07", "bankslip_issuing_date": "2020-10-07", "description": "BOLETO PARA PAGAMENTO DA MENSALIDADE DE SETEMBRO", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "payer": { "id": "182373263", "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA.", "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" }, "email": "mailto@qitech.com.br", "account": { "participant": "60701190", "branch": "3675", "account_number": "13212", "account_digit": "5", "account_type": "CACC" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "recipient": { "id": "282373263", "type": "legal_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "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" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "10552", "account_digit": "6", "account_type": "CACC" } }, "final_recipient": { "id": "382373263", "type": "legal_person", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "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" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "10442", "account_digit": "6", "account_type": "CACC" } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.056.098", "session_id": "7839jdqd9a8wd9" } } ``` Um pagamento de boleto deve ser enviado 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 do pagamento representa a decisão retornada pelo modelo sobre aquele boleto. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que este pagamento de boleto seja aprovado. automatically_reproved | Recomenda-se que este pagamento de boleto seja reprovado. in_manual_analysis | Recomenda-se que este pagamento de boleto seja analisado manualmente. pending | O pagamento de boleto está sendo processado. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada pagamento de boleto** bankslip_direction | enumerador | Modalidade do pagamento do boleto. Define se o cliente está pagando o boleto ou recebendo o pagamento do boleto. document_amount | inteiro | Valor do documento em centavos - conforme descrição da seção "Padrões". discount_amount | inteiro | Valor do desconto ou abatimento aplicado sobre o valor do documento em centavos - conforme descrição da seção "Padrões". other_deduction_amount | inteiro | Valor das outras deduções aplicadas sobre o valor do documento em centavos - conforme descrição da seção "Padrões". interest_amount | inteiro | Valor da multa, mora ou juros aplicados sobre o valor do documento em centavos - conforme descrição da seção "Padrões". amount | inteiro | Valor final pago no boleto - conforme descrição da seção "Padrões". bankslip_payment_date | datetime | A data e hora do pagamento do boleto, com fuso horário. bankslip_due_date | date | Data de vencimento do boleto de acordo com a padronização description | string | Campo descrição ou observações do boleto. face_recognition_key | string | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial. validation_key | string | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações. payer | *bankslip_payer* | Objeto que representa a pessoa física ou pessoa jurídica que pagou o boleto. recipient | *bankslip_recipient* | Objeto que representa a pessoa física ou pessoa jurídica beneficiária do boleto. final_recipient | *bankslip_recipient* | Objeto que representa a pessoa física ou pessoa jurídica beneficiária final do boleto. source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para o pagamento do boleto. Existem os seguintes enumeradores para *bankslip_direction*: `payed` e `received`. ## Enviar um Pagamento de Boleto Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a avaliação de um pagamento de boleto, basta enviar um objeto do tipo Boleto ao seguinte endpoint: `POST https://api.caas.qitech.app/bankslip/bankslip` ## Recuperar um Pagamento de Boleto Response Body ```json { "id": "082373263", "bankslip_direction": "received", ... } ``` Para recuperar os dados de um pagamento de boleto, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}` Onde *bankslip_id* é o identificador da transação no sistema do cliente utilizado no envio do boleto. ## Atualizar um pagamento de boleto Request Body ```json { "bankslip_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "bankslip_status": "completed" } ``` Após um pagamento de boleto ser criado e analisado, ela será enviado à câmara de compensação para ser processado. Deste modo, é necessário que seja informada a atualizações de status do pagamento quando este for enviado, através do endpoint: `PUT https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}` Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os pagamentos de boleto que estejam realmente sucetíveis a fraude. --- # Pagamento de Contas URL: /documentation/caas/banking/bill_payments No momento em que um usuário efetuar um pagamento de contas, os dados do pagamento deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados. ## Definição do Objeto de Pagamento de Contas Request Body ```json { "id": "082373263", "amount": 12979, "bill_payment_date": "2020-10-07T15:06:25-03:00", "bill_due_date": "2020-10-07", "bill_issuing_date": "2020-10-07", "service_description": "CONTA DE ELETRICIDADE ENEL", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "company": { "id": "451673263", "provided_service": "eletricity", "name" : "Enel", "legal_name": "Eletropaulo Metropolitana Eletricidade de São Paulo S.A.", "document_number": "61.695.227/0001-93", "address": { "street": "Av. Dr. Marcos Penteado de Ulhôa Rodrigues", "number": "939", "neighbourhood": "Sítio Tamboré", "city": "Barueri", "uf": "SP", "complement": "Loja 1 e 2", "postal_code": "06460-040" } }, "payer": { "id": "182373263", "type": "legal_person", "document_number": "07.487.735/0001-69", "name": "Gioconda Pizzaria e Rotisseria LTDA.", "email": "gioconda_pizza@bol.com.br", "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" }, "account": { "participant": "60701190", "branch": "3675", "account_number": "13212", "account_digit": "5", "account_type": "CACC" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.105.098", "session_id": "7839jdqd9a8wd9" } } ``` Um pagamento de conta deve ser enviado 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 do pagamento representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que este pagamento de conta seja aprovado. automatically_reproved | Recomenda-se que este pagamento de conta seja reprovado. in_manual_analysis | Recomenda-se que este pagamento de conta seja analisado manualmente. pending | O pagamento de conta está sendo processado. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada pagamento de conta** document_amount | inteiro | Valor do documento em centavos - conforme descrição da seção "Padrões". other_deduction_amount | inteiro | Valor das outras deduções aplicadas sobre o valor do documento em centavos - conforme descrição da seção "Padrões". interest_amount | inteiro | Valor da multa, mora ou juros aplicados sobre o valor do documento em centavos - conforme descrição da seção "Padrões". amount | inteiro | Valor final pago no conta - conforme descrição da seção "Padrões". bill_payment_date | datetime | A data e hora do pagamento do conta, com fuso horário. bill_due_date | date | Data de vencimento do conta de acordo com a padronização description | string | Campo descrição ou observações do conta. face_recognition_key | string | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial. validation_key | string | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações. client | *client* | Objeto que representa os dados do cliente, seja ele o cliente que está efetuando o pagamento do boleto ou o recebendo o pagamento. company | *company* | Objeto que representa a concessionária ou prestador de serviço referente àquela conta. payer | *bill_payer* | Objeto que representa a pessoa física ou pessoa jurídica que pagou a conta. recipient | *bill_client* | Objeto que representa a pessoa física ou pessoa jurídica para quem a conta foi emitida. source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para o pagamento da conta. ## Enviar um Pagamento de Conta Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a avaliação de um pagamento de conta, basta enviar um objeto do tipo BillPayment ao seguinte endpoint: `POST https://api.caas.qitech.app/bill_payment/bill_payment` ## Recuperar um Pagamento de Conta Response Body ```json { "id": "082373263", "amount": 12979, ... } ``` Para recuperar os dados de um pagamento de conta, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}` Onde *bill_payment_id* é o identificador da transação no sistema do cliente utilizado no envio do pagamento de conta. ## Atualizar um pagamento de conta Request Body ```json { "bill_payment_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "bill_payment_status": "completed" } ``` Após um pagamento de conta ser criado e analisado, ela será enviado à câmara de compensação para ser processado. Deste modo, é necessário que seja informada a atualizações de status do pagamento quando este for enviado, através do endpoint: `PUT https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}` Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os pagamentos que estejam realmente sucetíveis a fraude. --- # Depósitos URL: /documentation/caas/banking/deposits/introduction No momento em que um usuário efetuar um depósito, os dados do depósito deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco de fraude e Prevenção a Lavagem de Dinheiro envolvido na operação, baseado naquele conjunto de dados. ## Definição do Objeto de Depósito Request Body ```json { "id": "082373263", "amount": 12979, "deposit_date": "2020-10-07T15:06:25-03:00", "client": { "id": "182373263", "type": "natural_person", "document_number": "123.456.789-10", "name": "Benedito Calixto de Jesus", "email": "benedito@test.com", "address": { "street": "Rua José Wasth Rodrigues", "number": "243", "neighbourhood": "Vila Maria", "city": "São Paulo", "uf": "SP", "complement": "Apartamento 14B", "postal_code": "02121-010" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "destination_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "terminal": { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" }, "authentication": { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } } ``` Um depósito deve ser enviado 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 do depósito representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que este depósito seja aprovado. automatically_reproved | Recomenda-se que este depósito seja reprovado. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do depósito no sistema do cliente. **É essencial que este número seja único para cada depósito** amount | integer | Valor do depósito em centavos - conforme descrição da seção "Padrões". deposit_date | datetime | Data e hora da realização do depósito - conforme descrição da seção "Padrões". client | *client* | Objeto com os dados do cliente detentor da conta de origem. destination_account | *account* | Objeto que determina a conta de destino do recurso a ser depositado. terminal | *terminal* | Objeto com os dados do terminal onde o depósito está sendo realizado. authentication | *authentication* | Objeto com as informações de autenticação. ## Objetos do Depósito ### Objeto Terminal Request Body ```json { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" } ``` Objeto que representa o terminal que foi utilizado para o depósito. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do terminal no sistema do cliente latitude | number | Latitude, em graus, da localização do terminal longitude | number | Longitude, em graus, da localização do terminal address | *address* | Endereço do terminal type | enum | Tipo do terminal, possíveis valores: "atm", "counter" ### Objeto Authentication Request Body ```json { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } ``` Objeto que define os parâmetros da autenticação utilizada no momento do depósito. nome | tipo | descrição :----: | :----: | ----------- used_password | boolean | Determina se o usuário utilizou senha used_card | boolean | Determina se o usuário está com o cartão presente na autenticação used_card_chip_and_pin | boolean | Determina se o usuário utilizou o chip e senha do cartão used_card_magnetic_stripe | boolean | Determina se o usuário utilizou a tarja magnética do cartão used_fingerprint | boolean | Determina se o usuário utilizou fingerprint typed_account_number | boolean | Determina se o usuário digitou os dados da conta ## Enviar um Depósito Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "id": "082373263", "analysis_status": "automatically_approved", "reason": "2019-10-01T10:37:25-03:00" } ``` Para realizar a avaliação de um depósito, basta enviar um objeto do tipo deposit ao seguinte endpoint: `POST https://api.caas.qitech.app/deposit/deposit` ## Recuperar um Depósito Response Body ```json { "id": "082373263", "analysis_status": "automatically_approved", "reason": "2019-10-01T10:37:25-03:00" } ``` Para recuperar os dados de um depósito, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/deposit/deposit/{deposit_id}` Onde *deposit_id* é o identificador da transação no sistema do cliente utilizado no envio do depósito. ## Atualizar um depósito Request Body ```json { "deposit_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "id": "082373263", "deposit_status": "completed" } ``` Após um depósito ser criado e analisado, o dinheiro será disponibilizado ao usuário. Este processo pode ser interrompido por alguma outra regra de negócio. Deste modo, é necessário que seja informada a atualizações de status do saque quando este for finalizado, através do endpoint: `PUT https://api.caas.qitech.app/deposit/deposit/{deposit_id}` Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os depósitos que estejam realmente sucetíveis a fraude. --- # Status HTTP URL: /documentation/caas/banking/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/banking/introduction Bem vindo à API de Banking da QI Tech! Esta API dá acesso à funcionalidade de prevenção a fraudes para operações de bancos e contas digitais, como por exemplo análises de transferências, pagamentos de contas e pagamentos de boletos. 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á 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/` * Sandbox - `https://api.sandbox.caas.qitech.app/` :::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. ::: ## Análises no ambiente de Sandbox No ambiente de Sandbox, as análises não são cobradas e são respondidas de acordo com regras simplificadas. Para o caso de *wire_transfers*, *bankslips*, *bill_payments* e *pix*, a resposta dada será baseada no valor da operação (*amount*) enviado na requisição: mínimo | máximo | decisão ------ | ------ | ------- 16000 | - | Contestado Automaticamente* 10000 | 15999 | Aprovado Automaticamente 6000 | 9999 | Derivado para Análise Manual 0 | 5999 | Reprovado Automaticamente \* Contestado Automaticamente está disponível apenas para o serviço de *pix*. Para o caso de *withdrawal* e *deposit* a resposta dada será baseada no valor da operação (*amount*) enviado na requisição: mínimo | máximo | decisão ------ | ------ | ------- 10000 | - | Aprovado Automaticamente 0 | 9999 | Reprovado Automaticamente No caso de operações na DICT, a resposta dada será baseada na chave de vínculo na DICT (*dict_key*) enviada na requisição: chave na Dict | decisão :----------: | ------- "Approve_dict_key" | Aprovado Automaticamente Qualquer outra string | Derivado para Análise Manual "Reprove_dict_key" | Reprovado Automaticamente ## 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. ## Fluxos - Transferências O fluxo de análise de transferências é iniciado em duas situações: - Uma transferência está sendo efetuada pelo usuário do PSP - Uma transferência está sendo recebida pelo usuário do PSP Em ambos os casos, uma chamada ao endpoint de *wire_transfer* deve ser realizada e os possíveis status resultantes são: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente in_manual_analysis | Derivado para Análise Manual pending | O objeto de transferência bancária está sendo processado. Caso a transferência seja derivada para análise manual, um analista deverá aprovar ou reprovar a transferência. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar a transferência por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manual ## Fluxos - Boletos O fluxo de análise de Boletos é iniciado em duas situações: - Um pagamento de boleto está sendo efetuado pelo usuário do PSP - Um pagamento de boleto está sendo recebido pelo usuário do PSP Em ambos os casos, uma chamada ao endpoint de *bankslip* deve ser realizada e os possíveis status resultantes são: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente in_manual_analysis | Derivado para Análise Manual pending | O objeto de boleto está sendo processado. Caso o pagamento de boleto seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manual ## Fluxos - Pagamentos de Contas O fluxo de análise de Pagamentos de Contas é iniciado quando: - Um pagamento de conta está sendo efetuado pelo usuário do PSP Neste caso uma chamada ao endpoint de *bill_payment* deve ser realizada e os possíveis status resultantes são: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente in_manual_analysis | Derivado para Análise Manual pending | O objeto de pagamento de contas está sendo processado. Caso o pagamento de conta seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manual ## Fluxos - Saques O fluxo de análise de Saques é iniciado na seguinte situação: - Um saque está sendo efetuado pelo usuário do PSP Em ambos os casos, uma chamada ao endpoint de *withdrawal* deve ser realizada e os possíveis status resultantes são: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente Caso o saque seja derivado para análise manual, um analista deverá aprovar ou reprovar o saque. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manual ## Fluxos - Transação PIX O fluxo de pagamento PIX é iniciado em duas situações: - Um pagamento sendo efetuado pelo usuário do PSP integrado na QI Tech - Um pagamento sendo recebido de outro PSP Em ambos os casos, uma chamada ao endpoint de pagamento deve ser realizada e os possíveis status resultantes são: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente in_manual_analysis | Derivado para Análise Manual Caso o pagamento seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manualmente ## Fluxos - Alteração na DICT O fluxo de alteração na DICT é iniciado em duas situações: - O usuário do PSP integrado à QI Tech pede um cadastro/alteração/portabilidade/reivindicação ao PSP integrado à QI Tech - Uma portabilidade/reivindicação é recebida pelo PSP integrado à QI Tech Nos cadastros iniciados pelo usuário do PSP, o fluxo de validação de chave deve ser executado antes da alteração na DICT, por meio das APIs de validação da QI Tech. Caso a validação seja realizada pelo próprio PSP, esta informação também pode ser enviada na requisição à QI Tech. Para dar início ao processo, nestes dois momentos o PSP integrado à QI Tech deverá realizar uma chamada no endpoint adequado, que responderá um dos seguintes status: enumerador | descrição :--------: | --------- automatically_approved | Aprovado Automaticamente automatically_reproved | Reprovado Automaticamente in_manual_analysis | Derivado para Análise Manual Caso a alteração seja derivada para análise manual, um analista deverá aprovar ou reprovar a alteração. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar a alteração por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados: enumerador | descrição :--------: | --------- manually_approved | Aprovado Manualmente manually_reproved | Reprovado Manualmente ## 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. ::: --- # Objetos Compartilhados URL: /documentation/caas/banking/objects Boa parte dos dados são compartilhados entre os diferentes eventos de uma conta. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada. ## Objeto Client Request Body ```json { "id": "123456", "type": "natural_person", "document_number": "023.456.789-01", "name": "John Payer", "email": "john@payer.com", "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" } ``` Objeto que representa os dados do detenedor da conta. nome | tipo | descrição :----: | :----: | --------- type | enum *(obrigatório)* | Tipo do cliente: "natural_person" ou "legal_person" document_number | string *(obrigatório)* | Número do documento, de acordo co seção padronização name | string *(obrigatório)* | Nome do cliente email | string | E-mail do cliente address | *address* | Dados de endereço do cliente phone | *phone* | Dados telefônicos do cliente sales_channel | enum *(obrigatório)*| Canal por onde o cliente se cadastrou segment | string *(obrigatório)*| Segmento do cliente dentro da insituição (ex.: premium, gold) Existem os seguintes enumeradores para tipo de telefone: `inbound_sales`, `app`, `website`, `call_center` e `branch` ## Objeto Address Request Body ```json { "street": "Rua do Teste", "number": "111", "neighbourhood": "Bairro do Exemplo", "city": "Aparecida de Goiânia", "uf": "GO", "complement": "Térreo", "postal_code": "00000-000", "country": "BRA" } ``` O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira: nome | tipo | descrição ---- | :----: | --------- street | string *(obrigatório)* | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações. number | string *(obrigatório)* | Número do imóvel, incluindo letras caso possua. neighbourhood | string *(obrigatório)*| Bairro, sem abreviações. **e.g.: Santa Felicidade** city | string *(obrigatório)*| Nome completo da cidade, sem abreviações uf | string *(obrigatório)* | A unidade federativa, com duas letras maiúsculas. **e.g.: SP** complement | string | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12** postal_code | string *(obrigatório)* | O código postal da localidade, contendo o hífen. country | string *(obrigatório)* | Código ISO 3166-1 alfa-3 do país do endereço. No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente. ## Objeto Phone Request Body ```json { "international_dial_code": "1", "area_code": "11", "number": "999999999", "type": "mobile" } ``` Um objeto *phone* representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são: nome | tipo | descrição ---- | :----: | --------- international_dial_code | string *(obrigatório)* | Código de discagem internacional, sem zero ou +, somente números area_code | string *(obrigatório)* | Código de área, sem zero, somente números number | string *(obrigatório)* | Número do telefone, sem o hífen type | enum *(obrigatório)* | Tipo de número: celular, residencial, comercial, etc. Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial` e `mobile`. ## Objeto Account Request Body ```json { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" } ``` Objeto que representa os dados de uma conta. nome | tipo | descrição :----: | :----: | --------- participant | string *(obrigatório)* | ISPB da instituição detentora da conta branch | string *(obrigatório)* | Agência da Conta account_number | string *(obrigatório)* | Número da Conta sem o dígito account_digit | string *(obrigatório)* | Dígito da conta account_type | enum *(obrigatório)* | Tipo da conta de origem, possíveis valores: "CACC", "SLRY" e "SVGS" opening_date | datetime | Data de abertura da conta. ## Objeto Source Request Body ```json { "channel": "app", "platform": "android", "ip":"255.201.26.1", "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a" } ``` O objeto source representa o conjunto de informações da plataforma utilizada pelo usuário para realizar a operação. Os campos são: nome | tipo | descrição :----: | :----: | --------- channel | string | Canal utilizado pelo usuário para realizar a operação, ex.: internet banking, app platform | string | Plataforma utilizada pela aplicação ip | string | IP coletado do device session_id | string | Identificador único da sessão, utilizado para fazer o cruzamento do Device Scan com o evento em questão ## Objeto Dict Key Request Body ```json { "key_type": "cpf", "key_value": "09991222669", "assignment_date": "2020-01-15T18:00:00-03:00" } ``` O objeto **dict_key** é utilizado para representar os dados da chave de vínculo no DICT do cliente, seja ele o recebedor ou o pagador da transação. Os campos desse objeto são: nome | tipo | descrição :----: | :----: | --------- key_type | string *(obrigatório)* | Enumerador que contém o tipo da chave de vinculo no DICT. key_value | string | Contém a chave de vínculo cadastrada no DICT. assignment_date | datetime | Data que a chave de vínculo foi cadastrada no DICT. Os enumeradores para o campo *key_type* são os mesmos definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`. ## Objeto Destination Statistics Request Body ```json { "account":{ "settlements":{ "d3":4, "d30":67, "m6":618 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "owner":{ "settlements":{ "d3":6, "d30":88, "m6":996 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "key":{ "settlements":{ "d3":3, "d30":51, "m6":312 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } } } ``` Para que o risco de fraude em uma transação seja avaliado com maior precisão, é necessário informar o histórico transacional e de fraudes do creditado através do objeto *Destination Statistics*. Tais dados podem ser obtidos ao se consultar a chave de vinculo do creditado na base de dados do DICT. É exigência do BACEN que esses dados sejam utilizados na avaliação de fraude das transações. nome | tipo | descrição :----: | :----: | --------- account | *account* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes da conta do creditado. owner | *owner* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes associados ao documento do creditado. key | *key* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes associados a chave fornecida pelo creditado. Onde cada um dos objetos definidos acima possui os mesmos campos: nome | tipo | descrição :----: | :----: | --------- settlements | *settlements* *(obrigatório)* | Objeto que contém o histórico transacional. rejected | *rejected* *(opcional)* | Objeto que contém o histórico de operações negadas. reported_frauds | *reported_frauds* *(obrigatório)* | Objeto que contém o histórico de relatos de fraudes. reported_aml_cft | *reported_aml_cft* *(opcional)* | Objeto que contém o histórico de relatos de PLD/FT. confirmed_frauds | *confirmed_frauds* *(obrigatório)* | Objeto que contém o histórico de relatos de fraudes confirmados. confirmed_aml_cft | *confirmed_aml_cft* *(opcional)* | Objeto que contém o histórico de relatos de PLD/FT confirmados. Onde cada um desses objetos contém os campos **d3**, **d30** e **m6**, contendo o número de ocorrências nos ultimos 3 dias, 30 dias e 6 meses, que são campos obrigatórios, respectivamente. Da mesma forma que é definido pela API do DICT do BCB. --- # PIX Dict Operation URL: /documentation/caas/banking/pix_dict_operations No momento em que o usuário iniciar uma mudança na DICT, os dados deverão ser enviados para o nosso servidor, de maneira que possamos realizar uma análise do risco envolvido naquele conjunto de dados. ## Definição do Objeto de Dict Operation Request Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", "dict_key": { "key_type": "phone", "key_value": "16981610077", "assignment_date": "2020-01-15T18:00:00-03:00" }, "dict_operation_direction": "claimer", "dict_operation_reason": "user_requested", "dict_operation_creation_date": "2020-10-14T18:00:00-03:00", "dict_operation_type": "claim_portability", "client": { "id": "123456", "document_number": "099.912.226-69", "name": "João Jorge da Silva", "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": "65", "number": "988961210", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "source_account": { "participant": "04184779", "branch": "0001", "account_number": "1122", "account_digit": "6", "owner": { "type": "legal_person", "document_number": "94.948.708/0001-12", "name": "Irmão Soares Ferragista LTDA." }, "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_account": { "participant": "00000000", "branch": "3675", "account_number": "10442", "account_digit": "6", "owner": { "type": "natural_person", "document_number": "099.912.226-69", "name": "João Jorge da Silva" }, "account_type": "SLRY", "opening_date": "2020-01-15T18:00:00-03:00" }, "destination_statistics": { "account":{ "settlements":{ "d3":12, "d30":65, "m6":344 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "owner":{ "settlements":{ "d3":4, "d30":12, "m6":88 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } }, "key":{ "settlements":{ "d3":1, "d30":6, "m6":12 }, "rejected":{ "d3":4, "d30":67, "m6":618 }, "reported_frauds":{ "d3":0, "d30":0, "m6":0 }, "reported_aml_cft":{ "d3":0, "d30":0, "m6":0 }, "confirmed_frauds":{ "d3":0, "d30":0, "m6":0 }, "confirmed_aml_cft":{ "d3":0, "d30":0, "m6":0 } } }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065-98", "session_id": "7839jdqd9a8wd9" } } ``` Uma Dict Operation deve ser enviada para a API antes de ser encaminhada para o sistema de processamento do BCB, a fim de realizar uma validação prévia de fraude de cadastro. O status da análise da Dict Operation representa a decisão retornada pelo modelo sobre aquela operação. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que esta operação seja aprovada. automatically_reproved | Recomenda-se que esta operação seja reprovada. in_manual_analysis | Recomenda-se que a operação seja analisada manualmente por um analista. pending | A operação está sendo processada. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador da operação no sistema do cliente. **É essencial que este número seja único para cada processo de autorização** client | *client* | Objeto que representa os dados do cliente, seja ele o doador ou o recebedor. transaction_date | datetime | A data e hora de início da transação, com fuso horário. dict_key | *dict_key* | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação. dict_key_type | enumerador | Tipo da chave de vínculo ao DICT. dict_operation_direction| enumerador | Direção de operação no DICT, isto é, se uma chave está sendo cedida ou obtida. dict_operation_reason | enumerador | A razão pelo qual a Operação na Dict está sendo realizada. dict_operation_creation_date | datetime | Data da operação no DICT. dict_operation_type | enumerador | Tipo de operação no DICT. source_account | *source_account* | Objeto que representa os dados da conta que está cedendo a chave de vínculo. destination_account | *destination_account* | Objeto que representa os dados da conta que está recebendo a chave de vínculo. destination_statistics | *destination_statistics* | Objeto que representa o histórico de transações e fraudes da conta que esta recebendo a chave de vinculo. source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do cadastro O campo *dict_key_type* aceita os mesmos enumeradores definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`. O campo *dict_operation_direction* aceita os enumeradores: `donor` e `claimer`. O campo *dict_operation_type* aceita os enumeradores `registration`, `claim_ownership` e `claim_portability`. Sendo estas todos os tipos de operações na DICT definidas pelo BCB. ## Enviar uma Dict Operation Request Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", ... } ``` Response Body ```json { "dict_operation_key": "7f85e162-5a7d-41fa-a578-69df6f3df958", "status": "automatically_approved" } ``` Para realizar a avaliação de um pagamento, basta enviar um objeto do tipo Payment ao seguinte endpoint: `POST https://api.caas.qitech.app/pix/dict_operation` ## Recuperar uma Dict Operation Response Body ```json { "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5", ... } ``` Para recuperar uma Dict Operation, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}` Onde *dict_operation_id* é o identificador da operação que nos foi enviado no momento do cadastro desta, no campo "id". Será, então, retornado o objeto Dict Operation associado a chave provida. ## Atualizar uma Dict Operation Request Body ```json { "dict_operation_status": "cancelled_by_client", "reason": "user_requested", "event_date": "2020-10-07T15:06:25-03:00" } ``` Uma Dict Operation possui várias fases junto ao BCB antes que seja concluída. Deste modo, é necessário que sejam informadas todas as atualizações de status das operações, através do endpoint: `PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}` Deste modo, garate-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB. Algumas operações na DICT demandam que seja submetida a razão da operação juntos dos dados. Para estes casos, é necessário informar o campo *reason* no objeto de envio, contendo o mesmo enumerador provido ao sistema do BCB. São esses: enumerador | descrição :--------: | --------- user_requested | A operação foi requisitada pelo cliente. account_closure | A operação foi iniciada devido ao fechamento da conta do cliente. branch_transfer | A operação foi requisitada devido a mudança de agência do cliente. entry_inactivity | A operação foi requisitada devido a inatividade na conta do cliente. reconciliation | A operação foi requisitada após um processo de reconcialiation. default_operation | A operação foi requisitada por uma ação padrão do participante. fraud | A operação foi requisitada devido a um fraude ligada a conta do cliente. As fases de uma operação na DICT aceitas pelo campo *dict_operation_status* são: enumerador | descrição :--------: | --------- created | A dict_operation foi criada mas ainda não foi analisada. reproved | A dict_operation foi reprovada na análise e não será enviada ao BCB. waiting_resolution | A dict_operation foi enviada ao BCB e está esperando a resolução. cancelled_by_client | A dict_operation foi cancelada pelo cliente. cancelled_by_counterpart | A dict_operation foi cancelada pela outra parte da operação. confirmed | A dict_operation foi confirmada pela outra parte da operação. completed | A dict_operation foi completada e adicionada a base de dados do BCB. --- # PIX Infraction Report URL: /documentation/caas/banking/pix_infraction_reports ## Definição do Objeto de Infraction Reports Request Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00", "infraction_report_status": "received", "infraction_report_events": [ { "new_status": "received", "event_date": "2020-10-14T00:25:42-03:00" } ] } ``` Caso algum comportamento suspeito seja dectado por qualquer uma das partes da transação, um Infraction Report pode ser criado para relatar a suspeita. Esse Infraction Report será então analisado pela outra parte e poderá ser confimado ou não. Seguindo o padrão estabelecido pelo BCB, um Infraction Report deverá ter os campos: nome | tipo | descrição :----: | :----: | --------- infraction_report_type | enumerador | Enumerador que define o tipo de atividade suspeita presente na transação. infraction_report_details | string | Detalhes das circustâncias que levaram o criador do Infraction Report a acreditar que possa existir algum tipo de infração associada a transação. infraction_report_creator | enumerador | Enumerador que define quem criou o Infraction Report. infraction_report_date | datetime | Data do incidente. O campo *infraction_report_type* poderá conter os enumeradores: `fraud` e `compliance`. O campo *infraction_report_creator* poderá conter os enumeradores: `client` e `external`. ## Enviar um Infraction Report Request Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00" } ``` Response Body ```json { "infraction_report_key": "7f85e162-5a7d-41fa-a578-69df6f3df958", "infraction_report_status": "received" } ``` Para realizar a o envio de um Infraction Report, basta enviar uma requisição ao endpoint: `POST https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report` Onde *transaction_id* é o identificador da transação que nos foi enviado no momento do cadastro desta, no campo "id". ## Recuperar um Infraction Report Response Body ```json { "infraction_report_type": "compliance", "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ", "infraction_report_creator": "external", "infraction_report_date": "2020-10-14T00:25:42-03:00", "infraction_report_status": "received", "infraction_report_events": [ { "new_status": "received", "event_date": "2020-10-14T00:25:42-03:00" } ], "transaction_data": { "transaction_direction": "received", "id": "082373263", ... } } ``` Para recuperar um Infraction Report, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}` Será, então, retornado o objeto Infraction Report associado o *transaction_id* provido e com *infraction_report_key* idêntica a chave enviada. ## Atualizar um Infraction Report Request Body ```json { "infraction_report_status": "acknowledged", "event_date": "2020-10-07T15:06:25-03:00" } ``` Um Infraction Report possui várias fases junto ao BCB antes que seja concluído. Deste modo, é necessário que sejam informadas todas as atualizações de status do Infraction Report, através do endpoint: `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}` --- # PIX Transaction URL: /documentation/caas/banking/pix_transactions No momento em que o pagador iniciar ou receber um pagamento, os dados da transação deverão ser enviados para o nosso servidor. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados. ## Definição do Objeto de Pix Transactions Request Body ```json { "transaction_direction": "received", "id": "082373263", "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" }, "email": "mailto@qitech.com.br", "phone": { "international_dial_code": "55", "area_code": "16", "number": "981610077", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "amount": 13725, "transaction_date": "2020-10-07T15:06:25-03:00", "dict_key": { "key_type": "cpf", "key_value": "09991222669", "assignment_date": "2020-01-15T18:00:00-03:00" }, "capture_method": "static_qr_code", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "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" } } ``` Uma transação deve ser enviado 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` * `in_manual_analysis` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvida 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. approved_by_time | A transação foi aprovada por expiração de tempo de análise manual reproved_by_time | A transação foi aprovada por expiração de tempo de análise manual in_manual_analysis | Recomenda-se que a transação seja analisada manualmente por um analista. pending | A transação está sendo processada. nome | tipo | descrição :----: | :----: | --------- transaction_direction | enumerador | Tipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. *(obrigatório)* id | string | Identificador do pagamento no sistema do cliente. **É essencial que este número seja único para cada processo de pagamento** *(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. transaction_date | datetime | A data e hora de início da transação, com fuso horário. *(obrigatório)* dict_key | *dict_key* | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação. capture_method | enumerador | Método utilizado para iniciação do pagamento, se foi via QR Code estático ou dinâmico, via preenchimento de dados ou via chave da DICT. *(obrigatório)* face_recognition_key | string | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial. validation_key | string | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações. 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. *(obrigatório)* source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento Existem os seguintes enumeradores para *transaction_direction*: `sent` e `received`. Existem os seguintes enumeradores para *pix_modality*: `transacation`, `change` e `withdraw`. Existem os seguintes enumeradores para *capture_method*: `static_qr_code`, `dynamic_qr_code`, `offline_qr_code`, `typed`. ## Enviar uma Transação Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "analysis_status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a avaliação de uma transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint: `POST https://api.caas.qitech.app/pix/transaction` ## Recuperar uma Transação Response Body ```json { "transaction_direction": "received", "id": "082373263", ... } ``` Para recuperar os dados de uma transação, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/pix/transaction/{transaction_id}` Onde *transaction_id* é o identificador da transação que nos foi enviado no momento do cadastro, no campo "id". ## Atualizar uma Transação Request Body ```json { "transaction_status": "sent", "event_date": "2020-10-07T15:06:25-03:00" } ``` Após uma transação ser criada e analisada, ela deve ser enviada ao BCB para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transação quando essa for enviada ao BCB, através do endpoint: `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}` Deste modo, garante-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB. ## Transação não efetivada Request Body ```json { "transaction_status": "cancelled", "reason": "refused_by_counterpart", "event_date": "2020-10-07T15:06:25-03:00" } ``` Caso uma transação, por qualquer motivo, não tenha sido efetivada (i.e.: Saldo debitado da conta de origem e creditado na conta de destino), a transação pode ser atualizada para o status `cancelled`, com a razão do cancelamento para que seja possível identificar perfis de fraude relacionados a transação não efetivadas. O status cancelled só pode ser utilizado em transações que ainda possuem o status created, uma vez que o status `sent` é utilizado nos casos em que a transação foi evetivada. `PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}` As seguintes reasons são atualmente aceitas pela API, caso você veja a necessidade de enquadrar o motivo do cancelamento em outra reason, por favor, entre em contato com suporte.caas@qitech.com.br. reason | descrição :----: | --------- insufficient_balance | O cliente não possui saldo na conta para realizar a transação fraud_prevention | A transação foi cancelada pois não foi aprovada no sistema antifraude system_block | Algum bloqueio de sistema não permitiu a execução da transação, por exemplo conta cancelada/inativa ou limite alcançado invalid_destination | A instituição contraparte não aceitou a transação pois a conta de destino não existe refused_by_counterpart | A instituição contraparte rejeitou a transação system_error | A transação foi cancelada pois houve um erro no sistema da própria instituição invalid_authentication | A transação foi cancelada pois o cliente não passou em algum fluxo de autenticação --- # Padrões URL: /documentation/caas/banking/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 ``` 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` --- # Webhook URL: /documentation/caas/banking/webhook Atualizações no status de fraude (Para eventos que sejam derivados para análise manual ou que sejam respondidos como Pendente), 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. 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 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. Exemplos de endpoints para atualização de evento: * https://apidocliente.com.br/\{evento\} * https://apidocliente.com.br/admin/\{evento\}/123456 O campo \{evento\}, localizado na URL da requisição, pode assumir os seguintes valores, a depender do evento sendo notificado: * bill_payment * bankslip * wire_transfer * withdrawal * pix O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado. ## 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 --- # Transferências URL: /documentation/caas/banking/wire_transfers No momento em que um usuário efetuar ou receber uma transferência, os dados da transferência deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados. ## Definição do Objeto de Transferência Request Body ```json { "id": "082373263", "wire_transfer_direction": "received", "wire_transfer_type": "ted", "amount": 13725, "wire_transfer_date": "2020-10-07T15:06:25-03:00", "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222", "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d", "client": { "type": "natural_person", "id": "123456", "document_number": "056.966.649-03", "name": "Francisco Oliveira Benedetti", "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" }, "email": "mailto@qitech.com.br", "sales_channel": "inbound_sales", "segment": "Personalité" }, "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" }, "source": { "channel": "internet_banking", "platform": "android", "ip": "198.185.065.098", "session_id": "7839jdqd9a8wd9" } } ``` Uma transferência deve ser enviado 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 transferência representa a decisão retornada pelo modelo sobre aquela transferência. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` * `in_manual_analysis` * `pending` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que esta transferência seja aprovada. automatically_reproved | Recomenda-se que esta transferência seja reprovada. in_manual_analysis | Recomenda-se que a transferência seja analisada manualmente por um analista. pending | A transferência está sendo processada. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada transferência** wire_transfer_direction | enumerador | Modalidade da transferência cadastrada. Define se o cliente está recebendo ou enviando dinheiro. wire_transfer_type | enumerador | Tipo da transferência realizada, podendo ser uma TED, um DOC ou uma transferência interna entre contas da mesma instituição. amount | inteiro | O valor da transferência em centavos - conforme descrição da seção "Padrões". wire_transfer_date | datetime | A data e hora de início da transferência, com fuso horário. face_recognition_key | string | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial. validation_key | string | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações. client | *client* | Objeto que representa os dados do cliente, seja ele o cliente que está efetuando a transferência ou o recebedor. source_account | *source_account* | Objeto que representa os dados da conta debitada. destination_account | *destination_account* | Objeto que representa os dados da conta creditada. source | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio da transferência Existem os seguintes enumeradores para *wire_transfer_direction*: `sent` e `received`. Existem os seguintes enumeradores para *wire_transfer_type*: `ted`, `doc`, `internal_transfer`. ## Enviar uma Transferência Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a avaliação de uma transferência, basta enviar um objeto do tipo Wire Transfer ao seguinte endpoint: `POST https://api.caas.qitech.app/wire_transfer/wire_transfer` ## Recuperar uma Transferência Response Body ```json { "id": "082373263", "wire_transfer_direction": "received", ... } ``` Para recuperar os dados de uma transferência, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}` Onde *wire_transfer_id* é o identificador da transação no sistema do cliente utilizado no envio da transferência. ## Atualizar uma transferência Request Body ```json { "wire_transfer_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "wire_transfer_status": "completed" } ``` Após uma transferência ser criada e analisada, ela será enviado à câmara de compensação para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transferência quando esta for enviada, através do endpoint: `PUT https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}` Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar as transferências que estejam realmente sucetíveis a fraude. --- # Saques URL: /documentation/caas/banking/withdrawals No momento em que um usuário efetuar um saque, os dados do saque deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados. ## Definição do Objeto de Saque Request Body ```json { "id": "082373263", "amount": 12979, "withdrawal_date": "2020-10-07T15:06:25-03:00", "service_description": "SAQUE EM CAIXA 24H", "source_account": { "participant": "17315359", "branch": "0000", "account_number": "10442", "account_digit": "6", "account_type": "CACC", "opening_date": "2020-01-15T18:00:00-03:00" }, "client": { "id": "182373263", "type": "natural_person", "document_number": "023.456.789-01", "name": "John Payer", "email": "john@payer.com", "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "phone": { "international_dial_code": "55", "area_code": "11", "number": "998861708", "type": "mobile" }, "sales_channel": "inbound_sales", "segment": "Personalité" }, "terminal": { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" }, "authentication": { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } } ``` Um saque deve ser enviado 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 do saque representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**: * `automatically_approved` * `automatically_reproved` Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status: status | descrição :----: | --------- automatically_approved | Recomenda-se que este saque seja aprovado. automatically_reproved | Recomenda-se que este saque seja reprovado. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do saque no sistema do cliente. **É essencial que este número seja único para cada saque** amount | inteiro | Valor do saque em centavos - conforme descrição da seção "Padrões". withdrawal_date | datetime | Data e hora da realização do saque - conforme descrição da seção "Padrões" source_account | *account* | Objeto que determina a conta de origem do recurso a ser sacado client | *client* | Objeto com os dados do cliente detentor da conta de origem terminal | *terminal* | Objeto com os dados do terminal onde o saque está sendo realizado authentication | *authentication* | Objeto com as informações de autenticação ## Objetos do Saque ### Objeto Terminal Request Body ```json { "id": "1234566", "latitude": -45.2753548, "longitude": -15.24587, "address": { "street": "Av. Eng. Luis Carlos Berrini", "number": "105", "neighbourhood": "Brooklin", "city": "São Paulo", "uf": "SP", "complement": "Cj 303", "postal_code": "04501-140" }, "type": "atm" } ``` Objeto que representa o terminal que foi utilizado para o saque. nome | tipo | descrição :----: | :----: | --------- id | string | Identificador do terminal no sistema do cliente latitude | number | Latitude, em graus, da localização do terminal longitude | number | Longitude, em graus, da localização do terminal address | *address* | Endereço do terminal type | enum | Tipo do terminal, possíveis valores: "atm", "counter" ### Objeto Authentication Request Body ```json { "used_password": true, "used_card": true, "used_fingerprint": true, "typed_account_number": false } ``` Objeto que define os parâmetros da autenticação utilizada no momento do saque. nome | tipo | descrição :----: | :----: | ----------- used_password | boolean | Determina se o usuário utilizou senha used_card | boolean | Determina se o usuário está com o cartão presente na autenticação used_card_chip_and_pin | boolean | Determina se o usuário utilizou o chip e senha do cartão used_card_magnetic_stripe | boolean | Determina se o usuário utilizou a tarja magnética do cartão used_fingerprint | boolean | Determina se o usuário utilizou fingerprint typed_account_number | boolean | Determina se o usuário digitou os dados da conta ## Enviar um Saque Request Body ```json { "id": "12345", ... } ``` Response Body ```json { "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "status": "automatically_approved", "reason": "rule_decision_enum" } ``` Para realizar a avaliação de um pagamento de conta, basta enviar um objeto do tipo withdrawal ao seguinte endpoint: `POST https://api.caas.qitech.app/withdrawal/withdrawal` ## Recuperar um Saque Request Body ```json { "id": "082373263", "amount": 12979, ... } ``` Para recuperar os dados de um saque, basta enviar uma requisição ao seguinte endpoint: `GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}` Onde *withdrawal_id* é o identificador da transação no sistema do cliente utilizado no envio do saque. ## Atualizar um saque Request Body ```json { "withdrawal_status": "completed", "event_date": "2020-10-07T15:06:25-03:00" } ``` Response Body ```json { "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf", "withdrawal_status": "completed" } ``` Após um saque ser criada e analisada, o dinheiro será disponibilizado ao usuário. Este processo pode ser interrompido por alguma outra regra de negócio. Deste modo, é necessário que seja informada a atualizações de status do saque quando este for finalizado, através do endpoint: `PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}` Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os saques que estejam realmente sucetíveis a fraude.