Atualização de Pedidos
Você pode enviar informações relacionadas a atualização de status de pedidos para a Legiti por meio do endpoint
/order
usando uma requisição do tipo PUT
. Além disso, você também pode marcar um pedido como fraudulento usando o endpoint /order/mark\_fraudulent
POST
, atualizar informações de um pagamento através do endpoint /order/payment
PUT
, e atualizar as informações de um entrega através do endpoint /order/delivery
PUT
.Você deve usar esse endpoint para atualizar a Legiti toda vez que um pedido tem seu status alterado.
{
"id": "12345",
"status": "cancelled",
"status_reason": "User requested"
}
Propriedade | Tipo | Descrição |
---|---|---|
id | String | O identificador exclusivo do pedido na sua plataforma. Deve ser o mesmo id utilizado na criação do pedido |
status | String | Status do pedido. Valores permitidos: approved , declined , pending , cancelled , manual_analysis , unauthorized . Você pode ver mais sobre isso aqui |
status_reason | String | O motivo para a mudança de status. |
custom_data | JSON para captura de dados customizados para cada cliente |
Você deve usar esse endpoint para atualizar a Legiti quando um pedido for rejeitado ou cancelado devido a uma suspeita de fraude ou se um pedido virou um chargeback.
Se um pedido for considerado fraudulento (seja através de sua solução antifraude, análise manual, rejeição pelo adquirente, ou mesmo se você receber um chargeback), é extremamente importante que você envie essa informação para a Legiti. Esta é talvez a informação mais valiosa que você nos pode enviar; todos os nossos modelos de predição de fraude são treinados com essa tag.
{
"order_id": "12345",
"fraud_signal_type": "chargeback"
}
Propriedade | Tipo | Descrição |
---|---|---|
order_id | String | O identificador exclusivo do pedido na sua plataforma |
fraud_signal_type | String | O mecanismo pelo qual você identificou a ordem como fraudulenta. Os valores aceitos são: _ acquirer , manual_analysis , chargeback , third_party_antifraud , other . Você pode ver mais sobre isso aqui |
fraud_comment | String | Para adicionar informações relevantes sobre fraud_signal_type . É recomendado quando o fraud_signal_type é other ou third_party_antifraud |
custom_data | JSON para captura de dados customizados para cada cliente |
Você deve usar esse endpoint para atualizar a Legiti sempre que uma entrega tiver seus dados alterados. É importante ressaltar que caso precise indicar que o pedido foi entregue, você deve passar um valor no campo
delivery_datetime
dessa entidade, assim a Legiti entenderá que o item foi entregue.{
"id": "1569723",
"order_id": "12345",
"delivery_datetime": "2020-12-17T00:48:03Z",
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}
Propriedade | Tipo | Descrição |
---|---|---|
id | String | O identificador exclusivo da entrega (delivery) em sua plataforma. Saiba que esse é o ID usado para atualizar as informações de entrega posteriormente |
order_id | String | O identificador exclusivo do pedido na sua plataforma. Deve ser o mesmo id utilizado na criação do pedido |
type | String | O tipo de entrega (delivery). Os valores permitidos são: normal , express , e pickup |
delivery_datetime | String | |
deliverer | Informações sobre o entregador da encomenda | |
scheduled | Boolean | Indica se a entrega está agendada para uma data futura |
custom_data | JSON para captura de dados customizados para cada cliente |
Formato padronizado da Legiti para representar um entregador.
{
"id": "456987",
"name": "João Entregador",
"email": "[email protected]",
"document": "123.456.789-10",
"document_type": "cpf",
"phone_number": "11999123456",
"phone_country_code": "55",
"password_hash": "effebbbeeabc123",
"gender": "male",
"creation_datetime": "2019-12-17T00:48:03Z",
"address": {
"street_name": "Rua Fidalga",
"street_number": "252",
"zip_code": "05432-010",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"details": "Apto 11",
"label": "Casa"
}
}
Propriedade | Tipo | Descrição |
---|---|---|
id | String | O identificador exclusivo do entregador na sua plataforma |
email | String | O e-mail principal associado ao entregador |
document | String | O número do documento associado ao entregador |
document_type | String | O tipo do documento utilizado. Valores aceitos são cpf , cnpj , passport , rg , rne e other |
phone_number | String | O número de telefone principal associado ao entregador (apenas números; código do país não incluído). Nota: se o phone_number é fornecido, phone_country_code também é obrigatório |
phone_country_code | String | Código do país associado ao número de telefone (apenas números). Nota: se o phone_country_code é fornecido, phone_number também é obrigatório |
senha_hash | String | A senha protegida (salted e hashed) associada com o entregador |
name | String | Nome completo do entregador |
gender | String | O gênero do entregador. Os valores aceitos são: male , female , other , e undisclosed |
user_type | String | O tipo de entregador na sua plataforma. Os valores aceitos são: consumer , service_provider |
social_login | String | Se o entregador se cadastrou usando um serviço de terceiros. Valores aceitos são: facebook , apple , google , twitter |
creation_datetime | String (formato YYYY-MM-DDTHH:mm:ssZ em UTC) | A data e hora de quando a conta do entregador foi criada |
address | O endereço associado ao entregador | |
custom_data | JSON para captura de dados customizados para cada cliente |
Você deve usar esse endpoint para informar a Legiti o indentificador da adquirente para um pagamento. Esse endpoint deve ser utilizado apenas caso o campo
acquirer_id
não tenha sido enviado durante a criação do pedido. Essa entidade deve ser raramente utilizada, caso tenha dúvida se deve ou não utilizar entre em contato com seu time de Solutions{
"id": "852456",
"order_id": "12345",
"acquirer_id": "54d5sf4654fsdwhd"
}
Propriedade | Tipo | Descrição |
---|---|---|
id | String | O identificador exclusivo do pagamento na sua plataforma. Deve ser o mesmo id utilizado na criação do pedido |
order_id | String | O identificador exclusivo do pedido na sua plataforma. Deve ser o mesmo id utilizado na criação do pedido |
acquirer_id | String | O identificador único para cada transação retornada pela adquirente/gateway. Este identificador é usado para vincular chargebacks |
custom_data | JSON para captura de dados customizados para cada cliente |
Estas são as descrições para o campo
status
na entidade Pedido:
Status do pedido
Status | Descrição |
---|---|
approved | O pedido foi aprovado e é esperado que seja entregue ao consumidor |
declined | O pedido foi rejeitado por suspeita de fraude (tanto da Legiti ou por outro provedor de anti-fraude) |
pending | O pedido não foi nem rejeitado, nem aprovado, e seu pagamento ainda não foi processado. Você ainda está decidindo se deve aprovar ou rejeitar o pedido |
cancelled | O pedido foi cancelado ou reembolsado e não será mais entregue ou o consumidor está devolvendo |
manual_analysis | O pedido foi enviado a um humano para revisão |
unauthorized | O pagamento não foi aprovado pela adquirente |
Estas são as descrições para o campo
fraud_signal_type
na entidade pedido marcado fraudulento:Status | Descrição |
---|---|
acquirer | O pagamento foi rejeitado pela adquirente devido a suspeita de fraude |
manual_analysis | O pedido foi revisado por um humano e rejeitado por suspeita de fraude |
chargeback | Esse pedido gerou um chageback |
third_party_antifraud | O pedido foi rejeitado por outro provedor de solução de anti-fraude. Somente usado quando trabalhando com uma outra solução de anti-fraude em paralelo com a Legiti. Esteja ciente de que você deve passar o nome da solução de anti-fraude no campo fraud_comment |
other | Outro sinal indicando fraude ou suspeita de fraude. Neste caso, recomendamos que você passe mais detalhes através do campo fraud_comment |
Notifique a Legiti sempre que o status de um pedido for atualizado.
Curl
Python
Node.js
PHP
Ruby
Java
curl -X PUT https://legiti-api.lgtcdn.net/v2/order \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "12345",
"status": "unauthorized",
"status_reason": "Invalid card number"
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '12345',
'status': 'unauthorized',
'status_reason': 'Invalid card number',
}
try:
response = requests.put(
'https://legiti-api.lgtcdn.net/v2/order',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'id': '12345',
'status': 'unauthorized',
'status_reason': 'Invalid card number'
};
fetch(url, { method: 'PUT', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'id' => '12345',
'status' => 'unauthorized',
'status_reason' => 'Invalid card number'
);
$options = array(
'timeout' => 2,
);
$response = Requests::put(
'https://legiti-api.lgtcdn.net/v2/order',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order")
request = Net::HTTP::Put.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"id" => "12345",
"status" => "unauthorized",
"status_reason" => "Invalid card number"
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"id\": \"12345\",
\"status\": \"unauthorized\",
\"status_reason\": \"Invalid card number\"
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order")
.method("PUT", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
Propriedade | Obrigatória | Tipo |
---|---|---|
id | Sim | String |
status | Sim | String (valores aceitos: approved , declined , pending , cancelled , manual_analysis , unauthorized ) |
status_reason | Não | String |
custom_data | Não | JSON pré-definido |
Notifique a Legiti quando descobrir que um pedido é fraudulento.
Curl
Python
Node.js
PHP
Ruby
Java
curl -X POST https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent \
-H "Authorization: Bearer $API_KEY" \
-d '{
"order_id": "12345",
"fraud_signal_type": "chargeback",
"fraud_comment": "This is a chargeback",
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'order_id': '12345',
'fraud_signal_type': 'chargeback',
'fraud_comment': 'This is a chargeback',
}
try:
response = requests.post(
'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'order_id': '12345',
'fraud_signal_type': 'chargeback',
'fraud_comment': 'This is a chargeback'
};
fetch(url, { method: 'POST', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'order_id' => '12345',
'fraud_signal_type' => 'chargeback',
'fraud_comment' => 'This is a chargeback',
);
$options = array(
'timeout' => 2,
);
$response = Requests::post(
'https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent")
request = Net::HTTP::Post.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"order_id" => "12345",
"fraud_signal_type" => "chargeback",
"fraud_comment" => "This is a chargeback",
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"order_id\": \"12345\",
\"fraud_signal_type\": \"chargeback\",
\"fraud_comment\": \"This is a chargeback\",
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent")
.method("POST", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
Propriedade | Obrigatória | Tipo |
---|---|---|
order_id | Sim | String |
fraud_signal_type | Sim | String (valores aceitos: acquirer , manual_analysis , chargeback , third_party_antifraud , other ) |
fraud_comment | Não | String |
custom_data | Não | JSON pré-definido |
Deve ser utilizado apenas para clientes que utilizam a API de criação e avaliação de pedidos no formato para E-commerce
caso precise indicar que o pedido foi entregue, você deve passar um valor no campo
delivery_datetime
dessa entidade, assim a Legiti entenderá que o item foi entregueNotifique a Legiti sempre que informações de entrega forem atualizadas.
Curl
Python
Node.js
PHP
Ruby
Java
curl -X PUT https://legiti-api.lgtcdn.net/v2/order/delivery \
-H "Authorization: Bearer $API_KEY" \
-d '{
"id": "974613",
"order_id": "12345",
"delivery_datetime": "2020-12-17T00:48:03Z",
"deliverer": {
"id": "456987",
"name": "João Entregador"
}
}'
import json
import requests
headers = {
'Authorization': 'Bearer $API_KEY',
}
data = {
'id': '974613',
'order_id': '12345',
'delivery_datetime': '2020-12-17T00:48:03Z',
'deliverer': {
'id': '456987',
'name': 'João Entregador'
}
}
try:
response = requests.put(
'https://legiti-api.lgtcdn.net/v2/order/delivery',
headers=headers,
data=json.dumps(data),
timeout=2,
)
except requets.exceptions.TimeoutError as e:
print(e)
import fetch from 'node-fetch'
import AbortController from 'node-abort-controller'
const url = 'https://legiti-api.lgtcdn.net/v2/order/delivery';
const controller = new AbortController();
const signal = controller.signal;
setTimeout(() => controller.abort(), 2000);
var headers = {
'Authorization': 'Bearer $API_KEY'
};
var data = {
'id': '974613',
'order_id': '12345',
'delivery_datetime': '2020-12-17T00:48:03Z',
'deliverer': {
'id': '456987',
'name': 'João Entregador'
}
};
fetch(url, { method: 'PUT', headers: headers, body: data, signal: signal})
.then((res) => {
return res.json()
})
.then((json) => {
console.log(json);
// Do something with the returned data.
});
<?php
include('vendor/rmccue/requests/library/Requests.php');
Requests::register_autoloader();
$headers = array(
'Authorization' => 'Bearer $API_KEY'
);
$data = array(
'id' => '974613',
'order_id' => '12345',
'delivery_datetime' => '2020-12-17T00:48:03Z',
'deliverer' => array(
'id' => '456987',
'name' => 'João Entregador'
)
);
$options = array(
'timeout' => 2,
);
$response = Requests::put(
'https://legiti-api.lgtcdn.net/v2/order/delivery',
$headers,
json_encode($data),
$options
);
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://legiti-api.lgtcdn.net/v2/order/delivery")
request = Net::HTTP::Put.new(uri)
request.read_timeout = 2
request["Authorization"] = "Bearer $API_KEY"
request.body = JSON.dump({
"id" => "974613",
"order_id" => "12345",
"delivery_datetime" => "2020-12-17T00:48:03Z",
"deliverer" => {
"id" => "456987",
"name" => "João Entregador"
}
})
req_options = {
use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
http.request(request)
end
import okhttp3.*;
OkHttpClient client = new OkHttpClient().newBuilder()
.setConnectTimeout(2, TimeUnit.SECONDS)
.build();
String data = "{
\"id\": \"974613\",
\"order_id\": \"12345\",
\"delivery_datetime\": \"2020-12-17T00:48:03Z\",
\"deliverer\": {
\"id\": \"456987\",
\"name\": \"João Entregador\"
}
}"
RequestBody body = RequestBody.create(mediaType, data)
Request request = new Request.Builder()
.url("https://legiti-api.lgtcdn.net/v2/order/delivery")
.method("PUT", body)
.addHeader("Authorization", "Bearer $API_KEY")
.build();
Response response = client.newCall(request).execute();
Propriedade | Obrigatória | Tipo |
---|---|---|
id | Sim | String |
order_id | Sim | String |
type | Não | String (valores aceitos: normal , express , pickup ) |
delivery_datetime | Não | String (formato YYYY-MM-DDTHH:mm:ssZ em UTC) |
scheduled | Não | Boolean |
deliverer* | Não | |
↳ id | Sim | String |