Envios Flex

Envios Flex é um serviço que permite aos vendedores realizar envios por conta própria, 7 dias por semana. Integra envios no mesmo dia ou no dia seguinte para melhorar os prazos de entrega e aumentar a penetração no mercado. Com Envios Flex, os vendedores podem ter maior controle e acompanhamento sobre seus envios, oferecendo um serviço mais rápido e eficiente aos seus clientes.

Saiba mais sobre:

• Como funciona Envios Flex
• Tarifas dos Envios Flex
• Dicas para gerenciar adequadamente meus Envios Flex
• Como posso gerenciar meus endereços para Envios Flex
• Como oferecer Envios Flex e Full na mesma publicação
• Dicas para fazer entregas com Envios Flex
• Como evito a suspensão de zonas para meus Envios Flex

Visualização do vendedor:

Áreas de cobertura por países

Para poder oferecer Envios Flex, o endereço de envio do vendedor deve estar habilitado para alguma das áreas de cobertura de acordo com 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	Montevidéu Canelones
Peru	Lima (Área Metropolitana)
Equador	Quito

Configurar um usuário de teste

Para configurar a funcionalidade de Envios Flex para usuários de teste, levar em conta:

1. Faça login na conta em que deseja habilitar Envios Flex.
2. Certifique-se de que a conta tenha publicações ativas em ME2.
3. Verifique se sua conta tem reputação Amarela ou Verde.
4. Certifique-se de ter um endereço compatível com a área de cobertura do seu país.
5. Configure o endereço de envio de acordo com as áreas de cobertura nos países correspondentes.
6. Ative Envios Flex na conta.

Depois de concluir estas etapas, você deverá conseguir utilizar Envios Flex como usuário de teste.

Consultar assinaturas de um usuário

Este endpoint permite consultar as assinaturas de um usuário, que pode ter múltiplas assinaturas configuráveis correspondentes a diferentes origens, mesmo que todas pertençam ao mesmo modo.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar

Chamada:

curl -X GET https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/subscriptions/v1 \
-H 'Authorization: Bearer $ACCESS_TOKEN'

[
    {
        "site_id": "MLA",
        "user_id": 1438865529,
        "service_id": 738216,
        "mode": "FLEX",
        "origin": {
            "address_line": "Testing Address 3000",
            "city": {
                 "id": "TUxBQlNBQTM3Mzda",
                 "name": "Saavedra"
            },
            "id": "1369500000",
            "zip_code": "1234"
        },
        "status": "in", 
        "configuration": {
            "set": {
                    "coverage": {
                           "type":"zone", 
                           "capabilities": {
                                "cutoff_by_zone": false
                            }
                    },
                    "delivery_ranges": "dinamic"/"disabled",
                    "holidays": true ,
                    "transit_times": false
            },
            "available": {
                    "coverage": {
                            "type": ["zone"], 
                            "capabilities": {
                                "cutoff_by_zone": true
                            }
                    }
            }
        }
    }
]

Parâmetros de resposta:

• Detalhes da Assinatura:
  • site_id: Identificador do site (ex.: "MLA").
  • user_id: Identificador do usuário proprietário da assinatura.
  • service_id: Identificador do serviço ao qual a assinatura está associada.
  • mode: Modalidade da assinatura, que pode ser "FLEX" ou "TURBO".
  • status: Estado atual da assinatura (exs.: "creating", "pending", "activating", "in", "out").
• Origem da Assinatura (origin):
  • Informações detalhadas do endereço de origem.
  • address_line: Endereço completo da origem.
  • id: Identificador do endereço de origem.
  • zip_code: CEP do endereço.
  • city:
    • id: Identificador da cidade.
    • name: Nome da cidade.
• Configuração da Assinatura (configuration):
  • Detalhes da configuração definida e das opções disponíveis.
  • Configuração Ativa (set):
    • coverage: Configuração da cobertura atual.
    • type: Tipo de cobertura ativa. Possíveis valores:
      • "zone" — cobertura por zonas geográficas (Flex). Os endpoints de /configurations/coverage/zones/ aplicam a este tipo.
      • "radius" — cobertura por raio en km (Turbo). Os endpoints de /configurations/coverage/radius/ aplicam a este tipo. Ver Envíos Turbo.
    • capabilities: Capacidades da cobertura.
    • cutoff_by_zone: Indica se a cobertura atual tem horário de corte por zona.
    • delivery_ranges: Tipo de faixas de entrega configuradas: "dinamic", "fixed" ou "disabled".
    • holidays: Indica se a funcionalidade de feriados está habilitada.
    • transit_times: Indica se os tempos de trânsito estão habilitados.
  • Configuração Disponível (available):
    • coverage: Opções de cobertura que o usuário pode configurar.
    • type: Tipos de cobertura disponíveis (ex.: "zone").
    • capabilities: Capacidades de cobertura configuráveis.
    • cutoff_by_zone: Indica se o horário de corte por zonas é uma opção configurável.

