NAV

Introdução

Olá! Este documento explica como integrar com o serviço de antifraude da Konduto para que você comece a detectar as fraudes no seu e-commerce.

Nosso serviço usa o comportamento do visitante para analisar padrões de navegação e detectar fraudes. Você precisará adicionar um código JavaScript ao seu site e marcar suas páginas, para que possamos ver os seus visitantes, e deverá enviar pedidos para nossa API REST, para que nós possamos fazer a análise.

Nessa documentação, você encontra todo embasamento técnico necessário para encaminhar seus pedidos para nossa API, além de bibliotecas de integração para as principais linguagens.

Todo o contexto técnico voltado para os padrões de navegação podem ser encontrados acessando nosso portal de ajuda. Nele você encontrará as informações para implementar o JavaScript, coletar eventos de navegação e as formas de identificação do visitante em sua página.

Nós estamos melhorando constantemente este documento e agradecemos qualquer sugestão enviada. Você pode mandar uma mensagem para suporte@konduto.com com suas perguntas e sugestões de como melhora-lo.

Bibliotecas de integração

php-sdk - PHP helper
java-sdk - Java helper
dotnet-sdk - .NET helper

Nós disponibilizamos bibliotecas para ajudar com o desenvolvimento, bem como plugins para as plataformas mais comuns de e-commerce. Você encontrará ao lado uma lista com as integrações disponíveis até o momento, que estão hospedadas em nosso Github.

Se você não vê a biblioteca da sua linguagem ou o seu plugin, por favor entre em contato através do email oi@konduto.com.

Autenticação da API

# Como montar
Authorization: Basic BASE64(T738D516F09CAB3A2C1EE:)

# Resultado
Authorization: Basic VDczOEQ1MTZGMDlDQUIzQTJDMUVFOg==

Nós usamos padrão HTTP Basic Auth para autenticar os lojistas na nossa API.

Neste tipo de autenticação, você deve enviar um header HTTP chamado Authorization cujo valor é a palavra Basic seguida de um Base64 da sua chave privada.

Se você utiliza um de nossos helpers então a própria biblioteca já faz este passo, e você precisa apenas definir a sua chave.

API de Pedidos

URLs da API de Pedidos

POST https://api.konduto.com/v1/orders
PUT  https://api.konduto.com/v1/orders/{order_id}
GET  https://api.konduto.com/v1/orders/{order_id}

Quando o cliente faz a compra você deve nos enviar os dados do pedido para nossa API REST para que possamos analisa-la. Nós fazemos uma análise em tempo real e devolvemos uma recomendação do que fazer com o pedido e um score, que é o grau de confiança que temos do pedido.

Apesar de muitos dos parâmetros que aceitamos na API serem opcionais, nós recomendamos que você envie o quanto puder, pois cada ponto de dado faz diferença na análise.

O endereço de cobrança e as informações de cartão de crédito são especialmente importantes, mas entendemos que há casos onde você não tem esta informação em seu sistema.

Enviar um pedido

Você pode mandar pedidos usando o método POST e passando um JSON no corpo da requisição.

A chamada consiste em um objeto raiz que contém informações relacionadas ao pedido, bem como os objetos customer, billing, shipping e travel e as listas payment e shopping_cart.

Pedido         order

{
  "id":"10000000001",
  "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
  "total_amount":100.00,
  "shipping_amount":20.00,
  "tax_amount":3.45,
  "currency":"BRL",
  "installments":2,
  "ip":"189.68.156.100",
  "first_message":"2018-12-20T15:59:01Z",
  "messages_exchanged":30,
  "purchased_at":"2018-12-25T12:00:25Z",
  "analyze":true,
  "customer":{ },
  "payment":[ ],
  "billing":{ },
  "shipping":{  },
  "shopping_cart":[ ],
  "travel":{ },
  "seller":{ }
}

A raíz do objeto contém os dados básicos do pedido, como número, valor e moeda.

Parâmetro Descrição
id (obrigatório)
Identificador único para cada pedido.
Max. 100 chars, alpha-numérico
visitor (opcional)
Identificador do visitante obtido do nosso JavaScript.
Exatamente 40 chars, alpha-numérico
total_amount (obrigatório)
Valor total do pedido.
Max. 10 dígitos, número
shipping_amount (opcional)
Valor do frete
Max. 10 dígitos, número
tax_amount (opcional)
Valor dos impostos.
Max. 10 dígitos, número
currency (opcional)
Código da moeda com 3 letras (ISO-4712).
Exatamente 3 chars, string
installments (opcional)
Número de parcelas do pagamento.
Max. 3 dígitos, número
ip (opcional)
Endereço IPv4 do cliente
Max. 15 chars, string
first_message (opcional)
No Marketplace, traz a data e hora da primeira mensagem trocada entre comprador e vendedor. Formato AAAA-MM-DDTHH:mm:ssZ (ISO 8601)
Exatamente 20 chars, string.
messages_exchanged (opcional)
No Marketplace, deve trazer o número de mensagens trocadas entre comprador e vendedor até o momento da transação.
Número.
purchased_at (opcional)
No Marketplace, traz a data e hora do fechamento do pedido no site. Formato AAAA-MM-DDTHH:mm:ssZ (ISO 8601)
Exatamente 20 chars, string.
analyze (opcional)
Se false o sistema levará em conta a transação nas próximas análises mas não devolve uma recomendação e você não é cobrado.
Boolean. Se não enviado o padrão é true
customer (obrigatório)
Objeto que contém os detalhes do cliente.
payment (opcional)
Lista que contém os meios de pagamento.
billing (opcional)
Objeto que contém o endereço de cobrança.
shipping (opcional)
Objeto que contém o endereço de entrega.
shopping_cart (opcional)
Lista que contém os itens comprados.
travel (opcional)
Objeto que contém os dados de viagem e passageiros.

Comprador         customer

