Português
Search
⌃K
Links

Atualização de Pedidos

Visão geral

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.

Quando rastrear

Você pode ver mais informações sobre onde adicionar estes endpoints no seu fluxo de pagamento aqui

Entidades

Atualização de status de um pedido

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

Pedido Marcado como Fraudulento

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

Atualização de entrega

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
Data em que o item foi entregue em UTC seguindo o formato ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
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

Entregador

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
Address
O endereço associado ao entregador
custom_data
JSON para captura de dados customizados para cada cliente

Atualização de pagamento

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

Descrição dos Status

Status de Pedido

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

Pedido Marcado como Fraudulento

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

Endpoints da API

Atualização de status de um pedido

Notifique a Legiti sempre que o status de um pedido for atualizado.
É importante aderir às nossas melhores práticas de tratamento de erros de API
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();
Você pode dar uma olhada nas respostas aqui
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

Marcar Pedido como Fraudulento

Notifique a Legiti quando descobrir que um pedido é fraudulento.
É importante aderir às nossas melhores práticas de tratamento de erros de API
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();
Você pode dar uma olhada nas respostas aqui
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

Atualização de entrega

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 entregue
Notifique a Legiti sempre que informações de entrega forem atualizadas.
É importante aderir às nossas melhores práticas de tratamento de erros de API
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();
Você pode dar uma olhada nas respostas aqui
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