RentalAgreement-v1

When picking up a vehicle at the store, the renter starts their anti-fraud process. The data sent must be the final data, which will not be changed. This is important to guarantee two things:

Consistency of the data in the Anti-fraud database
A realistic risk assessment

The analysis process consists of sending a RentalAgreement to the appropriate endpoint and waiting for the response. There are eight possible results, returned in the fraud_status flag:

Result	Description
Automatically Approved	We recommend that this rental be approved
Automatically Denied	We recommend that this rental be rejected
Sent to manual analysis	Our rules or models are not confident about the decision and decided to send this rental to manual analysis.
Manually Approved	After manual analysis, the analyst chose to approve the rental
Manually Rejected	After manual analysis, the analyst chose to reject the rental
Manually Challenged	After manual analysis, the analyst informs the store that the driver's license and/or the selfie are incorrect and/or of low quality
Pending	The queries are taking longer than expected, this rental entered an automatic analysis queue and will be answered through a Webhook
Not analyzed	The request was sent with the analysis flag set to false, which means our systems must not return a decision

Status Dynamics

When retrieving a RentalAgreement object, the statuses are available. In addition to the statuses, a history of changes is also returned so that it can be consulted in the future. These changes are called events and carry, besides the new status, the modification dates.

Status Dynamics - car_status

The car_status status related to a RentalAgreement indicates the situation of the car related to this rental, that is, whether the car was returned or not. The following enumerators exist for this status:

rented
returned
recovered
written_off

Status Dynamics - fraud_status

The fraud_status status indicates the status of the fraud engine's decision and has a fairly simple state machine:

created
automatically_approved
automatically_reproved
in_manual_analysis
manually_approved
manually_reproved
manually_challenged
pending
not_analyzed

In addition, upgrade_status has the same enumerators.

Additional drivers and financial manager

Besides the main renter, sent in client, a RentalAgreement may carry other people involved in the rental:

Additional drivers (additional_drivers): list of people authorized to drive the vehicle besides the main renter.
Financial manager (financial_manager): individual or company designated as responsible for paying the rental. There is at most one financial manager per rental.

Both fields use the participant object definition, whose structure is identical to the client object.

Every participant sent goes through the same anti-fraud queries and analyses applied to the main renter, so this data also feeds the Anti-fraud database. The individual result of each participant is returned in the analysis response, as described in Send a RentalAgreement. However, this result does not change the fraud_status of the RentalAgreement, which is still determined by the assessment of the main renter.

Both fields are optional and may be omitted when there are no participants besides the main renter.

Object Definition

{
  "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"
      }
    ]
  },
  "additional_drivers": [
    {
      "type": "natural_person",
      "document_number": "987.654.321-00",
      "name": "Jane Sample",
      "gender": "female",
      "email": "jane.sample@sample.com.br",
      "allowed_information_on_email": true,
      "face_picture": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "documents": {
        "cnh": {
          "document_number": "000000000",
          "security_code": "00000",
          "first_issuance": "2018-03-10",
          "expiration_date": "2028-03-10",
          "state": "SP"
        }
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "00000-0000",
          "type": "mobile"
        }
      ]
    }
  ],
  "financial_manager": {
    "type": "legal_person",
    "document_number": "00.000.000/0001-00",
    "name": "Empresa Sample LTDA",
    "gender": "undefined",
    "email": "financeiro@sample.com.br",
    "allowed_information_on_email": false,
    "documents": {},
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "commercial"
      }
    ]
  },
  "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"
}

All information exchanges of a RentalAgreement use the following definition for this object. In some cases, to make the implementation easier and reduce the data flow between the parties, some information may be omitted.

name	type	description
id	string	Identifier of the analysis request in the client's system. It is essential that this number be unique for each rental. (required)
rental_agreement_code	string	Identifier of the RentalAgreement in the client's system. (required)
rental_agreement_date	DateTime	Date and time, with time zone, of the vehicle pickup for the rental that is taking place. (required)
car_rental_estimated_final_date	DateTime	Date and time, with time zone, of when the car is expected to be returned. (required)
reservation	reservation	Object that carries the properties of the reservation that originated this rental. (required)
rental_store	store	Store where the car is being picked up. (required)
rental_store_group	store	Branch of the store where the car is being picked up.
rental_store_type	store	Type of the store where the car will be picked up.
devolution_store	store	Store where the car will be returned; it may or may not be the same pickup store. (required)
car	car	Car that is being picked up - it is important that this value be, in fact, the car being picked up. (required)
client	client	Object that carries the information of the client who is picking up the vehicle. (required)
additional_drivers	List of participant	List of the additional drivers authorized to drive the vehicle in this rental.
financial_manager	participant	Individual or company designated as the financial manager of this rental.
coverages	List of coverage	List of coverage objects describing the insurance coverages purchased by the client. (required)
billing	billing	Object describing the details of the person or company responsible for paying the rental. (required)
rental_price	integer	Rental price, in cents. (required)
extra_hours	integer	Number of extra hours purchased. (required)
extra_hours_price	integer	Price of the extra hours purchased, in cents. (required)
discount	integer	Discount granted for any reason, in cents. (required)
prepayment_discount	integer	Discount for advance payment.
extra_kms	integer	Number of extra kilometers purchased. (required)
extra_kms_price	integer	Price of the extra kilometers purchased, in cents. (required)
third_party_coverage_price	integer	Price of the third-party insurance, in cents. (required)
coverage_price	integer	Price of the insurance purchased, in cents. (required)
additional_driver_price	integer	Total price of the additional driver(s) purchased, in cents.
driver_service_price	integer	Total price of the driver service purchased, in cents.
additional_expenses	integer	Additional expenses, in cents.
devolution_fee	integer	Price of the return fee, in cents. (required)
administration_fee	integer	Price of the administration fee, in cents. (required)
discount_partial_coverage	integer	Partial protection discount, in cents.
free_day_discount	integer	Free Day discount, in cents.
final_price	integer	Final price of the rental, in cents. (required)
pre_authorization_amount	integer	Pre-authorization amount, in cents.
coverage_deductible_amount	integer	Deductible amount of the coverage, in cents. (required)
upgrade_reason	enum	Type of upgrade (Granted or Bought) - Accepts the values `granted` and `bought` respectively.