Códigos de status de resposta:

• 200 OK: Consulta bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Consultar zonas de cobertura

Este endpoint permite obter informações detalhadas sobre as zonas de cobertura de entrega.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar
Query Params	show_availables ⇒ bool, para mostrar ou não os disponíveis

Chamada:

  curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/coverage/zones/v1?show_availables=boolean

Resposta:

  
{
    "zones": [
        {
            "id": "CABA",
            "cutoff": {
                "week": 12,
                "saturday": 12,
                "sunday": 12
            }
        }
    ],
    "availables": {
        "zones": [
            {
                "id": "CABA",
                "label": "CABA",
                "neighborhoods": [],
                "polygon": {
                    "geometry": {
                        "coordinates": [
                            [
                                [
                                    -57.754044,
                                    -34.907747
                                ],
                                [
                                    -57.785072,
                                    -34.888363
                                ]
                            ]
                        ],
                        "type": "Polygon"
                    },
                    "properties": {
                        "name": null
                    },
                    "type": "Feature"
                },
                "price": {
                    "cents": "99",
                    "currency_id": "ARS",
                    "decimal_separator": ".",
                    "fraction": "8506",
                    "symbol": "$"
                },
                "scope": "LocalLejano"
            }
        ],
        "cutoffs": {
            "global": {
                "min": 12,
                "max": 18
            },
            "per_scope": {
                "LocalInterno": {
                    "minimum": 12,
                    "maximum": 18
                },
                "LocalAdyacente": {
                    "minimum": 12,
                    "maximum": 18
                },
                "LocalLejano": {
                    "minimum": 10,
                    "maximum": 15
                }
            }
        }
    }
}

Considerações

No caso de não possuir uma configuração específica de horário de corte por zona, o objeto cutoff será omitido no response.

Parâmetros de resposta:

• zones
  • id: Identificador da zona (por exemplo, "CABA").
  • cutoff (week/saturday/sunday): Horário de corte configurado para cada dia.
• availables (Este objeto é incluído somente se o parâmetro show_availables=true estiver presente na consulta)
  • zones: Lista com as configurações das zonas disponíveis.
  • id: ID da zona.
  • label: Nome descritivo da zona.
  • neighborhoods: Lista de bairros dentro da zona.
  • polygon: Definição geográfica da zona.
  • geometry: Dados da geometria da zona.
    • coordinates: Coordenadas geográficas.
    • type: Tipo de geometria.
  • price: Informação do preço da zona.
    • cents: Valor em centavos.
    • currency_id: ID da moeda.
    • decimal_separator: Separador decimal.
    • fraction: Fração da moeda.
    • symbol: Símbolo da moeda.
    • scope: Alcance da zona.
• cutoffs
  • global: Informação global das horas de corte disponíveis.
    • min: Hora mínima global de corte.
    • max: Hora máxima global de corte.
  • per_scope: Horas de corte por tipo de alcance. Contém um objeto para cada alcance possível (LocalInterno, LocalAdyacente, LocalLejano).

Códigos de resposta

• 204 No Content: Atualização bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 501 Not implemented:: A configuração ainda não foi implementada.
• 500 Internal Server Error: Erro ao obter a configuração.

Atualizar zonas de cobertura

Este endpoint permite modificar as informações relacionadas às zonas de cobertura de entrega, como por exemplo adicionar ou eliminar zonas, além de ativar ou desativar horário de corte para dias da semana, sábados e domingos.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar

Chamada:

  curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/coverage/zones/v1

Exemplo do request body:

  
{
    "zones": [
        {
            "id": "CABA",
            "cutoff": {
                "week": 12,
                "saturday": 12,
                "sunday": 12
            }
        }
    ]
}

Considerações

