Reservation-v2

Esta seção diz respeito às informações necessárias para o fluxo de análise de fraude primariamente na reserva.

Ao realizar a reserva de um veículo, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais da reserva, que não serão alterados. Isto é importante para garantir dois pontos:

Consistência dos dados na base de dados do Antifraude
Avaliação realista do risco

O processo de análise consiste em enviar uma Reservation no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag fraud_status:

Resultado	Descrição
Aprovado Automaticamente	Recomenda-se que este aluguel seja aprovado
Negado Automaticamente	Recomenda-se que este aluguel seja reprovado
Derivado para análise manual	Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual.
Aprovado Manualmente	Após análise manual, o analista escolheu aprovar o aluguel
Reprovado Manualmente	Após análise manual, o analista escolheu reprovar o aluguel
Desafiado Manualmente	Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade
Pendente	As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook
Não analisado	A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer

Dinâmica dos Status

Ao recuperar um objeto do tipo Reservation os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

Dinâmica dos Status - fraud_status

O status fraud_status indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

created
automatically_approved
automatically_reproved
in_manual_analysis
manually_approved
manually_reproved
pending
not_analyzed

Definição do Objeto

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  "reservation_date": "2024-03-19T10:30:00-03:00",
  "rental_agreement_date": "2024-03-25T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2024-03-30T10:28:00-03:00",
  "channel": "reservation_central",
  "sales_channel" : "PARCERIA TELEFONICA",
  "rental_store": "SAOP",
  "rental_store_group": "GSP",
  "rental_store_type": "LOJA DE RUA",
  "devolution_store": "SAOP",
  "risky_antecedence": true,
  "car": {
    "model_group": "SV",
    "rental_daily_price" : 48496
  },
  "client": {
    "type": "natural_person",
    "segment": "ota",
    "document_number": "123.456.789-00",
    "name": "John Sample",
    "gender": "female",
    "birthdate": "2001-01-15",
    "mother_name": "Mary Sample",
    "email": "john.sample@sample.com.br",
    "allowed_information_on_email": true,
    "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
    "additional_pictures": [
      "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
      "9c67f365-1427-4889-b963-d3729d437ff3",
      "8006f82c-3a80-4371-914e-e88c91507711",
      "42c6909e-51aa-4b6d-972f-f4684a047993",
      "b7a88947-96bd-4557-81e9-a69a3c84f428"
    ],
    "total_rents": 6,
    "fidelity_points": 1200,
    "documents": {
      "rg": {
        "document_number": "00000000",
        "issuer": "SSP"
      },
      "cnh": {
        "document_number": "000000000",
        "security_code": "00000",
        "first_issuance": "2015-07-20",
        "expiration_date": "2030-07-26",
        "state": "SP"
      }
    },
    "residential_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "commercial_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "mobile"
      },
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "residential"
      }
    ]
  },
  "coverages": [
    {
      "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
      "price": 0
    },
    {
      "description": "PROTEÇÃO OCUPANTES E TERCEIROS",
      "price": 1668
    }
  ],
  "billing": {
    "name": "Agência AAA",
    "document_number": "00.000.000/0001-00",
    "voucher_type": "ABCD75",
    "voucher_description": "Pagamento pela agência"
  },
  "fare_name": "MENSAL - 2000KM - PRÓ-RATA",
  "rental_price": 43300,
  "extra_hours": 0,
  "extra_hours_price": 0,
  "discount": 0,
  "prepayment_discount": 100,
  "extra_kms": 0,
  "extra_kms_price": 0,
  "third_party_coverage_price": 1490,
  "coverage_price": 0,
  "additional_driver_price": 1000,
  "driver_service_price": 1000,
  "additional_expenses": 1000,
  "devolution_fee": 0,
  "administration_fee": 5374,
  "discount_partial_coverage": 50,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0
}

Todas as trocas de informação de uma Reservation 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
id	string	Identificador da requisição de análise no sistema do cliente. É essencial que este número seja único para cada análise. (obrigatório)
reservation_code	string	Identificador da Reserva no sistema do cliente. - Este campo é opcional e pode ser definido utilizando o método PUT.
reservation_date	DateTime	Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. (obrigatório)
car_rental_estimated_final_date	DateTime	Data e Hora com fuso-horário de quando o carro deve ser resolvido. (obrigatório)
rental_store	store	Loja onde o carro será retirado. (obrigatório)
rental_store_group	store	Filial da loja onde o carro será retirado
rental_store_type	store	Tipo da loja onde o carro será retirado
devolution_store	store	Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. (obrigatório)
reservation_channel	string	Canal pelo qual foi feito a reserva para este aluguel.
sales_channel	string	Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD). (obrigatório)
car	car	Objeto que carrega as informações do veículo sendo reservado. (obrigatório)
client	client	Objeto que carrega as informações do cliente que fará a retirada do veículo. (obrigatório)
coverages	List of coverage	Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. (obrigatório)
billing	billing	Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. (obrigatório)
rental_price	integer	Preço do aluguel, em centavos. (obrigatório)
extra_hours	integer	Quantidade de horas extras contratadas. (obrigatório)
extra_hours_price	integer	Preço das horas extras contratadas, em centavos. (obrigatório)
discount	inteiro	Desconto concedido por quaisquer motivos, em centavos. (obrigatório)
prepayment_discount	inteiro	Desconto por pagamento antecipado. (obrigatório)
extra_kms	integer	Quantidade de kilômetros extras contratados. (obrigatório)
extra_kms_price	integer	Preço de kilômetros extras contratados, em centavos. (obrigatório)
third_party_coverage_price	integer	Preço do seguro de terceiros, em centavos. (obrigatório)
coverage_price	integer	Preço do seguro contratado, em centavos.
additional_driver_price	integer	Preço total do(s) motoristas adicionais contratados, em centavos. (obrigatório)
driver_service_price	integer	Preço total do serviço de motorista contratado, em centavos. (obrigatório)
additional_expenses	integer	Despesas adicionais, em centavos. (obrigatório)
devolution_fee	integer	Preço da taxa de devolução, em centavos. (obrigatório)
administration_fee	integer	Preço da taxa de administração, em centavos. (obrigatório)
discount_partial_coverage	integer	Desconto de proteção parcial, em centavos. (obrigatório)
final_price	integer	Preço final do aluguel, em centavos. (obrigatório)
pre_authorization_amount	integer	Valor da pré-autorização, em centavos. (obrigatório)
coverage_deductible_amount	integer	Valor dedutível da cobertura, em centavos. (obrigatório)

Enviar uma Reserva

Exemplo de Request:

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  ...
}

Exemplo de Retorno:

{
  "reservation_key": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "pre_authorization_amount": 10000
}

Para realizar a avaliação de uma reserva, basta enviar um objeto do tipo Reservation ao seguinte endpoint:

POST https://api.caas.qitech.app/car_rental/reservation

Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.

Definir o código de uma Reserva

A QI Tech possibilita a definição do código da reserva após a análise inicial. Isto é útil em alguns fluxos operacionais. Nestes casos, basta realizar um PUT no endpoint a seguir, com o código da reserva definido no corpo:

PUT https://api.caas.qitech.app/car_rental/reservation/{reservation_id}

observação

Caso o código da reserva tenha sido definido anteriormente, na requisição de POST ou utilizando um PUT, não é possível redefinir o código da reserva. Neste caso, a API retornará 409 - Conflito.

{
  "reservation_code": "123456789"
}

Recuperar uma Reserva

A fim de recuperar uma Reserva específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Reserva em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

GET https://api.caas.qitech.app/car_rental/reservation/{reservation_id}

curl "https://api.caas.qitech.app/car_rental/reservation/{reservation_id}"
  -H "Authorization: TESTETESTETESTE"

Dinâmica dos Status​

Dinâmica dos Status - fraud_status​

Definição do Objeto​

Enviar uma Reserva​

Definir o código de uma Reserva​

Recuperar uma Reserva​