Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação
Envios Flex
Áreas de cobertura por países
Para oferecer envios flex, o endereço de entrega do vendedor deve estar habilitado para uma das áreas de cobertura segundo o país:
País | Cobertura |
---|---|
Argentina |
- AMBA (Área Metropolitana de Buenos Aires) - Córdoba |
Brasil |
- São Paulo - Rio de Janeiro - Brasília - Belo Horizonte - Porto Alegre - Salvador Bahia - Curitiba |
México |
- CDMX (Zona Metropolitana do Vale do México) - Mérida |
Chile |
- Santiago (Região Metropolitana) - Valparaíso |
Colômbia |
- Bogotá - Medellín - Cali |
Uruguai |
- Montevideo - Canelones |
Peru | - Lima (Área Metropolitana) |
Equador | - Quito |
Configurar um usuário de teste
Para configurar a funcionalidade de Envios Flex para usuários de prova, leve em conta:
1. Faça login na conta onde deseja ativar o Envios Flex
2. Certifique-se de que a conta tenha postagens ativas no ME2.
3. Verifique se sua conta tem reputação Amarela ou Verde.
4. Certifique-se de ter um endereço de e-mail compatível com a área de cobertura do seu país.
5. Defina o endereço de entrega de acordo com as áreas de cobertura dos países correspondentes.
6. Ative o envio flexível para a conta.
Depois de concluir esses passos, você poderá usar o Envios Flex como usuário de teste.
Consultar assinaturas de um usuário
Este endpoint permite consultar as assinaturas que um usuário possui.
- Se o usuário ativou apenas o Flex, ele terá uma única assinatura.
- Caso o usuário também tenha ativado o Turbo, ele terá duas assinaturas, pois para ativar o Turbo o usuário deve primeiro ter o Flex ativo.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/subscriptions/v1
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/subscriptions/v1
Resposta:
[
{
"id": 111181,
"site_id": "MLA",
"user_id": 1438865529,
"mode": "FLEX",
"configuration_type": {
"coverage": "zone",
"delivery": "custom"
},
"service_id": 736230,
"status": {
"id": "in",
},
"creation_date": "2023-08-02T06:34:40Z"
},
{
"id": 111183,
"site_id": "MLA",
"user_id": 1438865529,
"mode": "TURBO",
"configuration_type": {
"coverage": "radius",
"delivery": "accurate"
},
"service_id": 738216,
"status": {
"id": "in",
},
"creation_date": "2023-08-02T06:35:30Z"
}
]
Parâmetros de resposta:
id: ID único da inscrição.
site_id: Identificador do país.
user_id: ID do usuário.
mode: Tipo de inscrição(FLEX neste caso).
configuration_type: Tipo de configuração da inscrição (FLEX neste caso).br/>
configuration_type.coverage: Tipo de cobertura.
configuration_type.delivery: Tipo de entrega.
service_id: ID do serviço associado à sua inscrição.
status: Estado da inscrição.
status.id: Tipos de estados da inscrição:
- in: A assinatura está ativa. Neste estado o usuário poderá alterar suas configurações e receber pedidos de envio para modalidade de assinatura.
- out: A inscrição não está ativa. Neste estado o usuário não pode mudar a configuração.
- pending: A assinatura está com ativação pendente. Neste estado o usuário pode alterar sua configuração embora não receba pedidos para fazer envios.
Códigos de estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Atualizou corretamente a configuração | - |
400 - Bad Request | empty site id | O site_id está vazio | Validar o site_id |
400 - Bad Request | invalid site_id | Site_id inválido | Validar se o site_id está habilitado para Envios Flex |
400 - Bad Request | can't access to resource | Site_id inválido | Validar se o site_id está habilitado para Envios Flex |
404 - Not Found | user not found | Não existe o usuário | Validar o user_id |
Consultar a configuração da inscrição
Este endpoint permite consultar a configuração das inscrição que tem um usuário, para este caso de flex.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/configuration/v3
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/configuration/v3
{
"query": "{ configuration (user_id: 1438865529, service_id: 736230) { address { id address_line city { id name } zip_code } subscription { site_id user_id service_id status { id } creation_date training_times { original { value unit } remaining { value unit } activation_date } } delivery_window is_moderated delivery_ranges { week { capacity type processing_time from to et_hour calculated_cutoff } saturday { capacity type processing_time from to et_hour calculated_cutoff } sunday { capacity type processing_time from to et_hour calculated_cutoff } } working_days zones { enabled id is_mandatory label neighborhoods price { cents currency_id decimal_separator fraction symbol } selected } availables { cutoff capacity_range { from to } ranges } disabled_features } }"
}
Resposta:
{
"configuration": {
"address": {
"address_line": "Testing Street 1450",
"city": {
"id": "TUxBQlNBQTM3Mzda",
"name": "Saavedra"
},
"id": "1316123989",
"zip_code": "1430"
},
"availables": {
"capacity_range": {
"from": 1,
"to": 50
},
"cutoff": [
12,
13,
14,
15,
16,
17,
18
],
"ranges": [
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21
]
},
"delivery_ranges": {
"saturday": null,
"sunday": null,
"week": [
{
"calculated_cutoff": 14,
"capacity": 30,
"et_hour": 14,
"from": 12,
"processing_time": 0,
"to": 21,
"type": "cpt"
}
]
},
"delivery_window": "same_day",
"disabled_features": [
"CUTOFF_BY_ZONE",
"CAPACITY_BY_DAY"
],
"is_moderated": false,
"subscription": {
"creation_date": "2023-08-02T06:34:40Z",
"service_id": 736230,
"site_id": "MLA",
"status": {
"id": "in"
},
"training_times": null,
"user_id": 1438865529
},
"working_days": [
"week"
],
"zones": [
{
"enabled": true,
"id": "Almirante_Brown",
"is_mandatory": false,
"label": "Almirante Brown",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Avellaneda",
"is_mandatory": false,
"label": "Avellaneda",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Berazategui",
"is_mandatory": false,
"label": "Berazategui",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "CABA",
"is_mandatory": false,
"label": "CABA",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1114",
"symbol": "$"
},
"selected": true
},
{
"enabled": true,
"id": "Esteban_Echeverria",
"is_mandatory": false,
"label": "Esteban Echeverría",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Ezeiza",
"is_mandatory": false,
"label": "Ezeiza",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Florencio_Varela",
"is_mandatory": false,
"label": "Florencio Varela",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Hurlingham",
"is_mandatory": false,
"label": "Hurlingham",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Ituzaingo",
"is_mandatory": false,
"label": "Ituzaingó",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Jose_C_Paz",
"is_mandatory": false,
"label": "José C Paz",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Lanus",
"is_mandatory": false,
"label": "Lanús",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Lomas_de_Zamora",
"is_mandatory": false,
"label": "Lomas de Zamora",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Malvinas_Argentinas",
"is_mandatory": false,
"label": "Malvinas Argentinas",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "La_Matanza_1",
"is_mandatory": false,
"label": "La Matanza Norte",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "La_Matanza_2",
"is_mandatory": false,
"label": "La Matanza Sur",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Merlo",
"is_mandatory": false,
"label": "Merlo",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Moreno",
"is_mandatory": false,
"label": "Moreno",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Moron",
"is_mandatory": false,
"label": "Morón",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Quilmes",
"is_mandatory": false,
"label": "Quilmes",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Fernando",
"is_mandatory": false,
"label": "San Fernando",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Isidro",
"is_mandatory": false,
"label": "San Isidro",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Martin",
"is_mandatory": false,
"label": "San Martín",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "San_Miguel",
"is_mandatory": false,
"label": "San Miguel",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Tigre",
"is_mandatory": false,
"label": "Tigre",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "2409",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Tres_De_Febrero",
"is_mandatory": false,
"label": "Tres de Febrero",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
},
{
"enabled": true,
"id": "Vicente_Lopez",
"is_mandatory": false,
"label": "Vicente López",
"neighborhoods": [],
"price": {
"cents": "99",
"currency_id": "ARS",
"decimal_separator": ".",
"fraction": "1769",
"symbol": "$"
},
"selected": false
}
]
}
}
Parâmetros de resposta:
address: Informação sobre a direção do usuário.
availables: Contém informação sobre a capacidade, turnos e intervalos disponíveis para o serviço.
- availables.capacity_range: faixa de valores para capacidade.
- availables.cutoff: Detalhe dos turnos disponíveis.
- availables.ranges: Detalhe dos intervalo disponíveis.
- delivery_ranges.saturday: Intervalo de entrega e capacidade para os sábados.
- delivery_ranges.sunday: Intervalo de entrega e capacidade para os domingos.
- delivery_ranges.week: Intervalos de entrega e capacidade para os dias da semana.
disabled_features: Características desabilitadas para o serviço, incluindo CUTOFF_BY_ZONE e CAPACITY_BY_DAY.
is_moderated: Indica se o serviço está moderado (true/false).
subscription: Informação sobre a inscrição do usuário.
working_days: Dias úteis disponíveis.
zones: informação sobre as zonas disponíveis para o serviço.
- zones.selected: Indica se a zona está selecionada (true/false).
Códigos de Estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Atualizou corretamente a configuração. | - |
400 - Bad Request | empty site id | O site_id está vacío | Validar o site_id |
400 - Bad Request | invalid site_id | Site_id inválido | Validar se o site_id está habilitado para Envios Flex. |
400 - Bad Request | can't access to resource | Site_id inválido | Validar se o site_id está habilitado para Envios Flex. |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecido. |
400 - Bad Request | failed to create schema in graphql operation | GraphQL inválida para o esquema definido. | Validar o esquema de query estabelecido. |
400 - Bad Request | invalid query | GraphQL inválida para o esquema definido. | Validar o esquema de query estabelecido. |
404 - Not Found | subscriptions not found | Não existe assinatura a Envios Flex para a combinação de user_id e service_id enviada. | Validar o user_id e service_id no endpoint. |
404 - Not Found | user not found | Não existe o usuário. | Validar o user_id . |
Configurar Prazo de Entrega e Limite de Envios
Através deste endpoint, é possível configurar diferentes aspectos para Envios Flex como:
- Janela de Entrega
- Intervalo de Horário de Entrega
- Horário de Turnos
- Limite de envios
Chamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/delivery/custom/v3
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/delivery/custom/v3
{
"delivery_window": "same_day",
"delivery_ranges": {
"week": [
{
"from": 12,
"to": 21,
"capacity": 44,
"cutoff": 16
}
],
"saturday": [
{
"from": 12,
"to": 21,
"capacity": 33,
"cutoff": 14
}
],
"sunday": [
{
"from": 12,
"to": 21,
"capacity": 33,
"cutoff": 14
}
]
}
}
Códigos de estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Atualizou corretamente a configuração. | - |
400 - Bad Request | invalid user_id | User_id inválido. | Validar user_id (deve ser um número inteiro). |
400 - Bad Request | invalid service_id | Service_id inválido. | Validar o service_id (deve ser um número inteiro). |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecido. |
404 - Not Found | can't update delivery custom | Não pode realizar a atualização de configuração devido a não existir assinatura a Envios Flex para a combinação de user_id y service_id enviada. | Validar o user_id e service_id no endpoint. |
Ampliar área de cobertura Flex
Este endpoint permite adicionar mais áreas de coberturas para Envios Flex.
chamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configuration/coverage/zone/v3
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipping/flex/sites/MLA/users/1438865529/services/736230/configuration/coverage/zone/v3
{
"zones": [
{
"id": "Almirante_Brown"
},
{
"id": "Avellaneda"
},
{
"id": "CABA"
}
]
}
Códigos de Estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Atualizou corretamente a configuração. | - |
400 - Bad Request | invalid user_id | User_id inválido. | Validar o user_id (deve ser um número inteiro). |
400 - Bad Request | invalid service_id | Service_id inválido. | Validar o service_id (deve ser um número inteiro). |
400 - Bad Request | invalid JSON body | O JSON é inválido. | Validar o esquema de query estabelecido |
404 - Not Found | can't update delivery custom | Não pode realizar a atualização de configuração devido a não existir inscrição a Envios Flex para a combinação de user_id e service_id enviada. | Validar o user_id e service_id no endpoint. |
Consultar Flex no item
Este endpoint te permite consultar se o item está habilitado para Envios Flex ou não.
chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_ID
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403
Resposta:
Status: 204 No Content
Códigos de Estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
204 - No Content | - | Item habilitado para Envios Flex. | - |
403 - Forbidden | item down | Item não oferece Envios Flex. | Validar as modalidades de envio do Item. |
404 - Not Found | item not found | O país está desabilitado para Envios Flex. | Validar os países com Envios Flex. |
Ativar Flex no item
Este endpoint permite ativar a opção de Envíos Flex ao item.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_ID
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403
Resposta:
Status: 204 No Content
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
204 - No Content | - | Item atualizado corretamente para oferecer Envios Flex. | - |
400 - Bad Request | item is already in flex | Item já se encontra com Envios Flex. | - |
403 - Forbidden | item down | O Item não oferece Envios Flex. | Validar as modalidades de envio do ítem. |
404 - Not Found | item not found | Item não encontrado. | Validar os países com Envios Flex. |
Desativar Flex no item
Este endpoint permite desativar a opção de Flex no item.
Chamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE_ID/shipping/selfservice/items/$ITEM_ID
Exemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLB/shipping/selfservice/items/MLB1493119403
Resposta:
Status: 204 No Content
Códigos de Estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
204 - No Content | - | Item atualizado corretamente para deixar de oferecer Envios Flex. | - |
400 - Bad Request | item is already in flex | Item já não conta com Envios Flex. | - |
403 - Forbidden | item down | Item não oferece Envios Flex. | Validar as modalidades de envio do item. |
404 - Not Found | item not found | Item não encontrado. | Validar os países com Envios Flex. |
Identificar o código do transportadora
Este endpoint facilita a identificação da transportadora destinada a um envio, o que é útil para registrar mudanças de transportadora durante o processo de entrega.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/flex/sites/$SITE_ID/shipments/$SHIPMENT_ID/assignment/v1
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/flex/sites/MLA/shipments/40070866801/assignment/v1
Resposta:
{
"driver_id": 1234
}
Códigos de Estado de resposta:
Código | Mensagem | Descrição | Recomendação |
---|---|---|---|
200 - OK | - | Transportadora designada. | - |
404 - Not Found | shipment_id not found | Não possui transportadora designada ou não se encontra a rota aberta (envio pendente a ser entregue). Não existe (shipment inexistente). |
Validar o estado do envio ou shipment_id. |