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. 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:

"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.

{
    "service": 4,
    "from": {
        "name": "Remetente",
        "email": "[email protected]",
        "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": "[email protected]",
        "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 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.