• Para atualizar, adicionar ou eliminar zonas sem horário de corte por zona, envie as zonas sem o objeto cutoff.
• Para ativar horário de corte por zona, envie o objeto cutoff nas zonas, com valores diferentes para cada zona.
• Para desativar o horário de corte por zona, envie o objeto cutoff nas zonas, mas com os mesmos valores para cada zona.
• Para atualizar, adicionar ou eliminar zonas com horário de corte por zona, envie as zonas com os valores de cutoff correspondentes.

Códigos de resposta

• 204 No Content: Atualização bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Consultar feriados

Este endpoint permite obter informações detalhadas sobre cada holiday do site onde o serviço está configurado.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/holidays/v1

Resposta:

{
  "holidays": [
    {
      "date": "2021-12-25",
      "description": "Christmas",
      "selected": true
    }
  ]
}

Parâmetros de resposta:

• holidays: lista de feriados configurados.
  • date: data do feriado (formato YYYY-MM-DD).
  • description: descrição do feriado.
  • selected: indica se o user decide realizar envios durante esse feriado.

Códigos de status de resposta:

• 200 OK: Consulta bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Atualizar feriados

Este endpoint permite atualizar a configuração de feriados para um usuário. Por meio dele, é possível marcar um feriado como dia útil ou não útil para realizar entregas.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/holidays/v1

Exemplo:

{
  "holidays": [
    {
      "date": "2021-12-25",
      "description": "Christmas",
      "selected": false
    }
  ]
}

Considerações

• Um usuário só poderá estabelecer um dia como holiday (não útil) enviando no JSON do request body "selected": true, desde que esse dia esteja previamente configurado como dia de trabalho ativo para o seller.
• Por exemplo, se o seller não tem configurado o sábado como dia laboral e solicitar estabelecer um holiday no sábado, o endpoint retornará um erro.

Códigos de status de resposta:

• 204 No Content: Atualização bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Consultar faixas de entrega

Este endpoint permite recuperar informações sobre as faixas de entrega de um usuário.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar
Query Params	show_availables ⇒ bool, para mostrar ou não os disponíveis

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/delivery-ranges/v1?show_availables=$boolean 

Resposta:

{
    "delivery_window": "same_day",
    "delivery_ranges": {
        "week": [
            {
                "capacity": 500,
                "from": 12,
                "to": 12,
                "cutoff": 14
            }
        ],
        "saturday": [
            {
                "capacity": 500,
                "from": 12,
                "to": 12,
                "cutoff": 14
            }
        ],
        "sunday": [
            {
                "capacity": 500,
                "from": 12,
                "to": 12,
                "cutoff": 14
            }
        ]
    },
    "is_downgraded": false,
    "availables": {
        "capacity": {
            "min": 100,
            "max": 500
        },
            "delivery_ranges": {
                "type": "dynamic",
                "ranges": {
                    "1": [
                        {
                            "from": 9,
                            "to": 21
                        }
                    ]
                },
                "min_hours": 9,
                "max_hours": 21,
                "min_range_quantity": 1,
                "max_range_quantity": 1,
                "min_hours_quantity_between_ranges": 1
            },
        "delivery_windows": [
            "same_day",
            "next_day"
        ],
        "working_days": [
            "week",
            "saturday",
            "sunday"
        ],
        "cutoffs": {
            "global": {
                "min": 12,
                "max": 18
            }
        }
    }
}

Parâmetros de resposta:

• delivery_window: janela de entrega configurada atualmente (same_day e next_day).
• delivery_ranges week / saturday / sunday: faixas de entrega configuradas conforme o dia:
  • capacity: capacidade máxima de envios em cada faixa.
  • from: hora de início da faixa de entrega.
  • to: hora de fim da faixa de entrega.
  • cutoff: hora limite para ingressar pedidos nessa faixa. (Este campo não será visível se existir horário de corte.)
  • is_downgraded: indica se o serviço está moderado.
