Skip to main content

Order

Antes de realizar a entrega/envio de um produto ou a liberação de créditos para o seu cliente ou seller, você deve enviar os dados do pedido para a nossa API para que possamos lhe responder a nossa recomendação com relação a fraude. É muito importante que os dados enviados sejam os dados finais, que não serão alterados. Isto é muito 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 Order no endpoint adequado e esperar a resposta. Existem quatro resultados possíveis, devolvido na flag analysis_status:

ResultadoDescrição
Aprovado AutomaticamenteRecomenda-se que este pedido seja aprovado
Negado AutomaticamenteRecomenda-se que este pedido seja reprovado
Derivado para análise manualNossas regras ou modelos não estão confiantes da decisão e decidiram enviar este pedido para a análise manual.
Aprovado ManualmenteApós análise manual, o analista escolheu aprovar o pedido
Reprovado ManualmenteApós análise manual, o analista escolheu reprovar o pedido
PendenteAs consultas estão demorando mais do que o esperado, este pedido entrou em uma fila de análise automática e será respondido por meio de Webhook
Não analisadoA consulta foi enviada com a flag de análise falsa, ou trata-se de uma análise exclusivamente para geração de alertas, o que significa que nossos sistemas não deverão retornar recomendação na resposta da Order
Atenção

Caso o seu modelo de negócio demande, o motor da QI Tech pode ser configurado para que nenhum pedido seja derivado para análise manual, e nem para o estado Pendente. Assim, o seu usuário poderá receber imediatamente a confirmação da transação.

Dinâmica dos Status

Ao recuperar um objeto do tipo Order 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 - payment_status

O status payment_status relacionado a um Pedido indica a situação do pagamento relacionado a este pedido, isto é, se a transação foi efetivamente aprovada, se foi cancelada ou se recebeu um chargeback de fraude. Os seguintes status de pagamento estão disponíveis:

  • open
  • not_authorized
  • authorized
  • captured
  • cancelled
  • chargeback
Atenção

É de suma importância que o status de pagamento seja enviado para a QI Tech pois ele é utilizado como base para treinamento dos nossos modelos. No caso de chargeback, é muito importante que o reason_code seja enviado corretamente, como será explicado em seguida.

Dinâmica dos Status - analysis_status

O status analysis_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

Request Body
{
"id": "12345678",
"is_one_dollar_auth": false,
"seller": {
"id": "COD",
"name": "Restaurante do Aeroporto de Congonhas",
"type": "legal_person",
"document_number": "00.000.000/0001-00",
"email": "seller@gmail.com",
"registration_date": "2019-12-20T15:23:12-03:00",
"url": "https://www.qitech.com.br",
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
},
"address": {
"street": "Rua do Exemplo",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "Térreo",
"postal_code": "00000-000",
"country": "BRA"
}
},
"payment": {
"total_amount": 10000,
"shipping_amount": 500,
"currency": "BRL",
"is_recurrence": false,
"transactions": [{
"id": "124234",
"amount": 8000,
"bin": "123456",
"last_4": "1234",
"cardholder_name": "JOHN SAMPLE",
"card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"expiration_date": "2020-11",
"installments": 6,
"processor": "stone",
"payment_type": "credit",
"status": "not_authorized"
}]
},
"shipping": {
"name": "Mary Sample",
"gender": "female",
"document_number": "000.000.000-00",
"birthdate": "1990-01-02",
"email": "test@sample.com",
"address": {
"street": "Rua do Exemplo, 123",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
},
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
},
"scheduled_date": "2020-01-10",
"shipping_method": "regular"
},
"customer": {
"id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
"name": "Mary Sample",
"gender": "female",
"document_number": "000.000.000-00",
"registration_date": "2019-12-20T15:23:12-03:00",
"email": "test@sample.com",
"birthdate": "1990-01-02",
"address": {
"street": "Rua do Exemplo, 123",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
},
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
}
},
"device": {
"session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
"platform": "android",
"browser": "chrome",
"ip": "243.178.100.37"
},
"products": [{
"product_code": "latte-machiatto-30",
"name": "Latte Machiatto 30cl",
"description": "Latte Machiatto 30cl para levar, leite integral",
"sku": "1234",
"quantity": 2,
"unit_cost": 5000
}],
"order_date": "2020-01-03T15:35:12.454-03:00"
}

Todas as trocas de informação de um pedido 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.

nometipodescrição
idstringIdentificador do pedido no sistema do cliente.
É essencial que este valor seja único para cada pedido (Obrigatório)
is_one_dollar_authbooleanoSe esta for uma transação somente para validação do cartão, enviar com essa flag true (Obrigatório)
sellerObjeto SellerOs dados da loja onde a venda está sendo realizada. No caso de um market place, são os dados do vendedor. No caso de um aplicativo, são os dados da loja de retirada (Obrigatório)
paymentObjeto PaymentDados do pagamento do pedido (Obrigatório)
customerObjeto CustomerDados do cliente/usuário (Obrigatório)
shippingObjeto ShippingDados da entrega do pedido - Deve ser preenchido em casos de produtos de entrega física
deviceObjeto DeviceDados do aparelho/navegador onde o pedido é realizado
productsArray de ProductOs produtos sendo comprados (Obrigatório)
order_dateData HoraData e hora de realização do pedido (Obrigatório)

Enviar um Pedido

Request Body
  {
"id": "12345",
...
}
Response Body
  {
"id": "12345",
"analysis_status": "automatically_approved"
}

Para realizar a avaliação de um pedido, basta enviar um objeto do tipo Order ao seguinte endpoint:

POST https://api.caas.qitech.app/card_order/order

Atualizar o status de um Pedido

Request Body
{
"transaction_status": "chargeback"
}

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as transações são autorizadas, capturadas, canceladas ou recebem chargeback. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:

PUT https://api.caas.qitech.app/card_order/order/12345678/transaction/124234

Existem os seguintes enumeradores para transaction_status: open, not_authorized, authorized, captured, cancelled, chargeback

Recuperar um Pedido

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

GET https://api.caas.qitech.app/card_order/order/12345678

curl "https://api.caas.qitech.app/card_order/order/12345678"
-H "Authorization: EXAMPLE_API_KEY"

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

Buscar CardOrders

Response Body
[
{
"id": "12345",
...
},
{
"id": "12345",
...
}
]

Retorna um JSON que representa uma lista de objetos CardOrder.

Caso seja necessário buscar um CardOrder, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de CardOrders. 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/card_order/order?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 CardOrder:

ParâmetroPadrãoDescrição
initial_datenullPrimeira data que deve ser retornada a partir do campo order_date
final_datenullÚltima data que deve ser retornada a partir do campo order_date
page_number1Número da página de resultados desejada
page_rows50Número de objetos máximo a ser retornados em uma consulta