{
  "customer": {
    "id":"28372",
    "name":"Júlia da Silva",
    "tax_id":"12345678909",
    "dob":"1970-12-25",
    "phone1":"11-1234-5678",
    "phone2":"21-2143-6578",
    "email":"jsilva@exemplo.com.br",
    "created_at":"2010-12-25",
    "new":false,
    "vip":false
  }
}

Este objeto deve ser usado para enviar informações sobre a pessoa que está fazendo a compra, que na maioria dos casos é aquele que está logado em seu sistema.

Para passar informações sobre o portador do cartão ou o destinatário do produto você deve usar o objeto billing e shipping, respectivamente.

Parâmetro Descrição
id (obrigatório)
Identificador único do cliente. Pode ser qualquer valor (sequencial, documento, e-mail) desde que seja consistente em pedidos futuros.
Max. 100 chars, string.
name (obrigatório)
Nome completo do cliente.
Max. 100 chars, string.
email (obrigatório)
Endereço de e-mail do cliente.
Max. 100 chars, string.
dob (opcional)
Data de nascimento do cliente no formato AAAA-MM-DD (ISO 8601)
Exatamente 10 chars, string.
tax_id (opcional)
Número de documento fiscal do cliente (CPF, CNPJ, etc).
Max. 100 chars, string.
phone1 (opcional)
Número de telefone principal do cliente
Max. 100 chars, string.
phone2 (opcional)
Número de telefone secundário do cliente.
Max. 100 chars, string.
created_at (opcional)
Data de criação da conta ou cadastro do cliente no site, em formato AAAA-MM-DD (ISO 8601).
Exatamente 10 chars, string.
new (opcional)
Flag indicando se o cliente está usando uma conta recém-criada nesta compra.
Boolean.
vip (opcional)
Flag indicando se este é um cliente VIP ou comprador frequente.
Boolean.

Meios de Pagamento         payment

{  
  "payment":[  
    {  
      "type":"credit",
      "bin":"490172",
      "last4":"0012",
      "expiration_date":"072015",
      "status":"approved"
    },
    {  
      "type":"credit",
      "bin":"514800",
      "last4":"3752",
      "expiration_date":"082016",
      "status":"approved"
    }
  ]
}

Esta lista de objetos deve ser usado para enviar informações sobre os meios de pagamentos usados na compra.

Você pode mandar um pedido que contém múltiplos meios de pagamento, como compras com dois cartões de crédito.

Parâmetro Descrição
type (obrigatório)
Meio de pagamento usado pelo cliente. Atualmente suportamos credit, boleto, debit, transfer e voucher.
Max. 8 chars, string.
status (obrigatório para ‘credit’)
O status do pagamento retornado pela operadora de cartão.
Pode ser approved (aprovado), declined (negado) ou pending (pendente), caso o pagamento não tenha sido feito ainda.
Max. 8 chars, string.
bin (opcional)
Os primeiros seis números do cartão de crédito. É usado para identificar o tipo de cartão usado.
Exatamente 6 chars, string.
last4 (opcional)
Os últimos quatro dígitos do cartão de crédito.
Exatamente 4 chars, string.
expiration_date (opcional)
Data de validade do cartão no formato MMAAAA
Exatamente 6 chars, string.

Endereço de Cobrança         billing

{  
  "billing":{  
    "name":"Júlia da Silva",
    "address1":"Rua Primeiro de Abril, 123",
    "address2":"Apto. 45",
    "city":"São Paulo",
    "state":"SP",
    "zip":" 01001-001",
    "country":"BR"
  }
}

Este objeto deve conter informações do titular do cartão. É o mesmo nome e endereço que consta na fatura.

Parâmetro Descrição
name (opcional)
Nome do titular do cartão.
Max. 100 chars, string.
address1 (opcional)
Endereço da fatura do cliente com o banco.
Max. 255 chars, string.
address2 (opcional)
Complemento do endereço de fatura.
Max. 255 chars, string.
city (opcional)
Cidade do titular.
Max. 100 chars, string.
state (opcional)
Estado do titular
Max. 100 chars, string.
zip (opcional)
CEP do titular.
Max. 100 chars, string.
country (opcional)
Código do país do titular (ISO 3166-2)
Exatamente 2 chars, string.

Endereço de Entrega         shipping

{  
  "shipping":{  
    "name":"Júlia da Silva",
    "address1":"Rua Primeiro de Abril, 123",
    "address2":"Apto. 45",
    "city":"São Paulo",
    "state":"SP",
    "zip":" 01001-001",
    "country":"BR"
  }
}

Este objeto deve conter informações do destinatário que vai receber os produtos. Não há necessidade de enviá-lo caso você forneça um serviço ou download de software.

Parâmetro Descrição
name (opcional)
Nome do destinatário do pedido.
Max. 100 chars, string.
address1 (opcional)
Endereço de entrega do destinatário.
Max. 255 chars, string.
address2 (opcional)
Complemento do endereço de fatura.
Max. 255 chars, string.
city (opcional)
Cidade do destinatário.
Max. 100 chars, string.
state (opcional)
Estado do destinatário
Max. 100 chars, string.
zip (opcional)
CEP do destinatário.
Max. 100 chars, string.
country (opcional)
Código do país do destinatário (ISO 3166-2)
Exatamente 2 chars, string.

Carrinho de Compras         shopping_cart

{  
  "shopping_cart":[  
    {  
      "sku":"9919023",
      "product_code":"123456789999",
      "category":201,
      "name":"Camiseta Verde",
      "description":"Camiseta masculina verde tamanho M",
      "unit_cost":29.99,
      "quantity":1,
      "created_at":"2008-12-25"
    },
    {  
      "sku":"0017273",
      "category":202,
      "name":"Par de meias amarelas",
      "description":"Par de meias amarelas tamanho único",
      "unit_cost":7.50,
      "quantity":2,
      "discount":1.00
    }
  ]
}

Esta lista de objetos contém uma lista dos produtos que foram comprados neste pedido. Não existe limite para a quantidade de objetos que esta lista aceita.