• availables (Este objeto é incluído somente se o parâmetro show_availables=true estiver presente na consulta)
  • capacity_min: capacidade mínima disponível para configurar (segundo o flavour).
  • capacity_max: capacidade máxima disponível para configurar (segundo o flavour).
  • delivery_ranges_type: tipo de faixa de entrega disponível.
  • delivery_ranges_ranges_from: hora de início das entregas.
  • delivery_ranges_ranges_to: hora de fim das entregas.
  • delivery_ranges_min_range_quantity: quantidade mínima de faixas de entrega por dia.
  • delivery_ranges_max_range_quantity: quantidade máxima de faixas de entrega por dia.
  • delivery_ranges_min_hours_quantity_between_ranges: quantidade mínima de horas entre duas faixas.
  • delivery_windows: janelas de entrega disponíveis (same_day e next_day).
  • working_days: dias úteis disponíveis para operar (week, saturday, sunday).
  • cutoffs_global_min: hora mínima global de cutoff disponível.
  • cutoffs_global_max: hora máxima global de cutoff disponível.

Códigos de status de resposta:

• 200 OK: Consulta bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não tem credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Atualizar faixas de entrega

Este endpoint permite atualizar a configuração de faixas de entrega para um vendedor.

Params
Params	site_id ⇒ id do site user_id ⇒ id do user a consultar service_id ⇒ id do service a consultar

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' \
https://api.mercadolibre.com/flex/sites/$SITE_ID/users/$USER_ID/services/$SERVICE_ID/configurations/delivery-ranges/v1

Exemplo:

{
    "delivery_window": "same_day",
    "delivery_ranges": {
        "week": [
            {
                "capacity": 30,
                "from": 11,
                "to": 20,
                "cutoff": 14
            }
        ],
        "saturday": [
            {
                "capacity": 30,
                "from": 11,
                "to": 20,
                "cutoff": 14
            }
        ],
        "sunday": [
            {
                "capacity": 30,
                "from": 11,
                "to": 20,
                "cutoff": 14
            }
        ]
    }
}

Considerações

• Presença de horário de corte por zona: Se o endpoint tiver um horário de corte por zona definido, não se deve incluir o parâmetro cutoff na solicitação. Se tentar enviar este parâmetro nesse caso, será gerada uma resposta com o código de erro 400 (Bad Request).
• Ausência de horário de corte por zona: Se não houver horário de corte por zona definido, é opcional enviar o parâmetro cutoff. Isso significa que você pode decidir incluí-lo ou não na solicitação, dependendo da lógica de negócio que desejar implementar.
• Atualizar Delivery Window: Caso deseje atualizar o delivery_window, segue-se a mesma lógica dos pontos anteriores.
  • Delivery Window:
    • No caso de ter delivery_window configurado como "next_day", o envio do cutoff é indiferente, pois será ignorado já que a oferta será criada para o dia seguinte.
    • No caso de ter delivery_window configurado como "same_day", o envio do cutoff é indispensável.
  • Horário de corte por zona:
    • Se o horário de corte estiver ativado, não se deve enviar o parâmetro cutoff e a nova delivery window será atualizada corretamente.
    • Se o horário de corte não estiver ativado, deve-se incluir o parâmetro cutoff na solicitação.

Códigos de status da resposta:

• 204 No Content: Atualização bem-sucedida.
• 400 Bad Request: Algum parâmetro é inválido.
• 401 Unauthorized: Você não possui credenciais válidas.
• 403 Forbidden: Você não tem permissões suficientes para acessar este recurso.
• 404 Not Found: A configuração não foi encontrada.
• 500 Internal Server Error: Erro ao obter a configuração.

Consultar se a categoria permite Flex

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLB438794/shipping_preferences

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLB438794/shipping_preferences

Resposta:

{
  ...
  "logistics": [
    ...
    {
      "types": [
        "drop_off",
        "xd_drop_off",
        "self_service",
        "cross_docking",
        "fulfillment"
      ],
      "mode": "me2"
    }
  ],
  ...
  "category_id": "MLB438794"
}

Nota: Para saber se a categoria permite Flex, a opção self_service deve estar presente dentro do array logistics.

Consultar Flex no item

Este endpoint permite consultar se o item atualmente está sendo oferecido com Envíos Flex ou não.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/items/$ITEM_ID/v2

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/MLB/items/MLB1493119403/v2

Resposta:

{"has_flex": true/false}

Códigos de status da resposta:

Código	Mensagem	Descrição	Recomendação
200 - OK	-	Item existe e devolve a informação.	-
400 - Bad Request	Algum dado recebido é inválido	-	-
401 - Unauthorized	Autorização inválida	-	Revisar permissões de scope
403 - Forbidden	Autenticação inválida	Access_token incorreto	Revisar o access_token utilizado
404 - Not Found	O item não existe ou não foi encontrado	-	-.
500 - Internal Server Error	Erro interno inesperado/não controlado	-	-

