Introdução

Bem vindo à API de Prevenção a Fraudes em aluguel de veículos da Zaig! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de um contrato de aluguel, além de utilizar para atualizar a situação de um contrato.

Ao lado, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

• Produção - https://api.caas.qitech.app/car_rental/
• Sandbox - https://api.sandbox.caas.qitech.app/car_rental/

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a seguinte regra baseada no valor total do aluguel:

As análises de upgrade em abiente de Sandbox seguirão as decisões de análise abaixo:

Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da Zaig devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

Autenticação

Para autenticar uma chamada, utilize o código seguinte:

# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: TESTETESTETESTE"

Substitua a API key 'TESTETESTETESTE' 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: TESTETESTETESTE

RentalAgreement-v1

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:

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

Exemplo

{
  "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.

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/bca6268e-918a-4658-9161-a10b00a631ab

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:

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/bca6268e-918a-4658-9161-a10b00a631ab/car

No body da requisição devem ser enviados os dados do veículo que está sendo atrelado aquele 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/bca6268e-918a-4658-9161-a10b00a631ab

curl "https://api.caas.qitech.app/car_rental/rental_agreements/bca6268e-918a-4658-9161-a10b00a631ab"
  -H "Authorization: TESTETESTETESTE"

O comando acima retorna o JSON que representa um objeto de RentalAgreement.

Buscar RentalAgreements

Retorna um JSON que representa 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:

Reservation-v1

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:

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

Exemplo

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  "reservation_date": "2020-03-31T08:15:00-03:00",
  "rental_agreement_date": "2020-03-31T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2020-04-01T10: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",
  "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"
    ],
    "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"
  },
  "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.

Enviar uma Reserva

Exemplo de Request

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

Exemplo de Retorno

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

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/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 Zaig 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, confome exemplo ao lado:

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

    {
        "reservation_code": "123456789"
    }

Recuperar uma Reserva

A fim de recuperar uma Reserva específico, 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/bca6268e-918a-4658-9161-a10b00a631ab

curl "https://api.caas.qitech.app/car_rental/reservation/bca6268e-918a-4658-9161-a10b00a631ab"
  -H "Authorization: TESTETESTETESTE"

O comando acima retorna o JSON que representa um objeto de Reservation.

RentalAgreement-v2

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:

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

Exemplo