Parâmetro Descrição
sku (opcional)
SKU ou número de inventário do produto ou serviço.
Max. 100 chars, string.
product_code (opcional)
Código de barras ou UPC do produto ou serviço.
Max. 100 chars, string.
category (opcional)
Código da categoria do produto comprado.
Veja nossa lista de categorias para mais informações.
Max. 4 dígitos, número.
name (opcional)
Nome do produto ou serviço.
Max. 100 chars, string.
description (opcional)
Descrição de detalhada do produto ou serviço.
Max. 100 chars, string.
unit_cost (opcional)
Custo unitário deste produto ou serviço.
Max. 10 dígitos, número.
quantity (opcional)
Quantidade de unidades compradas.
Max. 10 dígitos, número.
discount (opcional)
Valor de desconto do produto.
Max. 10 dígitos, número.
created_at (opcional)
Data de publicação do produto no site, em formato AAAA-MM-DD (ISO 8601).
Exatamente 10 chars, string.

Viagem         travel

{  
  "travel":{  
    "type":"flight",
    "departure":{  
      "origin_airport":"GRU",
      "destination_airport":"SFO",
      "date":"2018-12-25T18:00Z",
      "number_of_connections":1,
      "class":"economy",
      "fare_basis":"Y"
    },
    "return":{  
      "origin_airport":"SFO",
      "destination_airport":"GRU",
      "date":"2018-12-30T18:00Z",
      "number_of_connections":1,
      "class":"business"
    },
    "passengers":[  
      {  
        "name":"Júlia da Silva",
        "document":"12345678909",
        "document_type":"id",
        "dob":"1970-01-01",
        "nationality":"BR",
        "loyalty":{  
          "program":"smiles",
          "category":"gold"
        },
        "frequent_traveler":true,
        "special_needs":false
      },
      {  
        "name":"Carlos Siqueira",
        "document":"XYZ1234",
        "document_type":"passport",
        "dob":"1970-12-01",
        "nationality":"US",
        "loyalty":{  
          "program":"multiplus",
          "category":"silver"
        },
        "frequent_traveler":false,
        "special_needs":true
      }
    ]
  }
}

Contém informações de viagem e dos passageiros desta compra. Dados de viagem estão divididos em objetos de ida (departure) e volta (return), além do tipo de transporte. Dados dos passageiros ficam no array passengers.

Parâmetro Descrição
type (obrigatório)
Tipo de viagem. Atualmente são suportados flight ou bus.
departure (obrigatório)
Objeto com as informações do viagem de ida.
return (opcional)
Objeto com as informações do viagem de volta.
passengers (obrigatório)
Array de objetos com os dados dos passegeiros

Informações da viagem

Parâmetro Descrição
origin_city (obrigatório se type=bus)
Cidade de origem.
Max 100 chars, string.
destination_city (obrigatório se type=bus)
Cidade de destino.
Max 100 chars, string.
origin_airport (obrigatório se type=flight)
Código IATA para o aeroporto de origem
Exatamente 3 chars, string.
destination_airport (obrigatório se type=flight)
Código IATA para o aeroporto de destino
Exatamente 3 chars, string.
date (obrigatório)
Date e hora do embarque em UTC no formato YYYY-MM-DDThh:mmZ (ISO 8601)
Exatamente 17 chars, string.
number_of_connections (opcional)
Número de conexões
class (opcional)
Nome da classe, como economy, business e first
Max. 8 chars, string.
fare_basis (opcional)
Código da classe.
Max 20 chars, string.

Informações dos passageiros

Parâmetro Descrição
name (obrigatório)
Nome completo do passangeiro
Max 100 chars, string.
document (opcional)
Número do documento
Max 100 chars, string.
document_type (opcional)
Tipo do documento. Pode ser passport ou id.
Max 8 chars, string.
dob (opcional)
Data de nascimento do passageiro no formato YYYY-MM-DD (ISO 8601).
Exatamente 10 chars, string.
nationality (opcional)
País de nascimento do passageniro (ISO 3166-2)
Exatamente 2 chars, string.
frequent_traveler (opcional)
Flag de viajante frequente.
Boolean, padrão é false.
special_needs (opcional)
Passageiro com necessidades especiais.
Boolean, padrão é false.

Vendedor         seller

{ 
  "id":"37",
  "name":"Loja do João",
  "created_at":"2009-11-25"
}

No Marketplace, são os campos destinados aos dados do Vendedor do produto.

Parâmetro Descrição
id (obrigatório)
Identificador único do vendedor dentro do Marketplace.
Max. 100 chars, string.
name (opcional)
Nome da loja ou do vendedor
Max. 100 chars, string.
created_at (opcional)
Data de criação da loja no Marketplace, em formato AAAA-MM-DD (ISO 8601)
Exatamente 10 chars, string.

Atualizar o parecer de um pedido

{  
  "status":"approved",
  "comments":"Documentos e endereço de entrega confirmados"
}

A qualquer momento você pode atualizar o parecer de risco de um pedido através do método PUT, passando um JSON no corpo da requisição.

O parecer de risco não deve ser confundido com a situação do pagamento. O status dentro da Konduto tem influencia no algoritmo e na análise de risco. Entenda mais sobre o status dos pedidos.

A chamada consiste em um objeto simples que contém dois campos, status e comments.

Parâmetro Descrição
status (obrigatório)
Novo status deste pedido. Pode ser APPROVED, DECLINED, NOT_AUTHORIZED, CANCELED or FRAUD, quando você identificar uma fraude ou chargeback.
Max. 8 chars, string.
comments (obrigatório)
Razão ou comentários sobre a atualização do pedido.
Max. 255 chars, string.

Consultar um pedido

GET https://api.konduto.com/v1/orders/ORD1837213

Você pode buscar os dados de um pedido usando o método GET. A resposta será um JSON com todos os dados que temos sobre o pedido, incluindo recommendation, score e o status atual.

API de Blacklist

URLs da Blacklist de Email

