RentalAgreement-v2

Esta seção diz respeito ao fluxo de análise de fraude com a scoragem principal ocorrendo na reserva.

Ao realizar a retirada de um veículo na loja, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais, 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 um RentalAgreement 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 RentalAgreement 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 - car_status

O status car_status relacionado a um RentalAgreement indica a situação do carro relacionado a este aluguel, isto é, se o carro foi devolvido ou não. Os seguintes enumeradores existem para este status:

rented
returned
recovered
written_off

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
manually_challenged
pending
not_analyzed

Além disso, o upgrade_status também possui os mesmos enumeradores.

Definição do Objeto

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "rental_agreement_code" : "12345678",
  "rental_agreement_date": "2020-03-31T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2020-04-01T10:28:00-03:00",
  "reservation": {
    "id": "0",
    "channel": "reservation_central",
    "reservation_date": "2020-03-31T08:15:00-03:00",
    "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": "AM",
    "upgrade_model_group": "SV",
    "rental_daily_price" : 48496,
    "risky_model_group": true,
    "risky_upgrade_model_group": true
  },
  "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",
  "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,
  "free_day_discount": 20000,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0,
  "upgrade_reason": "granted"
}

Todas as trocas de informação de um RentalAgreement 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 aluguel. (obrigatório)
rental_agreement_code	string	Identificador do RentalAgreement no sistema do cliente. (obrigatório)
rental_agreement_date	DateTime	Data e Hora com fuso-horário da retirada do veículo do aluguel que está ocorrendo. (obrigatório)
car_rental_estimated_final_date	DateTime	Data e Hora com fuso-horário de quando o carro deve ser resolvido. (obrigatório)
reservation	reservation	Objeto que carrega as propriedades da reserva que deu origem a esse aluguel. (obrigatório)
rental_store	store	Loja onde o carro está sendo retirado. (obrigatório)
rental_store_group	store	Filial da loja onde o carro está sendo 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)
car	car	Carro que está sendo retirado - é importante que este valor seja, de fato, o carro sendo retirado. (obrigatório)
client	client	Objeto que carrega as informações do cliente que está retirando o 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.
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. (obrigatório)
additional_driver_price	integer	Preço total do(s) motoristas adicionais contratados, em centavos.
driver_service_price	integer	Preço total do serviço de motorista contratado, em centavos.
additional_expenses	integer	Despesas adicionais, em centavos
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.
free_day_discount	integer	Desconto de Free Day, em centavos.
final_price	integer	Preço final do aluguel, em centavos. (obrigatório)
pre_authorization_amount	integer	Valor da pré-autorização, em centavos.
coverage_deductible_amount	integer	Valor dedutível da cobertura, em centavos. (obrigatório)
upgrade_reason	enum	Tipo de upgrade (Concedido ou Comprado) - Aceita os valores `granted` e `bought` respectivamente

Enviar um RentalAgreement

Exemplo de Request:

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

Exemplo de Retorno:

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "pre_authorization_amount": 100000,
  "block_document_number": true,
  "upgrade_status": "automatically_approved",
  "highest_allowed_car_group": "SV",
  "score": 870
}

Para realizar a avaliação de um aluguel, basta enviar um objeto do tipo RentalAgreement ao seguinte endpoint com a flag setada adequadamente:

POST https://api.caas.qitech.app/car_rental/rental_agreement?analyze=true

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.

O grupo máximo que pode ser fornecido naquele RA é disponibilizado na variável highest_allowed_car_group. Este valor é configurado na regra de avaliação do RA.

O parâmetro analyze existe para evitar que transações que não precisam ser analisadas passem pelos motores de fraude, sujando a base de dados. O valor padrão deste parâmetro é true, de maneira que somente alugueis que forem explícitamente retirados da análise não serão analisados.

Atualizar o status de um RentalAgreement

Corpo da requisição - Na efetivação de um aluguel de um carro:

{
  "car_status": "rented",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Corpo da requisição - Na devolução sem incidentes de um carro:

{
  "car_status": "returned",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Corpo da requisição - Na devolução mediante recuperação por roubo:

{
  "car_status": "recovered",
  "incident": "theft",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Corpo da requisição - Write-off com fraude confirmada:

{
  "car_status": "written_off",
  "incident": "misappropriation",
  "event_date": "2019-11-05T13:34:12-03:00"
}

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando os carros são alugados, devolvidos, ou quando são jogados a perda por fraude. Para isso, requisições com o método PUT devem ser utilizadas, passando-se como referência o id enviado na criação do rental_agreement, autenticadas normalmente:

PUT https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}

Caso o novo status seja written_off, os seguintes valores podem ser utilizados no campo incident, enviado no body da requisição, que indica o tipo de incidente do aluguel:

Enumerador	Descrição
theft	RAs que sofreram um roubo
misappropriation	RAs que foram classificados como apropriação indébita

Atualizar o veículo de um RentalAgreement

Corpo da requisição - Atualização de um veículo no aluguel:

{
  "car_plate": "ABC1B34",
  "car_model": "Chevrolet Onix",
  "model_group": "B",
  "event_date": "2020-10-15T13:34:12-03:00"
}

Para garantir a consistência entre as ocorrências de fraude e os aluguéis e garantir o retreinamento do modelo de score, é necessário informar ao sistema os dados de cada carro quando ele é atrelado ao aluguel. Para isso, requisições com o método POST devem ser utilizadas, passando-se como referência o id enviado na criação do rental_agreement, autenticadas normalmente:

POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/car

No body da requisição devem ser enviados os dados do veículo que está sendo atrelado àquele aluguel:

nome	tipo	descrição
car_plate	string	Placa do veículo.
car_model	string	Modelo do veículo, incluindo sua marca e modelo (ex.: Jeep Renegade).
model_group	string	O grupo do veículo, em letras maiúsculas.
event_date	DateTime	Data e Hora com fuso-horário do momento em que ocorreu a associação do carro ao aluguel.

Recuperar um RentalAgreement

A fim de recuperar um RentalAgreement específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do RentalAgreement 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/rental_agreements/{rental_agreement_id}

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

Buscar RentalAgreements

Retorno - uma lista de objetos RentalAgreement:

[
  {
    "id": "bca6268e-918a-4658-9161-a10b00a631ab",
    ...
  },
  {
    "id": "13a91409-9793-49b6-8583-9ba575075831",
    ...
  }
]

Caso seja necessário buscar um RentalAgreement, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de RentalAgreements. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.

GET https://api.caas.qitech.app/car_rental/rental_agreements?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20

Os seguintes parâmetros podem ser utilizados para buscar objetos de RentalAgreement:

Parâmetro	Padrão	Descrição
initial_date	null	Primeira data que deve ser retornada a partir do campo rental_agreement_date
final_date	null	Última data que deve ser retornada a partir do campo rental_agreement_date
store_code	null	Código da loja de onde os resultados devem ser retornados
page_number	1	Número da página de resultados desejada
page_rows	50	Número de objetos máximo a ser retornados em uma consulta

Dinâmica dos Status​

Dinâmica dos Status - car_status​

Dinâmica dos Status - fraud_status​

Definição do Objeto​

Enviar um RentalAgreement​

Atualizar o status de um RentalAgreement​

Atualizar o veículo de um RentalAgreement​

Recuperar um RentalAgreement​

Buscar RentalAgreements​