Documentação

VENDAS

Os seguintes serviços permitem buscar, obter e atualizar a informação das vendas realizadas sobre anúncios, tanto no MercadoLivre quanto na loja.

Indice

Busca Busca por Id Busca por filtros Atualizar os dados de Faturamento Atualizar os dados de Shipping

Ações

BUSCA POR ID

Retorna a informação de uma venda identificada pelo seu ID

GET  /v1/shops/{SHOP_ID}/orders/{ORDER_ID} 

Mostrar exemplo 
https://api.mercadoshops.com/v1/shops/{SHOP_ID}/orders/{order_id}?access_token={access_token} 

Parâmetros

ParâmetroValoresExemplo
access_token Código de segurança access_token=APP_USR-4X30-XXXXX-
SHOP_ID Id da loja https://api.mercadoshops.com/v1/shops /15XXXXX24/
ORDER_ID Id da venda https://api merdoshops.com/v1/shops/15XXXXX24/orders/11111111?acess_token=**************
{
id
Id único da venda
Tipo
STRING
store_id
Id da loja
Tipo
NUMERICO
channel
Canal de venda
Tipo
STRING
Valores Possíveis:
mshops
mercadoshops
meli
mercadolivre
external_reference
Número de referência externa da venda. Quando channel=meli, este ID coincide com o ID de venda do MercadoLivre.
Tipo
NUMERICO
currency
Moeda da venda
Tipo
STRING
amount
Valor da Venda
Tipo
NUMERICO
products_total
Soma total da quantidade de produtos
Tipo
NUMERICO
products_discounts_total
Soma total da quantidade de descontos nos produtos
Tipo
NUMERICO
products_grand_total
Soma total da quantidade de produtos incluindo descontos (subtotal da venda)
Tipo
NUMERICO
discounts_total
Soma total dos descontos aplicados após o subtotal da venda.
Tipo
NUMERICO
shipping_total
Soma total da quantidade de envios
Tipo
NUMERICO
grand_total
Quantidade total da venda
Tipo
NUMERICO
creation_date
Data da realização da venda
Tipo
Date(ISO_8601)
buyer_message
Mensagem do comprador
Tipo
STRING
status
{ Estados da venda
Tipo
OBJETO
delivered
Indica se o envio foi concretizado.
Tipo
BOOLEAN
Valores Possíveis
true
Despacho realizado
false
Despacho sem realizar
paid
Indica se o pagamento foi realizado.
Tipo
BOOLEAN
Valores Possíveis
true
Pagamento realizado
false
Pagamento sem realizar
closed
Para vendas com channel=meli, indica que o processo foi finalizado após ambas as partes foram qualificadas. Para vendas com channel=mshops, indica que o processo foi finalizado ao efetuar a entrega, ter sido cancelado ou ter expirado.
Tipo
BOOLEAN
Valores Possíveis
true
Venda finalizada
false
Venda aberta
closed_reason
Motivo da venda finalizada
Tipo
STRING
closed_date
Data de fechamento da venda
Tipo
Date(ISO_8601)
processed
A venda está sendo preparada para o envio ou já foi despachada
Tipo
BOOLEAN
Valores Possíveis
true
Venda aprovada
false
Venda sem aprovar
processed_date
Data de aprovação da venda
Tipo
Date(ISO_8601)
contact_data_status
new,
order_status
null
},
buyer
{ Informação do comprador
Tipo
OBJETO
id
Id de uso interno
Tipo
NUMERICO
meli_cust_id
null,
name
nome e sobrenome do comprador
Tipo
STRING
nickname
null,
client_id
Id do cliente
Tipo
NUMERICO
mail
Email do comprador
Tipo
STRING
mail2
Opcional. Segundo email do comprador
Tipo
STRING
phone
Telefone do comprador
Tipo
STRING
phone2
Opcional. Segundo telefone do comprador
Tipo
STRING
doc_number
Número do documento
Tipo
NUMERICO
doc_type
Tipo de documento
Tipo
STRING
},
billing_data
{ Dados para o faturamento
Tipo
OBJETO
store_id
Id da loja
Tipo
NUMERICO
name
nome e sobrenome do comprador
Tipo
STRING
email
email do comprador
Tipo
STRING
phone
Telefone do comprador
Tipo
STRING
zip_code
CEP do comprador
Tipo
STRING
address
{ Endereço de faturamento
Tipo
OBJETO
additional_info
Informação adicional de endereço
Tipo
STRING
street
Rua do endereço
Tipo
STRING
number
número do endereço
Tipo
STRING
city
cidade do endereço
Tipo
STRING
state
ID do estado/cidade do País
Tipo
STRING
Para obter a lista de IDs de estados/cidades de cada país utilize este recurso:
EXEMPLO:
id
"AR-B",
name
"Buenos Aires"
},
recipient
{ Identificação da pessoa para quem vai faturar a venda
doc_number
Documento de identificação
Tipo
STRING
type
Tipo de documento
Tipo
STRING
},
id
Id de uso interno
Tipo
NUMERICO
},
payments
[ Dados dos pagamentos realizados
Tipo
OBJETO
{
id
Id do pagamento
Tipo
NUMERICO
external_reference
Número de referência externa do pagamento. Quando channel=meli e provider=mercadopago, indica o número de pagamento no MercadoPago.
Tipo
NUMERICO
status
Estado do pagamento
Tipo
STRING
Valores Possíveis
pending
O usuário não completou o processo de pagamento
approved
O pagamento foi aprovado
in_process
O pagamento está sendo revisado
rejected
O pagamento foi rejeitado. O usuário pode repetir o pagamento
cancelled
O pagamento foi cancelado por uma das partes, o tempo de espera do pagamento expirou
refunded
O pagamento foi devolvido ao usuário
charged_back
Foi feita uma contestação ao cartão de crédito do usuário
provider
Empresa que gerenciou o pagamento
Tipo
STRING
method
Método de pagamento utilizado
Tipo
STRING
currency
Moeda de pagamento
Tipo
STRING
Valores Possíveis
ARS
Argentine peso
BRL
Brazilian real
VEF
Venezuelan strong bolivar
CLP
Chilean peso
MXN
Mexican peso
COP
Colombian peso
UYU
Uruguayan peso
amount
Valor do pagamento
Tipo
NUMERICO
paid
Indica se o pagamento foi concretizado.
Tipo
BOOELAN
Valores Possíveis
true
Venda pago
false
Venda não remunerado
paid_date
Data do pagamento
Tipo
Date(ISO_8601)
installments
Quantidade de parcelas do pagamento
Tipo
NUMERICO
fees
{ Tarifa aplicada ao pagamento
Tipo
OBJETO
finance_fee
Valor da tarifa financeira
Tipo
NUMERICO
}
}
],
shippings
[ Dados do envio
Tipo
OBJETO
{
id
Id de uso interno
Tipo
NUMERICO
external_reference
Número de referência externa do envio
Tipo
NUMERICO
ship_type
Tipo de Envio
Tipo
STRING
Valores Possíveis
not specified
Significa que o vendedor não especificou um preço de envio do seu item e que o comprador deve entrar em contato com o vendedor para arranjar uma opção de entrega e preço de compra.
custom
Vendedores podem incluir uma tabela de até 10 os custos de transporte sobre um item.
me1
(MercadoEnvios mode 1) Este método oferece uma calculadora de transporte para os custos de envio para todos os itens que permite que o vendedor para escolher.
me2
(MercadoEnvios mode 2) Este método fornece o vendedor uma etiqueta de código deseguimiento e pré- pagamento com a empresa de transporte escolhido por MercadoLivre .
channel_status
Estado do envio fornecido pelo canal.
status
Estado do envio normalizado (independentemente do canal)
receiver
{ Dados da pessoa que recebe o produto
Tipo
OBJETO
doc_number
Número do documento
Tipo
NUMERICO
doc_type
Tipo de documento
Tipo
STRING
name
Nome e sobrenome
Tipo
STRING
email
email
Tipo
STRING
phone
telefone
Tipo
STRING
address
Enredeço de entrega
Tipo
STRING
zip
CEP
Tipo
STRING
neighbourhood
Bairro
Tipo
STRING
municipality
Município
Tipo
STRING
city
Cidade
Tipo
STRING
state_id
ID de estado/cidade do País
Tipo
STRING
Para obter a lista de IDs de estados/cidades de cada país utilize este recurso:
Exemplo:
id
AR-B,
name
Buenos Aires
country_id
ID do País
Tipo
STRING
Para obter a lista de códigos dos países habilitados utilize este recurso:
Ejemplo:
id
AR,
name
Argentina
locale
es_AR
currency_id
ARS
},
additional_info
Informação adicional para a entrega
Tipo
STRING
method_id
Id do método de entrega
Tipo
NUMERICO
method
Nome do método de entrega
Tipo
STRING
currency
Moeda de pagamento
Tipo
STRING
Valores Possíveis
ARS
Argentine peso
BRL
Brazilian real
VEF
Venezuelan strong bolivar
CLP
Chilean peso
MXN
Mexican peso
COP
Colombian peso
UYU
Uruguayan peso
amount
Quantidade do envio
Tipo
NUMERICO
tracking_code
Código de rastreamento do envio
Tipo
STRING
observations
Observações
Tipo
STRING
date_created
Data de envio
Tipo
Date(ISO_8601)
}
],
invoice
{ Dados do faturamento
Tipo
OBJETO
invoiced
Indica se a venda foi faturada
Tipo
BOOLEAN
Valores Possíveis
true
Venda faturada
False
Venda não faturada
type
Tipo de comprovante emitido
Tipo
STRING
number
Número de comprovante
Tipo
STRING
invoiced_date
Data de faturamento da venda
Tipo
Date(ISO_8601)
},
products
[ Informação dos produtos comprados
Tipo
ARRAYS
{
id
ID do produto
Tipo
NUMERICO
channel
Canal de venda do produto
Tipo
STRING
Valores Possíveis
mshops
mercadoshops
meli
mercadolivre
external_reference
Referência externa do produto
Tipo
STRING
sku
Código de identificação do produto
Código de identificação do produto.
Tipo
STRING
SKU wikipwedia acordo:
title
Título do produto
Tipo
STRING
quantity
Quantidade vendida
Tipo
NUMERICO
method
Método de entrega
Tipo
STRING
currency
Moeda da venda
Tipo
STRING
Valores Possíveis
ARS
Argentine peso
BRL
Brazilian real
VEF
Venezuelan strong bolivar
CLP
Chilean peso
MXN
Mexican peso
COP
Colombian peso
UYU
Uruguayan peso
unit_price
Preço unitário do produto
Tipo
NUMERICO
amount
Quantidade total. Quantidade Vendida * Preço Unitário .
Tipo
NUMERICO
free_shipping
Indica se o produto tem envio grátis
Tipo
BOOLEAN
Valores Possíveis
true
ENVIO GRÁTIS
false
NO TRANSPORTE LIVRE
meli_variation_id
Se é um produto do MercadoLivre, indica o ID da variação tamanho / cor do produto
Tipo
NUMERICO
variations
[ Lista de características que definem a variação (ex. tamanho e cor)
Tipo
OBJETO
{
name
Nome da característica da variação
Tipo
STRING
value
Valor da característica
Tipo
STRING
}
],
promotion
Promoção incluída no produto
Tipo
STRING
},
PRODUCTO NRO 2
{
PRODUCTO NRO 3
},
{
PRODUCTO NRO 4
},
{
PRODUCTO NRO 5
}
],
notes
[],
feedback
{
buyer
null,
seller
null
},
promotions
[],
free_shipping
false
}
{
id
1999999999999,
store_id
15999999999,
channel
"meli",
external_reference
999999999999,
currency
"ARS",
amount
1405,
products_total
1405,
products_discounts_total
0 ,
products_grand_total
1405 ,
discounts_total
0 ,
shipping_total
57.99 ,
grand_total
1462.99 ,
creation_date
" 2015-09-10T07:31:03.000-04:00 ",
buyer_message
null ,
products_discounts_total
0 ,
products_discounts_total
0 ,
status
{
delivered
false,
paid
true,
closed
false,
closed_reason
null,
closed_date
null,
processed
true,
processed_date
null,
contact_data_status
"new",
order_status
"paid",
},
buyer
{
id
899999999999,
meli_cust_id
15399999999,
name
"Carlos Perez",
nickname
"CARLLLLLLLLLLL",
client_id
379999999999,
mail
null,
mail2
null,
phone
null,
phone2
null,
doc_number
null,
doc_type
null,
},
payments
[
{
id
1199999999,
external_reference
130299999999999,
status
"approved",
provider
"mercadopago",
method
"pagofacil",
currency
"ARS",
amount
1405,
paid
true,
paid_date
"2015-09-16T09:47:28.000-04:00",
installments
null,
fees
{
finance_fee
null
}
}
],
shippings
[
{
id
4699999,
external_reference
21499999,
ship_type
"me2",
channel_status
"on_route",
status
"on_route",
receiver
{
doc_type
null,
doc_number
"9999999999",
name
"Carlos Perez",
email
null,
phone
"0353999999",
address
"Calle 51",
zip
"999",
neighbourhood
null,
municipality
null,
city
"Las 99999",
state_id
"AR-X",
country_id
"AR",
},
additional_info
null,
method_id
152,
method
"Estándar",
currency
"ARS",
amount
57.99,
tracking_code
"3899999999999961",
observations
null,
date_created
"2015-09-16T09:47:31.000-04:00"
}
],
invoice
{
invoiced
false,
type
null,
number
null,
invoiced_date
null,
},
products
[
{
id
879999910,
channel
"meli",
external_reference
"MLA99999999999",
sku
null,
title
"Zapatillas 99999",
sku
null,
quantity
1,
currency
"ARS",
unit_price
1405,
amount
1405,
free_shipping
false,
meli_variation_id
91999949,
variations
[
{
name
"Color Primario",
value
"Negro"
},
{
name
"Talle",
value
"41.5"
},
{
name
"Color Secundario",
value
"Azul"
}
],
promotion
null
}
],
notes
[],
feedback
{
buyer
null,
seller
null
},
promotions
[],
free_shipping
null
}
BUSCA POR FILTROS
GET  /v1/shops/{SHOP_ID}/orders/SEARCH 