Ativar Flex no item

Este endpoint permite ativar a opção de Envíos Flex no item.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/items/$ITEM_ID/v2

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/MLB/items/MLB1493119403/v2

Resposta:

Status: 204 No Content

Códigos de status da resposta:

Código	Mensagem	Descrição	Recomendação
204 - No Content	-	Item habilitado para Envíos Flex.	-
400 - Bad request	item is already in flex	Item já tem Flex ativado	Validar que o item tem Flex antes da solicitação
403 - Forbidden	item down	Item não oferece Envíos Flex.	Validar as modalidades de envio do item.
404 - Not Found	item not found	O país está desabilitado para Envíos Flex.	Validar os países com Envíos Flex.
409 - Conflict	can't activate item	Conflito interno ao tentar modificar o status do item	Evitar enviar múltiplas solicitações de atualização para o mesmo item ao mesmo tempo.

Desativar Flex no item

Este endpoint permite desativar a opção de Envíos Flex no item.

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/$SITE_ID/items/$ITEM_ID/v2

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/MLB/items/MLB1493119403/v2

Resposta:

Status: 204 No Content

Códigos de status da resposta:

Código	Mensagem	Descrição	Recomendação
204 - No Content	-	Item desativado para Envíos Flex.	-
403 - Forbidden	item down	Item não oferece Envíos Flex.	Validar as modalidades de envio do item.
404 - Not Found	item not found	O país está desabilitado para Envíos Flex.	Validar os países com Envíos Flex.
409 - Conflict	can't activate item	Conflito interno ao tentar modificar o status do item	Evitar enviar múltiplas solicitações de atualização para o mesmo item ao mesmo tempo.

Registrar envios para transportadoras

Este endpoint permite que as mensagerias enviem os shipments que gerenciam, para que sejam processados e posicionados conforme sua performance, obtendo assim maior visibilidade para serem selecionados por um seller.

Chamada

Endpoint

POST https://api.mercadolibre.com/flex/sites/{SITE_ID}/users/{COURIER_USER_ID}/courier-shipment/v1

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
SITE_ID	string	Sim	Identificador do site. Exemplo: MLA para Argentina.
COURIER_USER_ID	string	Sim	User ID da conta de negócio da mensageria registrada no Mercado Libre.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de acesso no formato Bearer {ACCESS_TOKEN}.

Body (JSON)

{
  "shipment_id": {SHIPMENT_ID}
}

Campo	Tipo	Obrigatório	Descrição
SHIPMENT_ID	number	Sim	ID do envio que a mensageria está gerenciando.

Exemplo

curl -X POST \
-H 'Authorization: Bearer APP_USR-1234567890-...' \
https://api.mercadolibre.com/flex/sites/MLA/users/1444885522/courier-shipment/v1 \
-d '{"shipment_id": 123456786}'

Resposta bem-sucedida:

204 - No Content

Como funciona a integração?

O fluxo de integração envolve três atores principais: a Mensageria, o Desenvolvedor e o Aplicativo Integrador. A mensageria se registra por meio de um formulário, vincula sua conta via OAuth 2.0, e o desenvolvedor cria o app integrador que envia os shipments à API do MercadoLibre usando o access token da mensageria.

Considerações

O envio deve ser informado no momento em que a mensageria começa a gerenciá-lo. As requisições com envios já finalizados serão rejeitadas.

Os seguintes estados são considerados finalizados e não serão aceitos:

• delivered
• cancelled
• not_delivered
• shipped & delivery_blocked
• shipped & waiting_for_confirmation

Códigos de resposta

Código	Mensagem	Descrição	Recomendação
204 - No Content	-	Registro bem-sucedido.	-
400 - Bad Request	Parâmetro inválido	-	-
401 - Unauthorized	Autorização inválida	-	Revisar permissões de scope.
403 - Forbidden	Autenticação inválida	access_token incorreto.	Revise o access_token utilizado.
404 - Not Found	Shipment não encontrado	-	-
409 - Conflict	conflito de envío de courier	Envío já atribuído a uma transportadora	Verificar se o shipment já foi processado antes de tentar novamente
500 - Internal Server Error	Erro interno inesperado/não controlado	-	-

Identificar o código do transportista

