Atualização de Pedidos

Search…
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
Quando o status de pedido é atualizado​
Quando um pedido é marcado como fraudulento​
Quando um pagamento é atualizado​
Quando uma entrega é atualizada​
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
​Dados customizáveis​
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
​Dados customizáveis​
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
​Entregador​
Informações sobre o entregador da encomenda
scheduled
Boolean
Indica se a entrega está agendada para uma data futura
custom_data
​Dados customizáveis​
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
​Dados customizáveis​
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
​Dados customizáveis​
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
PUT https://legiti-api.lgtcdn.net/v2/order​
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
POST https://legiti-api.lgtcdn.net/v2/order/mark_fraudulent​
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
PUT https://legiti-api.lgtcdn.net/v2/order/delivery​
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
​Entregador​
 ↳ id
Sim
String
 name
Sim
String
 email
Não
String
 creation_datetime
Não
String (formato YYYY-MM-DDTHH:mm:ssZ em UTC)
 social_login
Não
String (Valores aceitos são: facebook, apple, google, twitter)
 document
Não
String
 document_type
Não
String
 phone_number
Não
String
 phone_country_code
Não
String
 password_hash
Não
String
 gender
Não
String (valores aceitos são: male, female, other, e undisclosed)
 address*
Não
​Address​
  ↳ street_name
Sim
String
  street_number
Sim
String
  city
Sim
String
  state
Sim
String
  country
Sim
String
  zip_code
Não
String
  details
Não
String
  label
Não
String
  latitude
Não
Float
  longitude
Não
Float
  custom_data
Não
JSON pré-definido
 custom_data
Não
JSON pré-definido
custom_data
Não
JSON pré-definido
*A entidade não é obrigatória mas, se incluída, alguns de seus campos são
Atualização de pagamento
PUT https://legiti-api.lgtcdn.net/v2/order/payment​
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
Notifique a Legiti sobre o código da adquirente de um pagamento.
É 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/payment \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
        "id": "974613",
        "order_id": "12345",
        "acquirer_id": "12645762"
    }'
import json
​
import requests
​
headers = {
    'Authorization': 'Bearer $API_KEY',
}
​
data = {
    'id': '974613',
    'order_id': '12345',
    'acquirer_id': '12645762'
}
​
try:
    response = requests.put(
        'https://legiti-api.lgtcdn.net/v2/order/payment',
        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/payment';
​
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',
    'acquirer_id': '12645762'
};
​
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',
    'acquirer_id' => '12645762'
);
​
$options = array(
    'timeout' => 2,
);
​
$response = Requests::put(
    'https://legiti-api.lgtcdn.net/v2/order/payment',
    $headers,
    json_encode($data),
    $options
);
require 'net/http'