POST    https://api.konduto.com/v1/blacklist/email
PUT     https://api.konduto.com/v1/blacklist/email/{email}
GET     https://api.konduto.com/v1/blacklist/email/{email}
DELETE  https://api.konduto.com/v1/blacklist/email/{email}

A Blacklist é um recurso que lhe permite bloquear pedidos que contém certos dados. Compras feitas com estas informações serão negadas automaticamente pelo nosso sistema. Você pode adicionar uma entrada à Blacklist permanentemente ou até uma certa data de expiração.

Com a API de Blacklist você pode adicionar, atualizar, consultar e remover emails da lista.

Adicionar item

Exemplo de adição de email à Blacklist

{  
  "email_address":"jsilva@exemplo.com.br",
  "days_to_expire":180
}

Para adicionar uma entrada você deve usar o método POST. Os resultados são imediatos, então o próximo pedido analisado já levará em conta este item da Blacklist.

O tempo de expiração é opcional. Se definido, a entrada será removida automaticamente ao vencer o prazo. Se não, o registro permanecerá na Blacklist indefinidamente.

Parâmetros para adicionar um email

Parâmetro Descrição
email_address (obrigatório)
Endereço de email
Max. 100 chars, string
days_to_expire (opcional)
Dias para que esta entrada seja removida automaticamente da Blacklist
Número.

Atualizar a expiração

Examplo de atualização de expiração

{
  "days_to_expire": 360
}

A atualização de um item da Blacklist serve unicamente para trocar a sua data de expiração. Você pode adiar ou adiantar a remoção automática de uma entrada. Ela é feita utilizando o método PUT.

Parâmetro Descrição
days_to_expire (obrigatório)
Dias para que esta entrada seja removida automaticamente da Blacklist
Número.

Consultar uma entrada

GET https://api.konduto.com/v1/blacklist/email/jsilva@exemplo.com.br

Você pode consultar se uma entrada já existe na Blacklist usando o método GET. Se ela tiver uma data de expiração este valor também será retornado na consulta.

Remover item

DELETE https://api.konduto.com/v1/blacklist/email/jsilva@exemplo.com.br

Para retirar uma entrada da Blacklist você deve usar o método DELETE.

Respostas

Códigos HTTP

200 OK # Sucesso
201 Created # Item criado
400 Bad Request # Erro na requisição
401 Unauthorized # Problema na autenticação da chave
403 Forbidden # Problema no cadastro da loja
404 Not Found # Não encontrado
405 Method Not Allowed # Método inexistente
429 Too Many Requests # Limite de requisições atingido
444 No Response # Sem resposta
500 Server Error # Erro interno do servidor

Nossa API usa códigos de resposta HTTP para indicar o resultado de uma chamada.

Uma resposta na casa dos 2xx significa que a requisição foi processada e não continha erros. Já uma resposta com códigos na faixa dos 4xx ou 5xx indica algum erro.

Código Descrição
200 Chamada é válida e temos uma resposta.
201 Item enviado foi adicionado à lista.
400 Houve um problema com a requisição enviada. O corpo da resposta tem mais informações sobre a causa do erro.
401 A chave de API enviada não é válida. Verificar o formato da chave e o seu conteúdo no portal.
403 Há algum problema com a sua conta. Por favor entre em contato com o nosso Suporte para mais informações.
404 O número de pedido não foi encontrado na nossa base.
405 O método HTTP enviado não é permitido para este recurso.
429 Você atingiu o limite de requisições permitidas. Entre em contato com o nosso Suporte para mais informações.
444 O endereço da requisição é inválida e o servidor cortou a conexão. Por favor, verifique a URL de envio da transação.
500 Houve algum erro no processamento interno da Konduto. Entre em contato com o nosso Suporte para mais informações.

Respostas de erro

As respostas de erro da nossa API trazem sempre o motivo do erro e, quando possível, uma indicação de como e onde fazer a correção.

A principal razão para uma chamada à API falhar é um problema na validação, seja na sintaxe ou nos valores passados. Se o erro for causado por algum problema interno na Konduto nós devolveremos um ID único que pode ser enviado para o nosso suporte para investigação.

Resposta com erro de validação

Exemplo de erro onde o valor foi enviado como string

{  
  "status":"error",
  "message":{  
    "where":"/total_amount",
    "why":{  
      "expected":[  
        "integer",
        "number"
      ],
      "found":"string"
    }
  }
}
Parâmetro Descrição
where Campo ou objeto onde o erro aconteceu
why Causas do erro de validação
expected Tipo de dado esperado neste campo
found Valor que foi recebido neste campo
missing Campo obrigatório ausente
unknown_field Campo não reconhecido

Exemplo de erro interno do processamento

{  
  "status":"error",
  "message":{  
    "notification":"We've been notified about this error and will investigate it. Please keep this error identifier",
    "error_identifier":"09e1a98c-eada-4695-8864-bff8ba4707ba",
    "where":"/",
    "why":{  
      "expected":"ok",
      "found":"Internal error"
    }
  }
}

Resposta com erro de servidor

Parâmetro Descrição
notification Mensagem de erro do servidor
error_identifier Identificador do erro, que pode ser enviado ao nosso suporte para investigação.
where Campo ou objeto onde o erro aconteceu
why Causas do erro de validação
expected Tipo de dado esperado neste campo
found Valor que foi recebido neste campo

Resposta da API de Pedidos

Uma resposta bem sucedida da API de pedidos retorna sempre dois objetos.

O campo status indica o resultado da chamada, e o campo order traz o retorno do pedido que está sendo manipulado. O valor do objeto order varia de acordo com a chamada que está sendo feita.

Parâmetro Descrição
status Mensagem de status da chamada. Retorna ok quando bem sucedida e error quando falhou.
order Objeto contendo a resposta da análise.

Resposta da análise