{
  "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.

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/bca6268e-918a-4658-9161-a10b00a631ab

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:

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/bca6268e-918a-4658-9161-a10b00a631ab/car

No body da requisição devem ser enviados os dados do veículo que está sendo atrelado aquele 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/bca6268e-918a-4658-9161-a10b00a631ab

curl "https://api.caas.qitech.app/car_rental/rental_agreements/bca6268e-918a-4658-9161-a10b00a631ab"
  -H "Authorization: TESTETESTETESTE"

O comando acima retorna o JSON que representa um objeto de RentalAgreement.

Buscar RentalAgreements

Retorna um JSON que representa 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:

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:

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

Exemplo

{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  "reservation_date": "2024-03-19T10:30:00-03:00",
  "rental_agreement_date": "2024-03-252020-03-31T10: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.

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 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/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 Zaig 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, confome exemplo ao lado:

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

    {
        "reservation_code": "123456789"
    }

Recuperar uma Reserva

A fim de recuperar uma Reserva específico, 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/bca6268e-918a-4658-9161-a10b00a631ab

curl "https://api.caas.qitech.app/car_rental/reservation/bca6268e-918a-4658-9161-a10b00a631ab"
  -H "Authorization: TESTETESTETESTE"

O comando acima retorna o JSON que representa um objeto de Reservation.

Troca de Mensagens

Para a troca de mensagens entre a mesa de análise manual e o atendente da loja, são disponibilizados dois endpoints:

POST https://api.caas.qitech.app/car_rental/rental_agreement/bca6268e-918a-4658-9161-a10b00a631ab/message GET https://api.caas.qitech.app/car_rental/rental_agreement/bca6268e-918a-4658-9161-a10b00a631ab/messages

Todas as mensagens são vinculadas a uma análise, utilizando o id enviado no momento do envio da análise.

Envio de Mensagem

Para que seja realizado o envio de uma mensagem, é necessário realizar a requisição utilizando o método POST no endpoint message, com uma payload que possui os seguntes campos:

Exemplo de payload para envio de uma mensagem

{
    "author_name": "John Sample",
    "author_document_number": "000.000.000-00",
    "message": "Alerta de fraude"
}

Recebimento de Mensagens

Para que as mensagens possam ser exibidas para o atendente, basta realizar a recuperação das mensagens trocadas por meio do endpoint de GET. O endpoint pode receber um query parameter chamado only_messages_to_show, que ao receber o valor true retorna somente as mensagens que devem ser exibidas na tela do atendente.

Os dados do autor somente são devolvidos quando a mensagem foi produzida por um ser humano.

Retorno no endpoint de recuperação de mensagens

[
    {
        "author_name": "John Sample",
        "author_document_number": "000.000.000-00",
        "source": "analysis_screen",
        "message": "Análise finalizada",
        "message_date": "2019-11-05T13:34:12-03:00"
    },
    {...}
]

Envio de Resultado Quiz

Para o envio do resultado Quiz, para que apareça na interface gráfica, o seguinte endpoint deve ser utilizado:

POST https://api.caas.qitech.app/car_rental/rental_agreement/bca6268e-918a-4658-9161-a10b00a631ab/quiz_result

O resultado do quiz é vinculado a uma análise, utilizando o id enviado no momento do envio da análise.

Envio do Quiz

Para que seja enviado o resultado do Quiz, é necessário realizar a requisição utilizando o método POST no endpoint quiz_result, com uma payload que possui os seguntes campos:

Exemplo de payload para envio do resultado do Quiz

{
    "score": 950,
    "result_enum": "low_risk",
    "result_description": "Baixo Risco"
}

Objetos Compartilhados

Boa parte dos dados são compartilhados entre Reservation e RentalAgreement. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

Objeto reservation

Exemplo

{
  "id": "0",
  "channel": "reservation_central",
  "reservation_date": "2020-03-31T08:15:00-03:00",
  "sales_channel" : "PARCERIA TELEFONICA"
}

O objeto reservation é utilizado no endpoint de rental_agreement para representar a reserva que deu origem ao aluguel que será analisado. Este campo é necessário para que um rental_agreement seja vinculado à reserva. Representada da seguinte maneira:

Existem os seguintes enumeradores para o campo channel: walkin, reservation_central, app, website_mobile, website_desktop, partnerships e third_parties.

Objeto car

Exemplo

{
  "model_group": "C",
  "upgrade_model_group": "SV",
  "group_description": "Sedan Médio 1.4",
  "rental_daily_price": 48496
}

O objeto car representa um veículo que está sendo reservado (endpoint de reservation) ou retirado (endpoint de rental_agreement). Os dados enviados são:

Objeto client

O objeto de client representa os dados referentes ao cliente que está fazendo a reserva ou retirada do veículo.

Objeto client (v1)

O exemplo "v1" representa o payload de exemplo antes da migração da scoragem principal para a reserva. Tanto para reservas quanto para rental_agreements.

Exemplo

{   
  "type": "natural_person",
  "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"
    }
  ]
}

Existem os seguintes enumeradores para o campo type: natural_person, legal_person, replacement, fleet, uber, enterprise e agencia.

Existem os seguintes enumeradores para o campo gender: male, female e undefined.

Objeto client (v2)

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

O exemplo do objeto de "client (v2)" representa o payload de exemplo posterior à migração da scoragem principal para a reserva. Tanto para reservas quanto para rental_agreements.

Exemplo

{   
  "type": "natural_person",
  "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"
    }
  ]
}

Existem os seguintes enumeradores para o campo type: natural_person, legal_person, replacement, fleet, uber, enterprise e agencia.

Existem os seguintes enumeradores para o campo gender: male, female e undefined.

Objeto billing

Exemplo

{
  "name": "Agência AAA",
  "document_number": "00.000.000/0001-00",
  "voucher_type":"ABCD75",
  "voucher_description": "Pagamento pela Agência"
}

O objeto billing é utilizado para representar quem é o responsável pelo pagamento do aluguel, e é representado da seguinte maneira:

Objeto address

Exemplo

{
  "street": "Rua do Exemplo",
  "number": "111",
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "",
  "postal_code": "00000-000"
}

O objeto address é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

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 documents

O objeto documents é utilizado para representar o detalhamento dos dados dos documentos informados pelo cliente. O objeto é representado da seguinte maneira:

Objeto rg

O objeto rg é utilizado para representar o detalhamento dos dados do RG informados pelo cliente. O objeto é representado da seguinte maneira:

Objeto cnh

O objeto cnh é utilizado para representar o detalhamento dos dados da CNH informados pelo cliente. O objeto é representado da seguinte maneira:

Objeto phone

