Recursos para IA
Criar pagamento com envio
Através da preferência, é possível criar um pagamento com um envio associado. Dessa forma, você poderá oferecer aos clientes entregas em domicílio dos produtos adquiridos, aproveitando a logística do Mercado Livre sem esforços extras por parte do seu negócio.
A criação de envios está disponível apenas para integradores autorizados pelo Mercado Pago. Caso ainda não tenha essa funcionalidade habilitada, revise a disponibilidade em sua conta Mercado Pago.
Para criar um pagamento com um envio associado, crie uma preferência enviando uma solicitação ao endpoint /checkout/preferencesPOST, incluindo seu Access TokenChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os nós items e shipments, conforme indicado na tabela abaixo.
curlcurl --location 'https://api.mercadopago.com/checkout/preferences' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --header 'Content-Type: application/json' \ --data '{ "external_reference": "Referencia externa 123", "items": [ { "title": "Producto 1", "description": "Descripción del producto 1", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "title": "Producto 2", "description": "Descripción del producto 2", "picture_url": "image.jpg", "quantity": 1, "currency_id": "MXN", "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "shipments": { "dimensions": "21x15x6.5,360", "free_methods_types": [ { "id": "standard" } ], "local_pickup": false, "mode": "me2", "stock_origin_id": "id", "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "neighborhood": Colonia, "city_name": Cuauhtémoc, "state_name": Ciudad de México, "country_name": México } } }'
| Campo | Descrição | Tipo | Obrigatoriedade |
external_reference | Referência que você pode sincronizar com seu sistema de pagamentos para identificar o envio. Este campo deve ter no máximo 64 caracteres e conter apenas números, letras, hífens (-) e sublinhados (_). Caracteres especiais como ([ ], (), '', @) não são permitidos. | String | Opcional |
items | Informações sobre os itens vendidos que serão enviados. | Array | Obrigatório |
items.title | Título do item que será exibido durante o processo de pagamento, no checkout, atividades e e-mails. | String | Obrigatório |
items.description | Descrição do item. | String | Opcional |
items.picture_url | URL da imagem do item. | String | Opcional |
items.quantity | Quantidade de itens. Esta propriedade é utilizada para calcular o custo total da compra. | Number | Obrigatório |
items.currency_id | Identificador único da moeda envolvida na transação. O único valor possível é o peso mexicano (MXN). | String | Opcional |
items.unit_price | Preço unitário do item. Esta propriedade é usada junto com a propriedade quantity para determinar o custo da compra. | Number | Obrigatório |
items.fiscal_data | Objeto que contém os dados fiscais do produto. | Object | Obrigatório para criar envios. Se você enviá-lo, deve incluir também o atributo shipments. |
items.fiscal_data.sat | Categoria SAT do item. Consulte os valores possíveis acessando o seguinte link. | String | Obrigatório |
items.fiscal_data.sat_measurement_id | Identificador único da unidade de medida do produto. | String | Obrigatório |
items.fiscal_data.measurement_unit | Unidade de medida do produto de acordo com as SAT Units | String | Obrigatório |
items.fiscal_data.package_id | Identificador do tipo de embalagem do produto. | String | Obrigatório |
items.fiscal_data.dangerous_material_id | Identificador para produtos perigosos. | String | Opcional |
items.dimensions | Objeto que contém as informações sobre o tamanho do item. | Object | Opcional |
items.dimensions.unit | Unidade de medida para o item. Deve ser cm (centímetros). | String | Obrigatório |
items.dimensions.height | Altura do item em centímetros. | Number | Obrigatório |
items.dimensions.width | Largura do item em centímetros. | Number | Obrigatório |
items.dimensions.length | Comprimento do item em centímetros. | Number | Obrigatório |
items.dimensions.weight | Peso do item em gramas. | Number | Obrigatório |
shipments | Informações do envio. | Object | Obrigatório |
shipments.dimensions | Tamanho do pacote, que será utilizado para definir o custo do envio. O formato deve ser cm x cm x cm, g. Se houver mais de um item, seu tamanho deve ser calculado considerando a soma das dimensões de todos os artigos, garantindo sempre que as dimensões máximas permitidas por pacote não sejam excedidas.Consulte as boas práticas para dimensionamento acessando a documentação. | String | Obrigatório |
shipments.free_methods_type | Identificador do método de envio. Deve ser enviado apenas ao oferecer envio gratuito, com o valor standard. O envio gratuito só é possível quando o valor da venda é maior que o custo do envio. Caso o custo do envio esteja a cargo do comprador, o campo não deve ser enviado. | String | Opcional |
shipments.local_pickup | Indica se deseja oferecer coleta de pacotes em uma agencia. Para esta solução, insira false. | Boolean | Obrigatório |
shipments.mode | Modo de envio. Para esta solução, insira me2. | String | Obrigatório |
shipments.stock_origin_id | Identificador do endereço de origem do pacote, que deve ser solicitado à equipe do Mercado Pago. Caso haja mais de um endereço de coleta, o stock_origin_id deve ser informado para o endereço de origem. | String | Opcional |
shipments.receiver_address | Detalhes do endereço de destino. Seu envio é recomendado para oferecer a melhor experiência de compra e, se necessário, os dados podem ser reutilizados. | Object | Opcional |
shipments.receiver_address.zip_code | Código postal do endereço de destino. | String | Opcional |
shipments.receiver_address.street_name | Nome da rua de destino. | String | Opcional |
shipments.receiver_address.street_number | Número do endereço de destino. | String | Opcional |
shipments.receiver_address.floor | Andar do apartamento de destino. | String | Opcional |
shipments.receiver_address.apartment | Número do apartamento de destino. | String | Opcional |
shipments.receiver_address.neighborhood | Bairro do endereço de destino. | String | Opcional |
shipments.receiver_address.city_name | Cidade do endereço de destino. | String | Opcional |
shipments.receiver_address.state_name | Estado do endereço de destino. | String | Opcional |
shipments.receiver_address.country_name | País do endereço de destino. | String | Opcional |
Se a requisição for enviada com sucesso, o pagamento com envio terá sido criado e a resposta será exibida como no exemplo a seguir.
json{ "additional_info": "", "auto_return": "", "back_urls": { "failure": "", "pending": "", "success": "" }, "binary_mode": false, "client_id": "6607075136335166", "collector_id": 2681149695, "coupon_code": null, "coupon_labels": null, "date_created": "2025-10-15T15:30:39.775-04:00", "date_of_expiration": null, "expiration_date_from": null, "expiration_date_to": null, "expires": false, "external_reference": "Referencia externa 123", "id": "2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "init_point": "https://www.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "internal_metadata": null, "items": [ { "id": "", "category_id": "", "currency_id": "MXN", "description": "Descripción del producto 1", "title": "Producto 1", "quantity": 1, "unit_price": 100, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 11, "length": 18, "weight": 100 } }, { "id": "", "category_id": "", "currency_id": "MXN", "description": "Descripción del producto 2", "title": "Producto 2", "quantity": 1, "unit_price": 110, "fiscal_data": { "sat": "23241500", "sat_measurement_id": "H87", "measurement_unit": "Pieza", "package_id": "4G", "dangerous_material_id": "M2340" }, "dimensions": { "unit": "G", "height": 3, "width": 10, "length": 18, "weight": 90 } }, ], "marketplace": "NONE", "marketplace_fee": 0, "metadata": {}, "notification_url": null, "operation_type": "regular_payment", "payer": { "phone": { "area_code": "", "number": "" }, "address": { "zip_code": "", "street_name": "", "street_number": null }, "email": "", "identification": { "number": "", "type": "" }, "name": "", "surname": "", "date_created": null, "last_purchase": null }, "payment_methods": { "default_card_id": null, "default_payment_method_id": null, "excluded_payment_methods": [ { "id": "" } ], "excluded_payment_types": [ { "id": "" } ], "installments": null, "default_installments": null }, "processing_modes": null, "product_id": null, "preference_expired": false, "redirect_urls": { "failure": "", "pending": "", "success": "" }, "sandbox_init_point": "https://sandbox.mercadopago.com.mx/checkout/v1/redirect?pref_id=2681149695-c464c4e0-1834-4e81-9956-25a3cc1e8db8", "site_id": "MLM", "shipments": { "mode": "me2", "local_pickup": false, "dimensions": "21x15x6.5,360", "free_methods": [], "free_methods_types": [ { "id": "standard" } ], "default_shipping_method": null, "receiver_address": { "zip_code": "06250", "street_name": "Ex-Hipódromo de Peralvillo", "street_number": null, "floor": "", "apartment": "", "city_name": "Cuauhtémoc", "state_name": "Ciudad", "country_name": "México", "neighborhood": "Colonia" }, "stock_origin_id": "id" }, "total_amount": null, "last_updated": null, "financing_group": "" }
O campo
sandbox_init_point aparece na resposta, mas não é funcional. Para testes de integração, utilize init_point.Em caso de necessidade, é possível cancelar o envio criado. Para isso, cancele integralmente o pagamento ao qual ele está associado por meio do endpoint /v1/payments/{id}PUT.
Se você optar por criar pagamentos com envio, poderá usar nossas APIs de gerenciamento de envios, que permitirão otimizar sua experiência pré e pós-venda.
Nossa API de Cotações permite estimar o valor de um envio com base no volume do pacote e no código postal dos endereços de despacho e destino.
Para cotar um envio, envie uma solicitação ao endpoint /shipping/v1/shipments-ratesPOST incluindo seu Access TokenChave privada da aplicação criada no Mercado Pago e que é utilizada no backend. Você pode acessá-la através de Suas integrações > Dados da integração > Testes > Credenciais de teste. O Access Token de teste começa com o prefixo `APP_USR`. e os parâmetros descritos na tabela abaixo. Tenha em conta que só é possível cotar o envio de um pacote por vez.
curlcurl --location 'https://api.mercadopago.com/shipping/v1/shipments-rates' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ --data '{ "packages": [ { "declared_value": 1500, "quantity": 1, "dimensions": { "weight": 500, "width": 30, "height": 30, "length": 30 } } ], "shipping_from": { "zip_code": "06760" }, "shipping_to": { "zip_code": "06720" } }'
| Campo | Descrição | Tipo | Obrigatoriedade |
packages | Contém as informações do pacote para a cotação. | Array | Obrigatório |
packages.declared_value | Valor do pacote a ser enviado. Não inclui o custo estimado de envio. | Number | Obrigatório |
packages.quantity | Quantidade de pacotes. O único valor permitido é 1. | Number | Obrigatório |
packages.dimensions | Objeto que contém as dimensões do pacote. Os máximos permitidos são: - Cada lado deve ter no máximo 150 cm. - O limite de dimensões totais não deve ultrapassar 330 cm. - O peso máximo é de 30 kg (real ou volumétrico). | Object | Obrigatório |
packages.dimensions.height | Altura do pacote em centímetros. | Number | Obrigatório |
packages.dimensions.width | Largura do pacote em centímetros. | Number | Obrigatório |
packages.dimensions.length | Comprimento do pacote em centímetros. | Number | Obrigatório |
packages.dimensions.weight | Peso do pacote em gramas. | Number | Obrigatório |
shipping_from.zip_code | Código postal do endereço de origem. Se este valor for informado, será usado para calcular a oferta. Caso contrário, serão aplicados os dados de Envios configurados no Mercado Pago. | String | Opcional |
shipping_to.zip_code | Código postal do endereço de destino. | String | Obrigatório |
Se a requisição estiver correta, a resposta retornará a cotação do envio, que pode conter mais de uma opção variável em preço e/ou prazo.
json{ "shipment_rate_id": "be9fae0d-1079-471e-887d-55861965d10e", "rates": [ { "options": [ { "id": "3c86ea36-fef7-4a9e-9092-d4eb6e744834", "pricing": { "base_price": "87", "price": "87", "discounts": [] }, "method": "standard", "pay_before": "2025-10-27T00:00:00-06:00", "delivery_promise": { "shipping_from": "2025-10-28T12:00:00-06:00", "shipping_to": "2025-10-30T12:00:00-06:00" }, "delivery_days": { "from": 3, "to": 5 } } ], "packages": [ { "quantity": 1, "dimensions": { "weight": "500", "width": "30", "height": "30", "length": "30" } } ] } ], "shipping_to": { "zip_code": "06720", "country_id": "MX", "city_id": "TUxNQ0NVQTczMTI", "state_id": "MX-DIF" } }
| Campo | Descrição | Tipo |
shipment_rate_id | Identificador da cotação. Use esse valor como shipment_rate_id ao criar o envio. | String |
rates | Lista de cotações para o pacote em função do endereço informado. | Array |
options | Lista das opções de cotações disponíveis. | Array |
id | Identificador da opção de envio. Use esse valor como option_id ao criar o envio a partir da cotação. | String |
base_price | Valor bruto do envio. | Number |
price | Valor líquido do envio. | Number |
method | Método de entrega. A única resposta possível para este campo é standard, para envios gratuitos. | String |
pay_before | Data esperada de pagamento para garantir a promessa de envio gerada. | Date |
delivery_promise.shipping_from | Data inicial da promessa de entrega. | String |
delivery_promise.shipping_to | Data final da promessa de entrega. | String |
delivery_days.from | Mínimo de dias úteis para a promessa de entrega. | Integer |
delivery_days.to | Máximo de dias úteis para a promessa de entrega. | Integer |
packages.quantity | Quantidade de pacotes cotados. | Number |
packages.dimensions | Dimensões do pacote cotado. | Object |
packages.dimensions.height | Altura do pacote. | Number |
packages.dimensions.width | Largura do pacote. | Number |
packages.dimensions.length | Comprimento do pacote. | Number |
packages.dimensions.weight | Peso do pacote. | Number |
shipping_to.zip_code | Código postal do endereço de destino. | String |
shipping_to.city_id | Identificador da cidade do endereço de destino. | String |
shipping_to.state_id | Sigla do estado do endereço de destino. | String |
shipping_to.country_id | Sigla do país do endereço de destino. | String |
Para conhecer os erros que esta solicitação pode retornar, acesse nossa Referência de APIAPI.
É possível configurar notificações Webhooks para receber alertas sobre envios e suas mudanças de status.
Para isso, é necessário indicar as URLs para as quais as mesmas serão enviadas seguindo o passo a passo abaixo:
- Acesse Suas integrações e selecione a aplicação integrada com o Checkout Pro para a qual você deseja ativar as notificações.
- No menu à esquerda, selecione Webhooks > Configurar notificações e configure a URL que será utilizada para recebê-las.
- Selecione a aba Modo produtivo e forneça uma
URL HTTPSpara receber notificações com sua integração produtiva.
- Selecione o evento Envios (Mercado Pago) para receber notificações, que serão enviadas no formato
JSONatravés de umHTTPS POSTpara a URL especificada anteriormente.
- Por fim, clique em Salvar configuração. Isso gerará uma chave secreta exclusiva para a aplicação, utilizada para validar a autenticidade das notificações recebidas, assegurando que elas sejam provenientes do Mercado Pago. Vale ressaltar que essa chave não possui prazo de validade, mas recomenda-se sua renovação periódica como medida de segurança. Para renovar a chave, basta clicar no botão Restabelecer.