Mostrar exemplo 
https://api.mercadoshops.com/v1/shops/{SHOP_ID}/orders/search?status=unanswered&limit=10&orders=question_date_asc&access_token={access_token} 

Parâmetros

ParâmetroValoresExemplo
access_token Código de segurança access_token=APP_USR-4X30-XXXXX-
SHOP_ID Id da loja https://api.mercadoshops.com/v1/shops /15XXXXX24/

FILTROS

NomeValoresExemplo
status new: Nova Venda

first_contact: Primeiro contato realizado

confirmed_data: Venda com dados de contato confirmados
status=new
processed true: Venda aprovada

false: Venda sem aprovar
processed=true
paid true: Venda paga

false: Não paga
paid=true
delivered true: Venda despachada

false: Sem despachar
delivered=true
closed true: venda finalizada

false: sem finalizar
closed=true
channel mshops: canal de venda mercadoshops

meli: canal de venda mercadolivre
channel=mshops
buyer_feedback true: qualificação do comprador realizada

false: qualificação do comprador pendente
buyer_feedback=true
seller_feedback true: qualificação do vendedor realizada

false: qualificação do vendedor pendente
seller_feedback=true
feedback true: qualificação do comprador e vendedor realizada

false: qualificação do comprador e vendedor pendente
feedback=true
shipping Pending : Envio pendente

