---
updatedAt: 2026-07-14T19:32:54.000Z
agentTools:
projectIndex: https://docs.melhorenvio.com.br/llms.txt
---
# Inserir fretes no carrinho
Carrinho de Compras
Adiciona uma etiqueta de frete ao carrinho de compras do Melhor Envio. O retorno incluirá o id da etiqueta gerada. Salve este `id` para os próximos passos (como o checkout e geração da etiqueta).
Nessa rota, a integração deve utilizar os dados obtidos no retorno de uma cotação realizada previamente, além das informações do remetente, destinatário e dos pacotes.
> ⚠️ Atenção:
>
> Caso informado a UF (`state_abbr`) na requisição, será validado se ela corresponde ao CEP.
# Regras e Considerações
**1. Documentos (`from` e `to`)**
* **Pessoa Física:** Enviar apenas o campo `document` (CPF);
* **Pessoa Jurídica:** Enviar obrigatoriamente o `company_document` (CNPJ) e, se houver, o `state_register` (Inscrição Estadual) e `economic_activity_code` (CNAE - obrigatório para LATAM).
**2. Agência (`agency`)**
* O campo `agency` (ID da agência) é obrigatório para as transportadoras Latam Cargo, Azul Cargo e Buslog e **apenas em integrações que utilizam o token gerado diretamente no painel** do Melhor Envio. Fora desse cenário, o ideal é que não seja informado.
**3. Nota Fiscal vs. Declaração de Conteúdo (`options`)**
* Para envios comerciais, é obrigatório enviar a chave da Nota Fiscal no campo `options.invoice.key` e a inscrição estadual em `from.state_register`;
* Para envios não comerciais (com declaração de conteúdo), o campo `options.invoice` não deve ser enviado e o campo `from.state_register` deve estar vazio ou conter o valor `"ISENTO"`;
* A partir de 06/04/2026 API do Melhor Envio terá integração com a SEFAZ para comunicação da DCe, desta forma, é obrigatorio que seja informado na requisição de Inserir Fretes no Carrinho o atributo `products` de forma correta e completa. A API do Melhor Envio disponbiliza tambem um endpoint especifico para impressão da DCe que poderá encontrar neste link [Impressão de DACE](https://docs.melhorenvio.com.br/reference/impressao-dace). Caso a geração da DCe tenha sido previamente feita, será necessário informar a chave DCe para a API do Melhor Envio no momento de criação de etiqueta através do parametro `options.dce.key`.
> ⚠️ A transportadora Azul possui disponibilidade para envios comerciais via API desde que seja enviado o conteudo do XML da NFe adaptado para JSON. O conteudo do XML deve ser enviado através do "options.invoice.xml\_content".
**4. Valor Segurado (`options.insurance_value`)**
* Deve conter o valor total de seguro do envio, que geralmente corresponde à somatória dos valores dos produtos declarados na Nota Fiscal ou Declaração de Conteúdo.
**5. Volumes (Pacotes)**
* Na cotação, você pode receber um array com múltiplos pacotes. Ao inserir no carrinho, o parâmetro `volumes` deve conter um array com as dimensões e pesos de cada um desses pacotes.
**Exemplo de volumes para 2 pacotes:**
```json
"volumes": [
{ "height": 43, "width": 60, "length": 70, "weight": 30 },
{ "height": 30, "width": 40, "length": 50, "weight": 10 }
]
```
> 📘 Atenção:
>
> As transportadoras Correios, J\&T e Loggi não aceitam múltiplos volumes em uma única requisição. Se a cotação retornar *n* pacotes para essas transportadoras, você deverá realizar *n* chamadas separadas para a rota /api/v2/me/cart, cada uma contendo apenas 1 volume.
**6. Identificação da Plataforma (`options`)**
* `options.platform`: Se não for preenchido, será usado o nome do seu aplicativo;
* `options.tags`: Utilize para identificar o pedido com base em informações da sua plataforma (Ex: ID do pedido);
* `options.reminder`: Anotação que será apresentada com a impressão da etiqueta, fora da área de recorte.
```json
{
"service": 4,
"from": {
"name": "Remetente",
"email": "remetente@email.com",
"phone": "11912345678",
"document": "",
"company_document": "46867029000176",
"state_register": "",
"economic_activity_code": "4687701",
"address": "Rua do Remetente",
"complement": "",
"number": "1234",
"district": "Bairro do Remetente",
"city": "Cidade do Remetente",
"postal_code": "09831510",
"state_abbr": "SP"
},
"to": {
"name": "Destinatário",
"email": "destinatario@email.com",
"phone": "41912345678",
"document": "05596752088",
"state_register": "ISENTO",
"address": "Rua do Destinatário",
"complement": "",
"number": "1234",
"district": "Bairro do Destinatário",
"city": "Cidade do Destinatário",
"postal_code": "11730000",
"country_id": "BR",
"state_abbr": "SP"
},
"products": [
{
"name": "Teste 1",
"quantity": "1",
"unitary_value": "400"
},
{
"name": "Teste 2",
"quantity": "1",
"unitary_value": "200"
}
],
"volumes": [
{
"height": 15,
"width": 30,
"length": 40,
"weight": 120
},
{
"height": 4,
"width": 10,
"length": 10,
"weight": 0.1
}
],
"options": {
"platform": "Minha Loja",
"reminder": "Compra XYZ",
"insurance_value": 600,
"receipt": false,
"own_hand": false,
"reverse": false,
"dce":{
"key":""
},//Incluir este parametro a partir de 06/04/2026 em envios com DC-e gerada fora da integração com o Melhor Envio
"invoice": {
"key": "422404***1497000123400598762797110***653",
"xml_content":""
},
"tags": [
{
"tag": "Identificação do pedido na plataforma, exemplo: 1000007",
"url": "Link direto para o pedido na plataforma, se possível, caso contrário pode ser passado o valor null"
}
]
}
}
```
Também disponibilizamos um [fluxograma](https://melhorenvio.s3.sa-east-1.amazonaws.com/partners/manual/Diagrama+de+integra%C3%A7%C3%A3o+-+Fluxograma+de+compra+e+impress%C3%A3o+de+etiqueta+de+envio.pdf) que poderá lhe auxiliar a visualizar todo o processo de compra de envios, assim como servir de base para que você adapte da melhor maneira ao fluxo de seu sistema.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "api-melhor-envio-sandbox",
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox.melhorenvio.com.br/",
"description": "Ambiente de Sandbox (Testes)"
},
{
"url": "https://melhorenvio.com.br/",
"description": "Ambiente de Produção (Real)"
}
],
"security": [
{}
],
"paths": {
"/api/v2/me/cart": {
"post": {
"summary": "Inserir fretes no carrinho",
"description": "Carrinho de Compras",
"operationId": "inserir-fretes-no-carrinho",
"parameters": [
{
"name": "Accept",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "application/json"
}
},
{
"name": "Content-Type",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "application/json"
}
},
{
"name": "Authorization",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "Bearer token"
}
},
{
"name": "User-Agent",
"in": "header",
"description": "O User-Agent deve conter o nome da sua aplicação e um e-mail de contato técnico.",
"required": true,
"schema": {
"type": "string",
"default": "Aplicação (email para contato técnico)"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"service",
"from",
"to",
"products",
"volumes"
],
"properties": {
"service": {
"type": "integer",
"description": "Id referente do serviço da transportadora",
"format": "int32"
},
"agency": {
"type": "integer",
"description": "Id da agência/unidade onde será postado o envio (consultar regras das transportadoras)",
"format": "int32"
},
"from": {
"type": "object",
"description": "Informações do remetente do envio",
"properties": {
"name": {
"type": "string",
"description": "Nome"
},
"phone": {
"type": "string",
"description": "Telefone"
},
"email": {
"type": "string",
"description": "E-mail"
},
"document": {
"type": "string",
"description": "CPF"
},
"company_document": {
"type": "string",
"description": "CNPJ"
},
"state_register": {
"type": "string",
"description": "Inscrição Estadual"
},
"address": {
"type": "string",
"description": "Logradouro"
},
"complement": {
"type": "string",
"description": "Complemento"
},
"number": {
"type": "string",
"description": "Número"
},
"district": {
"type": "string",
"description": "Bairro"
},
"city": {
"type": "string",
"description": "Cidade"
},
"country_id": {
"type": "string",
"description": "País"
},
"postal_code": {
"type": "string",
"description": "Cep"
},
"state_abbr": {
"type": "string",
"description": "Estado"
},
"note": {
"type": "string",
"description": "Observação"
}
},
"required": [
"name",
"document",
"company_document",
"address",
"number",
"district",
"city",
"country_id",
"postal_code",
"state_abbr"
]
},
"to": {
"type": "object",
"description": "Informações do destinatário do envio",
"properties": {
"name": {
"type": "string",
"description": "Nome"
},
"phone": {
"type": "string",
"description": "Telefone"
},
"email": {
"type": "string",
"description": "E-mail"
},
"document": {
"type": "string",
"description": "CPF"
},
"company_document": {
"type": "string",
"description": "CNPJ"
},
"state_register": {
"type": "string",
"description": "Inscrição Estadual"
},
"address": {
"type": "string",
"description": "Logradouro"
},
"complement": {
"type": "string",
"description": "Complemento"
},
"number": {
"type": "string",
"description": "Número"
},
"district": {
"type": "string",
"description": "Bairro"
},
"city": {
"type": "string",
"description": "Cidade"
},
"country_id": {
"type": "string",
"description": "País"
},
"postal_code": {
"type": "string",
"description": "Cep"
},
"state_abbr": {
"type": "string",
"description": "Estado"
},
"note": {
"type": "string",
"description": "Observação"
}
},
"required": [
"name",
"document",
"company_document",
"address",
"number",
"district",
"city",
"country_id",
"postal_code",
"state_abbr"
]
},
"products": {
"type": "array",
"description": "Informações dos produtos que serão enviados (utilizado na declaração de conteúdo)",
"items": {
"properties": {
"name": {
"type": "string",
"description": "Nome"
},
"quantity": {
"type": "string",
"description": "Quantidade"
},
"unitary_value": {
"type": "string",
"description": "Valor Unitário"
}
},
"required": [
"name",
"quantity",
"unitary_value"
],
"type": "object"
}
},
"volumes": {
"type": "array",
"description": "Descrição dos volumes contidos no envio",
"items": {
"properties": {
"height": {
"type": "integer",
"description": "Altura",
"format": "int32"
},
"width": {
"type": "integer",
"description": "Largura",
"format": "int32"
},
"length": {
"type": "integer",
"description": "Comprimento",
"format": "int32"
},
"weight": {
"type": "number",
"description": "Peso",
"format": "float"
}
},
"required": [
"height",
"width",
"length",
"weight"
],
"type": "object"
}
},
"options": {
"type": "object",
"description": "Informações complementares do envio",
"required": [
"insurance_value",
"receipt",
"own_hand",
"reverse",
"non_commercial"
],
"properties": {
"insurance_value": {
"type": "number",
"description": "Valor Segurado",
"format": "double"
},
"receipt": {
"type": "boolean",
"description": "Flag para setar o serviço adicional de Aviso de Recebimento,"
},
"own_hand": {
"type": "boolean",
"description": "Flag para setar o serviço adicional de Mãos Próprias"
},
"reverse": {
"type": "boolean",
"description": "Flag para identificar o envio como Envio reverso"
},
"non_commercial": {
"type": "boolean",
"description": "Flag para identificar o envio como um Envio não comercial"
},
"invoice": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"description": "Chave da Nota Fiscal"
}
}
},
"dce": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Chave da DCe"
}
}
},
"plataform": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"properties": {
"tag": {
"type": "string",
"description": "Identificação do pedido na plataforma"
},
"Url": {
"type": "string",
"description": "Url da plataforma"
}
},
"type": "object"
}
}
}
}
}
}
}
}
},
"responses": {
"201": {
"description": "201",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"id\": \"10b87ac0-e99d-4aa4-b8b0-b147a84e16bf\",\n \"protocol\": \"ORD-20220397305\",\n \"service_id\": 3,\n \"agency_id\": 48,\n \"contract\": null,\n \"service_code\": null,\n \"quote\": 25.35,\n \"price\": 25.35,\n \"coupon\": null,\n \"discount\": 5.71,\n \"delivery_min\": 5,\n \"delivery_max\": 6,\n \"status\": \"pending\",\n \"reminder\": null,\n \"insurance_value\": 50,\n \"weight\": null,\n \"width\": null,\n \"height\": null,\n \"length\": null,\n \"diameter\": null,\n \"format\": \"box\",\n \"billed_weight\": 3.5,\n \"receipt\": false,\n \"own_hand\": false,\n \"collect\": false,\n \"collect_scheduled_at\": null,\n \"reverse\": false,\n \"non_commercial\": true,\n \"authorization_code\": null,\n \"tracking\": null,\n \"self_tracking\": null,\n \"delivery_receipt\": null,\n \"additional_info\": null,\n \"cte_key\": null,\n \"paid_at\": null,\n \"generated_at\": null,\n \"posted_at\": null,\n \"delivered_at\": null,\n \"canceled_at\": null,\n \"suspended_at\": null,\n \"expired_at\": null,\n \"created_at\": \"2022-03-29 12:50:19\",\n \"updated_at\": \"2022-03-29 12:50:19\",\n \"parse_pi_at\": null,\n \"products\": [\n {\n \"name\": \"Papel adesivo para etiquetas 1\",\n \"quantity\": 3,\n \"unitary_value\": 100,\n \"weight\": null\n },\n {\n \"name\": \"Papel adesivo para etiquetas 2\",\n \"quantity\": 1,\n \"unitary_value\": 700,\n \"weight\": null\n }\n ],\n \"volumes\": [\n {\n \"id\": 101594,\n \"height\": \"10.00\",\n \"width\": \"15.00\",\n \"length\": \"20.00\",\n \"diameter\": \"0.00\",\n \"weight\": \"3.50\",\n \"format\": \"box\",\n \"created_at\": \"2022-03-29 12:50:19\",\n \"updated_at\": \"2022-03-29 12:50:19\"\n }\n ]\n}"
}
},
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "10b87ac0-e99d-4aa4-b8b0-b147a84e16bf"
},
"protocol": {
"type": "string",
"example": "ORD-20220397305"
},
"service_id": {
"type": "integer",
"example": 3,
"default": 0
},
"agency_id": {
"type": "integer",
"example": 48,
"default": 0
},
"contract": {},
"service_code": {},
"quote": {
"type": "number",
"example": 25.35,
"default": 0
},
"price": {
"type": "number",
"example": 25.35,
"default": 0
},
"coupon": {},
"discount": {
"type": "number",
"example": 5.71,
"default": 0
},
"delivery_min": {
"type": "integer",
"example": 5,
"default": 0
},
"delivery_max": {
"type": "integer",
"example": 6,
"default": 0
},
"status": {
"type": "string",
"example": "pending"
},
"reminder": {},
"insurance_value": {
"type": "integer",
"example": 50,
"default": 0
},
"weight": {},
"width": {},
"height": {},
"length": {},
"diameter": {},
"format": {
"type": "string",
"example": "box"
},
"billed_weight": {
"type": "number",
"example": 3.5,
"default": 0
},
"receipt": {
"type": "boolean",
"example": false,
"default": true
},
"own_hand": {
"type": "boolean",
"example": false,
"default": true
},
"collect": {
"type": "boolean",
"example": false,
"default": true
},
"collect_scheduled_at": {},
"reverse": {
"type": "boolean",
"example": false,
"default": true
},
"non_commercial": {
"type": "boolean",
"example": true,
"default": true
},
"authorization_code": {},
"tracking": {},
"self_tracking": {},
"delivery_receipt": {},
"additional_info": {},
"cte_key": {},
"paid_at": {},
"generated_at": {},
"posted_at": {},
"delivered_at": {},
"canceled_at": {},
"suspended_at": {},
"expired_at": {},
"created_at": {
"type": "string",
"example": "2022-03-29 12:50:19"
},
"updated_at": {
"type": "string",
"example": "2022-03-29 12:50:19"
},
"parse_pi_at": {},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "Papel adesivo para etiquetas 1"
},
"quantity": {
"type": "integer",
"example": 3,
"default": 0
},
"unitary_value": {
"type": "integer",
"example": 100,
"default": 0
},
"weight": {}
}
}
},
"volumes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"example": 101594,
"default": 0
},
"height": {
"type": "string",
"example": "10.00"
},
"width": {
"type": "string",
"example": "15.00"
},
"length": {
"type": "string",
"example": "20.00"
},
"diameter": {
"type": "string",
"example": "0.00"
},
"weight": {
"type": "string",
"example": "3.50"
},
"format": {
"type": "string",
"example": "box"
},
"created_at": {
"type": "string",
"example": "2022-03-29 12:50:19"
},
"updated_at": {
"type": "string",
"example": "2022-03-29 12:50:19"
}
}
}
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"error\": {\n \"volumes\": [\n [\n \"Peso do pacote 1 não informado\",\n \"Altura do pacote 1 não informada\",\n \"Largura do pacote 1 não informada\",\n \"Comprimento do pacote 1 não informado\"\n ]\n ]\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"volumes": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"example": "Peso do pacote 1 não informado"
}
}
}
},
"description": "Erro de validação. O corpo da resposta indicará quais campos (ex: `volumes`) contêm erros."
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```