Este endpoint facilita a identificação do transportista atribuído a um envio, o que é útil para registrar mudanças de transportista 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/v2

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/flex/sites/MLA/shipments/40070866801/assignment/v2

Resposta:

{
    "driver_id": 1234
}

Códigos de status da resposta:

Código	Mensagem	Descrição	Recomendação
200 - OK	-	Transportista atribuído.	-
400 - Bad Request	Parâmetro inválido	-	-
401 - Unauthorized	Autorização inválida	-	Revisar permissões de scope
403 - Forbidden	Autenticação inválida	Access_token incorreto	Revisar o access_token utilizado
404 - Not Found	shipment_id not found	Não possui transportista atribuído ou a rota não está aberta (envio pendente de entrega). Não existe (shipment inexistente).	Validar o status do envio ou shipment_id.
500 - Internal Server Error	Erro interno inesperado/não controlado	-	-

Estados e subestados Flex

Este endpoint permite conhecer os estados e subestados do fluxo de Envíos Flex.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/$SHIPMENT_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/shipments/43319685225

Resposta:

{
    ...
      "comments": null,
      "substatus": "receiver_absent",
      "date_created": "2024-04-23T10:48:51.245-04:00",
      "date_first_printed": "2024-04-23T13:14:16.093-04:00",
    ...
     "status": "shipped",
        }

Parâmetros de resposta:

• status: O estado geral do pacote. Os valores possíveis são:
  • delivered: pacotes entregues.
  • ready_to_ship: pacotes prontos para despachar.
  • cancelled: pacotes cancelados.
  • not_delivered: pacotes rejeitados ou que não será possível entregar. Dentro deste status temos os seguintes substatus possíveis:
    • Rejeitado pelo comprador.
      • refused_delivery: O comprador rejeitou a entrega.
  • shipped: pacotes que estão a caminho do comprador.
    • Saída para rota: O pedido está a caminho.
      • out_for_delivery: O pacote está a caminho para ser entregue.
      • soon_deliver: O motorista notificou o comprador que seu pacote é o próximo na rota de entrega.
    • Endereço incorreto ou incompleto.
      • bad_address: O motorista registrou que o endereço fornecido está incorreto.
    • Não há ninguém no endereço.
      • receiver_absent: O motorista marcou que o comprador estava ausente no momento da entrega.
    • O comprador decide reagendar a compra pelo aplicativo.
      • buyer_rescheduled: O comprador solicitou reagendar a entrega.
    • O motorista marcou como entregue longe do endereço do comprador.
      • delivery_blocked: O motorista indicou que o pacote foi entregue, porém longe do endereço do comprador. Solicita-se ao comprador que confirme se recebeu o envio.
    • O vendedor marca o envio como entregue pelo seu aplicativo.
      • waiting_for_confirmation: O pacote foi marcado como entregue pelo vendedor após a data prometida. Solicita-se ao comprador que confirme se recebeu o envio.

Convivência Full e Flex

Para gerenciar estoque do Flex quando o vendedor tem Fulfillment ativo na sua publicação, disponibilizamos a funcionalidade de estoque distribuído.

Consulte a documentação para entender o funcionamento: Convivência Full e Flex

Itens não enviáveis por ME2 (Itens em ME1, custom ou not_specified)

Produtos em categorias que não são enviados por Mercado Envios (ME2) em outras modalidades logísticas (drop_off, crossdocking, fulfillment) por suas particularidades, agora podem ser enviados por Envíos Flex especificamente.

São considerados não enviáveis os produtos que possuem a seguinte característica:

• Inflamável: Produtos com risco de inflamação.
• Pack 4 Pneus: Pacotes que contêm quatro pneus.
• Não Maquinável: Itens que não podem ser processados por máquinas.
• Hazmat: Materiais perigosos.

Para ativar o Flex no produto do vendedor, valide que a categoria agora permite a opção self_service (Flex), como já é realizado para os demais envios.

Categoria exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/categories/MLA45502/shipping_preferences

Resposta:

{
...
"logistics": [
    ...
    {
        "types": [
            "self_service"
        ],
        "mode": "me2"
    }
],
...
"category_id": "MLA45502"
}

Depois disso, para ativar o Flex não é necessário modificar o shipping.mode do item, mas apenas executar o opt-in do Flex conforme a instrução de Ativar Flex.

Vista do vendedor:

Próximo: Envios Turbo