pickup: Envio levantado del vendedor

on_route: Envio a caminho

print_tag: etiqueta impressa

to_be_agreed: envio a convener

in_progress: em progresso

delivered: Entregue
shipping=pending

PAGINAÇÃO E ORDENAÇÃO

NomeValoresExemplo
limit Limite de itens devolvidos limit=10
orders creation_date_asc

Ordem por data de criação crescente

creation_date_desc

Ordem por data de criação decrescente

client_id_asc

Ordem por cliente_id crescente

client_id_desc

Ordem por cliente_id decrescente

name_asc

Ordem por nome do cliente crescente

name_desc

Ordem por nome do cliente decrescente

total_last_updated_asc

Ordem total por última atualização crescente

total_last_updated_sasc

Ordem total por última atualização decrescente
orders=creation_date_asc
{
seller_id
Id da loja
Tipo
NUMERICO
query
Palavra usada para fazer a busca
Tipo
STRING
paging
{
Descrição
Resumen del Paginado
Tipo
OBJETO
total
Resultados totais da busca
Tipo
NUMERICO
offset
Número de registro a partir do qual são devolvidos os resultados nesta resposta
Tipo
NUMERICO
limit
Limite dos resultados devolvidos por cada resposta
Tipo
NUMERICO
},
results
[
{
RESPOSTA ESTRUCTRA UMA PUBLICAÇÃO
},
{
RESPOSTA ESTRUCTRA UMA PUBLICAÇÃO
},
],
orders
[ ordem APLICADA
Tipo
OBJETO
{
id
"creation_date_desc",
name
"Order by creation date descending"
}
],
filters
[ Filtros APLICADOS
Tipo
OBJETO
{
id
"channel",
name
"Channel",
values
[
{
id
"meli",
name
"Meli orders",
results
707
}
]
}
],
available_orders
[ ordenação Disponível
Tipo
OBJETO
{
id
"creation_date_asc",
name
"Order by creation date ascending"
},
{
id
"creation_date_desc",
name
"Order by creation date descending"
},
{
id
"client_id_asc",
name
"Order by client id ascending"
},
{
id
"client_id_desc",
name
"Order by client id descending"
},
{
id
"name_asc",
name
"Order by client name ascending"
},
{
id
"name_desc",
name
"Order by client name ascending"
},
{
id
"total_last_updated_asc",
name
"Order by total last updated ascending"
},
{
id
"total_last_updated_desc",
name
"Order by total last updated descending"
}
],
available_filters
[ Filtros Disponibles
Tipo
OBJETO
{
id
"status",
name
"Status",
values
[
{
id
"new",
name
"New orders",
results
0
},
{
id
"first_contact",
name
"Orders with first contact made",
results
0
},
{
id
"confirmed_data",
name
"Orders with confirmed data",
results
0
},
]
},
{
id
"processed",
name
"Processed",
values
[
{
id
"true",
name
"Processed orders",
results
0
},
{
id
"false",
name
"Not processed orders",
results
0
}
]
},
{
id
"paid",
name
"Paid",
values
[
{
id
"true",
name
"Paid orders",
results
0
},
{
id
"false",
name
"Not paid orders",
results
0
}
]
},
{
id
"delivered",
name
"Delivered",
values
[
{
id
"true",
name
"Delivered orders",
results
0
},
{
id
"false",
name
"Not delivered orders",
results
0
}
]
},
{
id
"closed",
name
"Closed",
values
[
{
id
"true",
name
"Closed orders",
results
0
},
{
id
"false",
name
"Not closed orders",
results
0
}
]
},
{
id
"channel",
name
"Channel",
values
[
{
id
"meli",
name
"Meli orders",
results
707
},
{
id
"mshops",
name
"Mshops orders",
results
0
}
]
},
{
id
"buyer_feedback",
name
"Buyer_feedback",
values
[
{
id
"true",
name
"Buyer feedback completed",
results
0
},
{
id
"false",
name
"Buyer feedback not completed",
results
0
}
]
},
{
id
"seller_feedback",
name
"Seller_feedback",
values
[
{
id
"true",
name
"Seller feedback completed",
results
0
},
{
id
"false",
name
"Seller feedback not completed",
results
0
}
]
},
{
id
"feedback",
name
"Feedback (buyer + seller)",
values
[
{
id
"true",
name
"Seller and buyer feedback completed",
results
0
},
{
id
"false",
name
"Seller and buyer feedback not completed",
results
0
}
]
},
{
id
"shipping",
name
"Shipping status",
values
[
{
id
"pending",
name
"Pending",
results
10
},
{
id
"pickup",
name
"Pickup",
results
0
},
{
id
"on_route",
name
"On_route",
results
14
},
{
id
"print_tag",
name
"Print_tag",
results
0
},
{
id
"to_be_agreed",
name
"To be agreed",
results
82
},
{
id
"in_progress",
name
"In progress",
results
82
},
{
id
"delivered",
name
"In progress",
results
579
}
]
},
{
id
"pending_process",
name
"Not processed orders",
values
[ Resumo de vendas pendentes
Tipo
OBJETO
{
id
"pending_process",
name
"Not processed orders",
results
Número de resultados
Tipo
NUMERICO
}
]
},
{
id
"pending_shipment",
name
"Not shipped orders",
values
[ Resumo TRANSPORTE Na pendência de vendas
Tipo
OBJETO
{
id
"pending_shipment",
name
"Not shipped orders",
results
Número de resultados
Tipo
NUMERICO
}
]
},
{
id
"pending_feedback",
name
"Pending feedback orders",
values
[ Resumo de vendas pendentes Grade
Tipo
OBJETO
{
id
"pending_feedback",
name
"Pending feedback orders",
results
Número de resultados
Tipo
NUMERICO
}
]
},
{
id
"closed_orders",
name
"Closed orders",
values
[ Resumo de vendas pendentes Grade
Tipo
OBJETO
{
id
"closed_orders",
name
"Closed orders",
results
Número de resultados
Tipo
NUMERICO
}
]
}
]
}
ERROS :
403: Token Invalido
ATUALIZAR OS DADOS DE FATURAMENTO
PUT  /v1/shops/{SHOP_id}/orders/{ORDER_ID} 