{  
  "status":"ok",
  "order":{  
    "id":"ORD1837213",
    "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "score":0.07,
    "recommendation":"review",
    "ip":"189.68.156.100",
    "device":{  
      "user_id": "405961fab293600daeed93ae561",
      "fingerprint": "e4f2c690951038a8f77aa583847",
      "platform": "MacIntel",
      "browser": "Chrome",
      "language": "pt_BR",
      "timezone": "GMT -3",
      "cookie": true,
      "javascript":  true,
      "flash": true
    },
    "geolocation":{  
      "city":"São Paulo",
      "state":"SP",
      "country":"BR"
    },
    "navigation":{  
      "time_site_7d":15.0,
      "time_per_page_7d":2.0,
      "new_accounts_7d":0,
      "password_resets_7d":1,
      "checkout_count_7d":0,
      "sales_declined_7d":0,
      "sessions_7d":3,
      "time_site_1d":45.0,
      "new_accounts_1d":0,
      "password_resets_1d":0,
      "sales_declined_1d":0,
      "sessions_1d":1,
      "session_time":45.0,
      "time_since_last_sale":121.0,
      "referrer": "http://www.google.com/"
    }
  }
}

Na resposta da análise de um pedido os campos retornados dentro do objeto order são:

Objeto Parâmetro Descrição
- id Identificador único enviado na chamada
- visitor Identificador do visitante enviado na chamada
- score Score da transação entre 0 e 1.

Para transações que não foram analisadas o valor -1 é retornado (ver parâmetro order.analyze).
- recommendation Ação recomendada para este pedido. Pode ser APPROVE, REVIEW ou DECLINE.

Para transações que não foram analisadas o valor NONE é retornado (ver parâmetro order.analyze).
- status Status atual do pedido.
Pode ser APPROVED, PENDING, DECLINED, CANCELED, NOT_AUTHORIZED, NOT_ANALYZED e FRAUD.
- device Objeto contendo os dados coletados da máquina
device user_id Identificador único do visitante
device fingerprint Identificação do navegador
device platform Tipo de dispositivo pelo cliente
device browser Navegador do cliente
device language Idioma do navegador do cliente
device timezone Fuso horário do cliente em GMT
device cookie Flag indicando se o cliente tem Cookies habilitados
device javascript Flag indicando se o cliente tem JavaScript habilitados
device flash Flag indicando se o cliente tem Flash habilitados
device ip Endereço de IP do cliente
- geolocation Objeto contendo os dados de geolocalização do cliente
geolocation city Cidade detectada
geolocation state Estado detectado
geolocation country País detectado
- navigation Objeto contento os resumo de navegação do cliente
navigation session_time Tempo da última sessão, em minutos.
navigation referrer Origem da visita.
navigation time_site_1d Tempo gasto no site pelo usuário no último dia, em minutos.
navigation new_accounts_1d Quantidade de contas criadas pelo usuário no último dia.
navigation password_resets_1d Quantidade de redefinições de senha do usuário no último dia.
navigation sales_declined_1d Quantidade de pedidos negados feitos pelo cliente no último dia.
navigation sessions_1d Número de visitas do usuário no último dia.
navigation time_since_last_sale Tempo desde a última compra do usuário, em minutos.
navigation time_site_7d Tempo gasto no site pelo usuário nos últimos 7 dias, em minutos.
navigation time_per_page_7d Tempo médio por página gasto pelo usuário nos últimos 7 dias, em minutos
navigation new_accounts_7d Quantidade de contas criadas pelo usuário na última semana.
navigation password_resets_7d Quantidade de redefinições de senha do usuário na última semana.
navigation checkout_count_7d Visualizações do carrinho de compras feitas pelo usuário na última semana.
navigation sales_declined_7d Quantidade de pedidos negados feitos pelo cliente na última semana.
navigation sessions_7d Número de visitas do usuário na última semana.

Resposta da atualização

{
  "status": "ok",
  "order": {
    "old_status": "pending",
    "new_status": "approved"
  }
}

A resposta da atualização de status sempre retorna o status anterior e o status atual, o que acabou de ser mudado. Isto acontece mesmo quando o status antigo e o novo são o mesmo, ou seja, quando não houve atualização.

Parâmetro Descrição
old_status Antigo status da transação.
new_status Novo status da transação.

Resposta da consulta

{  
  "status":"ok",
  "order":{  
    "id":"ORD1837213",
    "visitor":"da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "created_at":"2028-03-13T21:48:30Z",
    "updated_at":"2028-03-15T08:09:26Z",
    "score":0.07,
    "recommendation":"approve",
    "status":"approved",
    "ip":"189.68.156.100",
    "total_amount":159.61,
    "tax_amount":3.04,
    "shipping_amount":6.57,
    "currency":"BRL",
    "first_message":"2018-12-20T15:59:01Z",
    "messages_exchanged":30,
    "purchased_at":"2018-12-25T12:00:25Z",
    "device":{  
      "user_id": "405961fab293600daeed93ae561",
      "fingerprint": "e4f2c690951038a8f77aa583847",
      "platform": "MacIntel",
      "browser": "Chrome",
      "language": "pt_BR",
      "timezone": "GMT -3",
      "cookie": true,
      "javascript":  true,
      "flash": true
    },
    "geolocation":{  
      "city":"São Paulo",
      "state":"SP",
      "country":"BR"
    },
    "billing":{  
      "name":"Júlia da Silva",
      "address1":"Rua Primeiro de Abril, 123",
      "address2":"Apto. 45",
      "city":"São Paulo",
      "state":"SP",
      "zip":" 01001-001",
      "country":"BR"
    },
    "shipping":{  
      "name":"Júlia da Silva",
      "address1":"Rua Primeiro de Abril, 123",
      "address2":"Apto. 45",
      "city":"São Paulo",
      "state":"SP",
      "zip":" 01001-001",
      "country":"BR"
    },
    "customer":{  
      "id":"28372",
      "name":"Júlia da Silva",
      "tax_id":"12345678909",
      "dob":"1970-12-25",
      "phone1":"11-1234-5678",
      "phone2":"21-2143-6578",
      "email":"jsilva@exemplo.com.br",
      "new":false,
      "vip":false
    },
    "navigation":{  
      "time_site_7d":15.0,
      "time_per_page_7d":2.0,
      "new_accounts_7d":0,
      "password_resets_7d":1,
      "checkout_count_7d":0,
      "sales_declined_7d":0,
      "sessions_7d":3,
      "time_site_1d":45.0,
      "new_accounts_1d":0,
      "password_resets_1d":0,
      "sales_declined_1d":0,
      "sessions_1d":1,
      "session_time":45.0,
      "time_since_last_sale":121.0,
      "referrer": "http://www.google.com/"
    },
    "payment":[  
      {  
        "type":"credit",
        "bin":"490172",
        "last4":"0012",
        "expiration_date":"072015",
        "status":"approved"
      },
      {  
        "type":"credit",
        "bin":"514800",
        "last4":"3752",
        "expiration_date":"082016",
        "status":"approved"
      }
    ],
    "shopping_cart":[  
      {  
        "sku":"9919023",
        "product_code":"123456789999",
        "category":201,
        "name":"Camiseta Verde",
        "description":"Camiseta masculina verde tamanho M",
        "unit_cost":29.99,
        "quantity":1
      },
      {  
        "sku":"0017273",
        "category":202,
        "name":"Par de meias amarelas",
        "description":"Par de meias amarelas tamanho único",
        "unit_cost":7.50,
        "quantity":2,
        "discount":1.00
      }
    ],
    "travel":{  
      "type":"flight",
      "departure":{  
        "origin_airport":"GRU",
        "destination_airport":"SFO",
        "date":"2018-12-25T18:00Z",
        "number_of_connections":1,
        "class":"economy",
        "fare_basis":"Y"
      },
      "return":{  
        "origin_airport":"SFO",
        "destination_airport":"GRU",
        "date":"2018-12-30T18:00Z",
        "number_of_connections":1,
        "class":"business"
      },
      "passengers":[  
        {  
          "name":"Júlia da Silva",
          "document":"12345678909",
          "document_type":"id",
          "dob":"1970-01-01",
          "nationality":"BR",
          "loyalty":{  
            "program":"smiles",
            "category":"gold"
          },
          "frequent_traveler":true,
          "special_needs":false
        },
        {  
          "name":"Carlos Siqueira",
          "document":"XYZ1234",
          "document_type":"passport",
          "dob":"1970-12-01",
          "nationality":"US",
          "loyalty":{  
            "program":"multiplus",
            "category":"silver"
          },
          "frequent_traveler":false,
          "special_needs":true
        }
      ]
    }
  }
}

A consulta de um pedido traz todos os dados relacionados aquela venda, que incluem tanto informações enviadas pela loja quanto da nossa análise.

Objeto Parâmetro Descrição
- id Identificador único enviado na chamada
- created_at Date e hora do envio da transação, em formato YYYY-MM-DDThh:mmZ (ISO 8601).
- updated_at Date e hora da última atualização da transação, em formato YYYY-MM-DDThh:mmZ (ISO 8601).
- visitor Identificador do visitante enviado na chamada
- score Score da transação entre 0 e 1.

Para transações que não foram analisadas o valor -1 é retornado.
- recommendation Ação recomendada para este pedido. Pode ser APPROVE, REVIEW ou DECLINE.

Para transações que não foram analisadas o valor NONE é retornado.
- status Mensagem de status da chamada. Retorna ok quando bem sucedida e error quando falhou.
- ip Customer’s IP address.
- total_amount Valor total do pedido.
- tax_amount Valor dos impostos.
- shipping_amount Valor do frete.
- installments Número de parcelas do pagamento.
- currency Código da moeda.
- payment Lista que contém os meios de pagamento.
payment type Lista que contém os meios de pagamento.
payment bin Lista que contém os meios de pagamento.
payment last4 Lista que contém os meios de pagamento.
payment expiration_date Lista que contém os meios de pagamento.
payment status Lista que contém os meios de pagamento.
- customer Objeto que contém os detalhes do cliente.
customer id Identificador único do cliente.
customer name Nome completo do cliente.
customer email Endereço de e-mail do cliente.
customer dob Data de nascimento do cliente no formato AAAA-MM-DD
customer tax_id Número de documento fiscal do cliente (CPF, CNPJ, etc).
customer phone1 Número de telefone principal do cliente.
customer phone2 Número de telefone secundário do cliente.
customer new Flag indicando se o cliente usou uma conta recém-criada.
customer vip Flag indicando se é um cliente VIP ou comprador frequente.
- billing Objeto que contém o endereço de cobrança.
billing name Nome do titular do cartão.
billing address1 Endereço da fatura do cliente com o banco.
billing address2 Complemento do endereço de fatura.
billing city Cidade do titular do cartão.
billing state Estado do titular do cartão.
billing zip CEP do titular do cartão.
billing country Código do país do titular do cartão.
- shipping Objeto que contém o endereço de entrega.
shipping name Nome do destinatário do cartão.
shipping address1 Endereço de entrega do destinatário.
shipping address2 Complemento do endereço de fatura.
shipping city Cidade do destinatário.
shipping state Estado do destinatário.
shipping zip CEP do destinatário.
shipping country Código do país do destinatário.
- shopping_cart Lista que contém os itens comprados.
shopping_cart sku SKU ou número de inventário do produto ou serviço.
shopping_cart product_code Código de barras ou UPC do produto ou serviço.
shopping_cart category Código da categoria do produto comprado.
Veja nossa lista de categorias para mais informações.
shopping_cart name Nome do produto ou serviço.
Max. 100 chars, string.
shopping_cart description Descrição de detalhada do produto ou serviço.
shopping_cart unit_cost Custo unitário deste produto ou serviço.
shopping_cart quantity Quantidade de unidades compradas.
shopping_cart discount Valor de desconto do produto.
- device Objeto contendo os dados coletados da máquina.
device user_id Identificador único do visitante.
device fingerprint Identificação do navegador.
device platform Tipo de dispositivo pelo cliente.
device browser Navegador do cliente.
device language Idioma do navegador do cliente.
device timezone Fuso horário do cliente em GMT.
device cookie Flag indicando se o cliente tem Cookies habilitados.
device javascript Flag indicando se o cliente tem JavaScript habilitados.
device flash Flag indicando se o cliente tem Flash habilitados.
device ip Endereço de IP do cliente.
- geolocation Objeto contendo os dados de geolocalização do cliente.
geolocation city Cidade detectada na geolocalização.
geolocation state Estado detectado na geolocalização.
geolocation country País detectado na geolocalização.
- navigation Objeto contento os resumo de navegação do cliente.
navigation session_time Tempo da última sessão, em minutos.
navigation referrer Origem da visita.
navigation time_site_1d Tempo gasto no site pelo usuário no último dia, em minutos.
navigation new_accounts_1d Quantidade de contas criadas pelo usuário no último dia.
navigation password_resets_1d Quantidade de redefinições de senha do usuário no último dia.
navigation sales_declined_1d Quantidade de pedidos negados feitos pelo cliente no último dia.
navigation sessions_1d Número de visitas do usuário no último dia.
navigation time_since_last_sale Tempo desde a última compra do usuário, em minutos.
navigation time_site_7d Tempo gasto no site pelo usuário nos últimos 7 dias, em minutos.
navigation time_per_page_7d Tempo médio por página gasto pelo usuário nos últimos 7 dias, em minutos
navigation new_accounts_7d Quantidade de contas criadas pelo usuário na última semana.
navigation password_resets_7d Quantidade de redefinições de senha do usuário na última semana.
navigation checkout_count_7d Visualizações do carrinho de compras feitas pelo usuário na última semana.
navigation sales_declined_7d Quantidade de pedidos negados feitos pelo cliente na última semana.
navigation sessions_7d Número de visitas do usuário na última semana.
- travel Objeto que contém os dados de viagem e passageiros.
travel type Tipo de viagem.
travel departure Objeto com as informações do viagem de ida.
travel return Objeto com as informações do viagem de volta.
travel passengers Array de objetos com os dados dos passegeiros
travel departure/return Objeto que contém os dados de viagem (cada trecho)
departure
return
origin_city Cidade de origem.
departure
return
destination_city Cidade de destino.
departure
return
origin_airport Código IATA para o aeroporto de origem.
departure
return
destination_airport Código IATA para o aeroporto de destino.
departure
return
date Date e hora do embarque em UTC no formato YYYY-MM-DDThh:mmZ (ISO 8601)
departure
return
number_of_connections Número de conexões
departure
return
class Nome da classe, como economy, business e first
departure
return
fare_basis Código da classe.
travel passenger Objeto que contém os dados dos passageiros.
passengers name Nome completo do passangeiro.
passengers document Número do documento.
passengers document_type Tipo do documento. Pode ser passport ou id.
passengers dob Data de nascimento do passageiro no formato YYYY-MM-DD (ISO 8601).
passengers nationality País de nascimento do passageniro (ISO 3166-2)
passengers frequent_traveler Flag de viajante frequente.
passengers special_needs Passageiro com necessidades especiais.

Resposta da API de Blacklist

A resposta da API de Blacklist traz a confirmação da operação feita naquele registro, seja ela uma inserção, atualização, consulta ou remoção. Abaixo temos os detalhes de cada resposta.

Resposta da inserção

{
  "status": "ok",
  "uri": "/v1/blacklist/email/tom@tom.com",
  "expires_at": "2015-11-21"
}
Parâmetro Descrição
status Status da solicitação. Pode ser ok ou error.
uri Endereço do recurso que foi criado na Blacklist, para uso futuro.
expires_at Data em que a entrada será removida da Blacklist.

Resposta da atualização

{
  "status": "ok",
  "expires_at": "2015-11-22"
}
Parâmetro Descrição
status Status da solicitação. Pode ser ok ou error.
expires_at Data em que a entrada será removida da Blacklist.

Resposta da consulta

Exemplo de resposta de consulta de email

{
  "email_address": "tom@tom.com",
  "expires_at": "2015-11-21"
}
Parâmetro Descrição
status Status da solicitação. Pode ser ok ou error.
expires_at Data em que a entrada será removida da Blacklist.
email_address Endereço de email.

Resposta da remoção

{
  "status": "ok",
  "message": "deleted tom@tom.com from email blacklist"
}
Parâmetro Descrição
status Status da solicitação. Pode ser ok ou error.
message Mensagem de confirmação de remoção do registro.

Como fazer os seus testes

Nosso ambiente de teste permite que você integre com a nossa API e obtenha respostas previsíveis, podendo assim simular todos os cenários de uma operação real.

A recommendation do ambiente de teste varia de acordo com os centavos do valor da transação (campo total_amount), seguindo a tabela abaixo. Já o score retornado será o valor dos centavos.

Atenção: estas regras se aplicam somente para o nosso ambiente de testes.. Em Produção use o campo recommendation.

Centavos do valor Resposta simulada
*.00 - *.29 APPROVED
*.30 - *.60 REVIEW
*.61 - *.99 DECLINE

Notificações (Webhooks)

A notificação (webhook) é um serviço auxiliar que permite automatizar fluxos que dependem de mudanças no status de um pedido. Sempre que o pedido muda de status nós enviaremos um POST para uma URL especificada pela loja.

A partir desta notificação a loja pode seguir com o seu fluxo operacional, sem a necessidade de consultar um a um o status de pedidos pendentes.

Esta automação é feita para integrar o nosso sistema com a sua aplicação. As notificações por email podem ser configuradas diretamente no nosso Portal.

Parâmetros da notificação

O webhook envia um JSON que contém o número do pedido, a hora da mudança de status, o novo status que o pedido entrou e uma assinatura de validação.

{
  "order_id": "ORD1837213",
  "timestamp": 1608898332000,
  "status": "APPROVED",
  "signature": "6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30"
}
Parâmetro Descrição
order_id Identificador único do pedido, enviado pelo lojista.
timestamp Date e hora da notificação em milisegundos (Era Unix).
status Novo status do pedido, ao qual a notificação está se referindo.
Pode ser APPROVED, PENDING, DECLINED, CANCELED, NOT_AUTHORIZED e NOT_ANALYZED.
signature Assinatura de validação da notificação. É um HMAC-SHA-256 dos campos da notificação.
Veja abaixo como calcular a assinatura do webhook.

Recibo da notificação

{
  "status":"ok"
}

Nós esperamos que a resposta da notificação confirme que o evento foi recebido. Caso este recibo não seja enviado, nós tentaremos entregar o webhook novamente.

Você deve imprimir um JSON no corpo da resposta HTTP 200 que contém apenas um valor: {"status":"ok"}.

Ao ver esta mensagem nós entenderemos que a notificação foi recebida corretamente e não tentaremos outras entregas.

Calculando a assinatura

<?php 
// Define a chave privada
$private_key = "T738D516F09CAB3A2C1EE";

// JSON original recebido no webhook
$webhook = '{
  "order_id": "ORD1837213",
  "timestamp": 1608898332000,
  "status": "APPROVED",
  "signature": "6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30"
}';

// Transforma JSON em array
$arr = json_decode($webhook, true);

// Passa assinatura do webhook para variável $signature
$signature = $arr["signature"];

// Remove a assinatura do array
unset($arr["signature"]);

// Transforma o array em string concatenada por #
// ORD1837213#1608898332000#APPROVED
$to_hash = implode("#", $arr);

// Calcula o HMAC com os dados do webhook
$my_hash = hash_hmac("sha256", $to_hash, $private_key);

// 6c136402b15492ca764f2687d009a4f6ebd44a2c24fabe13dc6183a6da2ceb30
echo $my_hash;

// true
echo ($my_hash === $signature) ? true : false;
?>

A assinatura de validação do webhook serve para garantir a integridade da mensagem, evitando casos de spoofing. É altamente recomendado que você calcule e valide a assinatura de cada webhook recebido.

Cada webhook contém um HMAC-SHA-256 no campo signature, formado pela concatenação dos campos enviados na notificação, e usando a chave privada da API como segredo.

Os campos devem ser concatenados da seguinte forma:
order_id + # + timestamp + # + status

Tabelas de referência

Abaixo você encontrará as tabelas de referência que contém informações adicionais sobre a lista de moedas (campo currency) a de categorias de produtos (category).

Moedas mais comuns

Lista completa de moedas

Aqui nós listamos apenas as moedas mais usadas. Você pode encontrar a lista completa de códigos de moeda aqui

Código Moeda
USD Dólar Americano ($)
BRL Real Brasileiro (R$)
ARS Peso Argentino ($)
AUD Dólar Australiano ($)
CAD Dólar Canadense ($)
CLP Peso Chileno ($)
EUR Euro (€)
GBP Libra Esterlina (£)
JPY Iene Japonês (¥)
MXP Peso Mexicano ($)

Categorias de produtos

O que são as categorias?

Categorias de produto são importantes pois elas nos dizem o tipo de produto que está sendo comprado (sapatos, jóias ou um GPS). Comprar uma TV é muito diferente de comprar um livro, então as categorias fazem diferença para nós.

Esta lista foi baseada na taxonomia de produtos do Google e elas representam os principais agrupamentos de produtos.

Se você acha que há alguma categoria faltando fique à vontade para nos contactar no oi@konduto.com e nos avisar!

Descrição Código
Animais & Bichos de Estimação 100
Roupas e Acessórios
Roupas em Geral 201
Accessórios em Geral 202
Fantasias e Acessórios 203
Acessórios para Bolsas e Carteiras 204
Bolsas, Carteiras e Malas 205
Joias 206
Acessórios para Sapatos 207
Sapatos 208
Outros 299
Arte e Entretenimento 300
Bebês e Recém-nascidos 400
Negócios e Indústria
Propaganda e Marketing 501
Agricultura 502
Construção 503
Filme e Televisão 504
Finanças e Seguros 505
Serviços de Alimentação 506
Madeireiras 507
Maquinário Pesado 508
Hotel e Hospedagem 509
Armazém Industrial 510
Equipamentos Militares 511
Manufatura 512
Movimentação de Material 513
Medicina 514
Mineração 515
Piercing e tatuagem 516
Varejo 517
Ciência e Laboratórios 518
Placas e Sinais 519
Equipamentos de Segurança do Trabalho 520
Outros 599
Câmeras e Óticas
Câmeras 601
Acessórios de câmeras 602
Fotografia 603
Outros 699
Eletrônicos
Impressoras 3D 701
Áudio 702
Componentes de Circuito 703
Comunicação 704
Componentes 705
Computadores 706
Acessórios Eletrônicos 707
Aparelho GPS 708
Acessórios de GPS 709
Redes 711
Impressão, Cópia, Scanner e Fax 712
Acessórios de Impressão, Cópia, Scanner e Fax 713
Vídeo 715
Consoles de Vídeo Game 716
Acessórios de Vídeo Game 717
Outros 799
Comidas, Bebidas e Cigarro 800
Móveis 900
Ferramentas 1000
Saúde e Beleza 1100
Casa e Jardim 1200
Malas e Bagagens 1300
Adulto 1400
Armas e Munição 1500
Materiais de Escritório 1600
Religião e Cerimoniais 1700
Software
Software de Computador 1801
Bens e Moedas Digitais 1802
Serviços Digitais 1803
Jogos de Vídeo Games 1804
Outros 1899
Equipamento de Esporte 1900
Brinquedos e Jogos 2000
Veículos e Peças 2100
Livros 2300
DVDs e Vídeos 2400
Revistas e Jornais 2500
Música
CDs e Vinil 2601
Instrumentos Musicais 2602
Música Digital 2603
Outros 2699
Outras categorias não especificadas 9999