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:

Resultado	Descrição
Aprovado Automaticamente	Recomenda-se que este pedido seja aprovado
Negado Automaticamente	Recomenda-se que este pedido seja reprovado
Derivado para análise manual	Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este pedido para a análise manual.
Aprovado Manualmente	Após análise manual, o analista escolheu aprovar o pedido
Reprovado Manualmente	Após análise manual, o analista escolheu reprovar o pedido
Pendente	As 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 analisado	A 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.

nome	tipo	descrição
id	string	Identificador do pedido no sistema do cliente. É essencial que este valor seja único para cada pedido (Obrigatório)
is_one_dollar_auth	booleano	Se esta for uma transação somente para validação do cartão, enviar com essa flag true (Obrigatório)
seller	Objeto Seller	Os 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)
payment	Objeto Payment	Dados do pagamento do pedido (Obrigatório)
customer	Objeto Customer	Dados do cliente/usuário (Obrigatório)
shipping	Objeto Shipping	Dados da entrega do pedido - Deve ser preenchido em casos de produtos de entrega física
device	Objeto Device	Dados do aparelho/navegador onde o pedido é realizado
products	Array de Product	Os produtos sendo comprados (Obrigatório)
order_date	Data Hora	Data 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âmetro	Padrão	Descrição
initial_date	null	Primeira data que deve ser retornada a partir do campo order_date
final_date	null	Última data que deve ser retornada a partir do campo order_date
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

Order

Dinâmica dos Status​

Dinâmica dos Status - payment_status​

Dinâmica dos Status - analysis_status​

Definição do Objeto​

Enviar um Pedido​

Atualizar o status de um Pedido​

Recuperar um Pedido​

Buscar CardOrders​

Dinâmica dos Status

Dinâmica dos Status - payment_status

Dinâmica dos Status - analysis_status

Definição do Objeto

Enviar um Pedido

Atualizar o status de um Pedido

Recuperar um Pedido

Buscar CardOrders