Mostrar exemplo 
https://api.mercadoshops.com/v1/shops/{SHOP_ID}/orders/{ORDER_ID}?access_token={token} 

Parâmetros

ParâmetroValoresExemplo
access_token Código de segurança access_token=APP_USR-4X30-XXXXX-
SHOP_ID Id da loja https://api.mercadoshops.com/v1/shops /159999999/
ID ID da venda v1/shops/159999999/orders/999911111
Invoice
{ DADOS DE FATURAMENTO
Tipo
OBJETO
Invoiced
Se esta marcada
Tipo
BOOLEAN
Valores Possíveis
true
facturado
false
unbilled
number
número do voucher
Tipo
STRING
type
tipo de prova
Tipo
STRING
}
{
invoice
{
invoiced
true,
number
"060300007620",
type
"FC"
}
}
ATUALIZAR OS DADOS DE SHIPPING

Atualize o status de shipping e o código de rastreamento.

PUT  /v1/shops/{SHOP_id}/orders/{ORDER_ID}/shippings/{SHIPPING_ID} 

Mostrar eXemplo 
https://api.mercadoshops.com/v1/shops/{SHOP_ID}/orders/{ORDER_ID}/shippings/{SHIPPING_ID}?access_token={token} 

Parâmetros

ParâmetroValoresExemplo
access_token Código de rastreamento access_token=APP_USR-4X30-XXXXX-
SHOP_ID ID da loja https://api.mercadoshops.com/v1/shops /159999999/
ID ID da venda v1/shops/159999999/orders/999911111
SHIPPING_ID ID do ENVIO  
status
Estado de Entrega
Tipo
STRING
Valores Possíveis
pickup
Levantamentos
pending
Entrega de malha
in_progress
próximo
on_route
No meu caminho
delivered
comprometida
tracking_code
código de acompanhamento
Tipo
STRING
{
status
"pending",
tracking_code
"111111"
}