Send a RentalAgreement

Request example:

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

Response example:

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

If the rental was sent with additional drivers and/or a financial manager, the individual analysis result of each of them is also returned:

name	type	description
financial_manager.fraud_status	enum	Result of the anti-fraud analysis of the financial manager. Uses the same enumerators as the RentalAgreement fraud_status.
additional_drivers[].id	string	Identifier of the additional driver analyzed.
additional_drivers[].fraud_status	enum	Result of the anti-fraud analysis of that additional driver. Uses the same enumerators as the RentalAgreement fraud_status.

note

These statuses are informative and independent: a rejected additional driver or financial manager does not change the RentalAgreement fraud_status. It is up to the rental company to decide what to do with the rejected participant, such as refusing to include that driver in the rental.

To assess a rental, simply send a RentalAgreement object to the following endpoint with the flag set appropriately:

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

Besides the status of the response, the desired pre-authorization amount is also returned, if there is one. If no pre-authorization increase is identified, the returned value is null and must not be used.

The highest group that can be provided in that RA is made available in the highest_allowed_car_group variable. This value is configured in the RA assessment rule.

The analyze parameter exists to prevent transactions that do not need to be analyzed from going through the fraud engines, polluting the database. The default value of this parameter is true, so that only rentals explicitly removed from the analysis will not be analyzed.

Update the status of a RentalAgreement

Request body - When a car rental is effected:

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

Request body - On the return of a car without incidents:

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

Request body - On the return of a car recovered after a theft:

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

Request body - Write-off with confirmed fraud:

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

To guarantee the feedback loop of the rules and of the implemented artificial intelligence model, it is necessary to inform the system when cars are rented, returned, or written off due to fraud. To do so, requests with the PUT method must be used, passing as a reference the id sent when creating the rental_agreement, authenticated as usual:

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

If the new status is written_off, the following values can be used in the incident field, sent in the request body, which indicates the type of incident of the rental:

Enumerator	Description
theft	RAs that suffered a theft
misappropriation	RAs that were classified as misappropriation

Update the vehicle of a RentalAgreement

Request body - Updating a vehicle in the rental:

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

To guarantee the consistency between fraud occurrences and rentals and to guarantee the retraining of the score model, it is necessary to inform the system of the data of each car when it is linked to the rental. To do so, requests with the POST method must be used, passing as a reference the id sent when creating the rental_agreement, authenticated as usual:

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

The data of the vehicle being linked to that rental must be sent in the request body:

name	type	description
car_plate	string	License plate of the vehicle.
car_model	string	Model of the vehicle, including its make and model (e.g.: Jeep Renegade).
model_group	string	The group of the vehicle, in uppercase letters.
event_date	DateTime	Date and time, with time zone, of the moment when the car was associated with the rental.

Retrieve a RentalAgreement

In order to retrieve a specific RentalAgreement, simply make a GET request. The returned result is the most up-to-date json of the RentalAgreement in question. If this identifier is not related to any object, HTTP Status 404 is returned.

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"

Search RentalAgreements

Response - a list of RentalAgreement objects:

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

If it is necessary to search for a RentalAgreement, a GET with query parameters can be used. The returned result is a JSON representing a list of RentalAgreements. If no object is found with the parameters sent, HTTP Status 200 is returned with an empty list in the response body.

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

The following parameters can be used to search for RentalAgreement objects:

Parameter	Default	Description
initial_date	null	First date that must be returned based on the rental_agreement_date field
final_date	null	Last date that must be returned based on the rental_agreement_date field
store_code	null	Code of the store from which the results must be returned
page_number	1	Number of the desired results page
page_rows	50	Maximum number of objects to be returned in a query

Status Dynamics​

Status Dynamics - car_status​

Status Dynamics - fraud_status​

Additional drivers and financial manager​

Object Definition​

Send a RentalAgreement​

Update the status of a RentalAgreement​

Update the vehicle of a RentalAgreement​

Retrieve a RentalAgreement​

Search RentalAgreements​