Exemplo

{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "99999-9999",
  "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:

Existem os seguintes enumeradores para tipo de telefone: residential, commercial, mobile.

Objeto coverage

Exemplo

{
  "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
  "price": 0
}

Um objeto coverage está relacionado a uma cobertura contratada pelo locatário.

Webhook

Atualizações no status de fraude (Para RentalAgreements 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, configurar um endereço do endpoint por onde vamos notificar as atualizações e também um secret_token que será utilizado para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de polling. Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de RentalAgreement para proceder com o polling.

Assinatura

Exemplo de cálculo de assinatura em Python

    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + 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, 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.

Requisição

Exemplo de requisição

    {
        "rental_agreement_id": "123456",
        "fraud_status": "automatically_approved",
        "upgrade_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }

A requisição possui o formato ao lado e notifica a mudança no status de fraude.

Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

• 10 segundos
• 30 segundos
• 60 segundos
• 120 segundos
• 120 segundos
• 3600 segundos
• 7200 segundos
• 36000 segundos

Imagens

Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.

Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.

Envio

Exemplo de envio utilizando o cUrl

    curl    -F "data=@path/to/local/file" \
            -H "Authorization: TESTETESTETESTE" \
            -H "DocumentNumber: 000.000.000-00" \
            "https://api.caas.qitech.app/car_rental/image?type=face"

Exemplo de retorno

    {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_name": "05696664903.jpg",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "type": "face",
        "created_at": "2020-07-29T18:40:57Z"
    }   

Para enviar uma imagem, basta realizar o envio da imagem no formato .jpg em multipart/form-data com uma requisição POST no endpoint:

https://api.caas.qitech.app/car_rental/image?type=$type

Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o suporte para que providenciem a adição):

• face
• driver_license
• id
• contract

Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.

Análise da Imagem para App

Ao utilizar a api_key do App, o resultado contará com um valor adicional, chamado de result que pode receber os seguintes valores:

• registration_approved
• registration_reproved

Que indica se o cadastro da foto foi aprovado ou reprovado.

Neste momento, a qualidade da foto também é avaliada, podendo receber um resultado 400, conforme descrito no próximo item.

Exemplo de retorno para o App

    {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_name": "05696664903.jpg",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "type": "face",
        "result": "registration_approved",
        "created_at": "2020-07-29T18:40:57Z"
    }   

Validação de qualidade da imagem

Exemplo de retorno em caso de imagem inválida

    {
        "title": "image_quality",
        "description": "A imagem enviada não possui uma face"
    }

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado.

O valor do campo description é a mensagem que explica o motivo da imagem ser inválida.

Atenção - Existem outros motivos pelos quais retornaremos 400 (Todos relacionados a dados inválidos). Somente os retornos com title "image_quality" são resultantes da validação de qualidade da imagem e portanto devem ser repassados ao usuário.

Recuperação dos Arquivos

Leitura de imagem

    curl "https://api.caas.qitech.app/car_rental/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: TESTETESTETESTE"

Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:

https://api.caas.qitech.app/car_rental/image/{image_key}/file

Onde image_key é o valor retornado durante o envio da imagem.

Recuperação dos meta-dados do arquivo

Leitura de meta dados

    curl "https://api.caas.qitech.app/car_rental/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: TESTETESTETESTE"

Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:

https://api.caas.qitech.app/car_rental/image/{image_key}

Onde image_key é o valor retornado durante o envio da imagem.

Padrões

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

Valores Monetários

Exemplos:

10000
12345
98741
1223
1
0

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

Data e Hora com Fuso Horário

Alguns exemplos:

2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

YYYY-MM-ddThh:mm:ss±hh:mm

Data e Hora sem Fuso Horario

Alguns exemplos:

2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

YYYY-MM-ddThh:mm:ssZ

Data

Alguns exemplos

2019-10-15
2019-01-01
2017-03-20

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

YYYY-MM-dd

Documentos

Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

CPF

Exemplos de CPFs válidos contra a máscara definida:

123.456.789-12
321.987.543-23
111.283.333-00

Exemplos de CPFs inválidos contra a máscara definida:

8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01

O CPF é sempre definido como uma string e será validado conta a máscara:

###.###.###-##

CNPJ

Exemplos de CNPJs válidos contra a máscara definida:

08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35

Exemplos de CNPJs inválidos contra a máscara definida:

8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3

O CNPJ é sempre definido como uma string e será validado conta a máscara:

##.###.###/####-##

Status HTTP

Todas as APIs da Zaig utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231: