medusa-fulfillment-melhor-envio

Provedor de fulfillment do Melhor Envio para Medusa v2.

Calcula fretes em tempo real no checkout usando a API do Melhor Envio, com suporte a PAC, SEDEX, Jadlog e outros serviços.

Instalação

npm install medusa-fulfillment-melhor-envio

Configuração

1. medusa-config.ts

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/fulfillment",
      options: {
        providers: [
          {
            resolve: "medusa-fulfillment-melhor-envio",
            id: "melhor-envio",
            options: {
              accessToken:     process.env.MELHOR_ENVIO_ACCESS_TOKEN,
              baseUrl:         process.env.MELHOR_ENVIO_BASE_URL,
              fromPostalCode:  process.env.MELHOR_ENVIO_FROM_POSTAL_CODE,
              services:        process.env.MELHOR_ENVIO_SERVICES,
              defaultWidthCm:  process.env.MELHOR_ENVIO_DEFAULT_WIDTH_CM,
              defaultHeightCm: process.env.MELHOR_ENVIO_DEFAULT_HEIGHT_CM,
              defaultLengthCm: process.env.MELHOR_ENVIO_DEFAULT_LENGTH_CM,
              defaultWeightKg: process.env.MELHOR_ENVIO_DEFAULT_WEIGHT_KG,
              userAgent:       process.env.MELHOR_ENVIO_USER_AGENT,
            },
          },
        ],
      },
    },
  ],
})

2. Variáveis de ambiente

| Variável | Obrigatória | Descrição | |---|---|---| | MELHOR_ENVIO_ACCESS_TOKEN | Sim | Token de acesso da sua conta Melhor Envio | | MELHOR_ENVIO_FROM_POSTAL_CODE | Sim | CEP de origem dos envios (somente números) | | MELHOR_ENVIO_BASE_URL | Não | URL da API. Padrão: https://www.melhorenvio.com.br | | MELHOR_ENVIO_SERVICES | Não | IDs dos serviços separados por vírgula. Padrão: 1,2 | | MELHOR_ENVIO_DEFAULT_WIDTH_CM | Não | Largura padrão do pacote em cm. Padrão: 11 | | MELHOR_ENVIO_DEFAULT_HEIGHT_CM | Não | Altura padrão do pacote em cm. Padrão: 4 | | MELHOR_ENVIO_DEFAULT_LENGTH_CM | Não | Comprimento padrão do pacote em cm. Padrão: 16 | | MELHOR_ENVIO_DEFAULT_WEIGHT_KG | Não | Peso padrão do pacote em kg. Padrão: 0.3 | | MELHOR_ENVIO_USER_AGENT | Não | User-Agent das requisições. Padrão: medusa-fulfillment-melhor-envio/0.1.0 |

Exemplo de .env:

MELHOR_ENVIO_ACCESS_TOKEN=seu-token-aqui
MELHOR_ENVIO_FROM_POSTAL_CODE=01310100
MELHOR_ENVIO_SERVICES=1,2

Como obter o token: acesse sua conta em melhorenvio.com.br > Configurações > Tokens de acesso > Gerar novo token.

Serviços disponíveis

Configure os IDs desejados em MELHOR_ENVIO_SERVICES (separados por vírgula):

| ID | Serviço | |---|---| | 1 | Correios - PAC | | 2 | Correios - SEDEX | | 3 | Jadlog - .Package | | 4 | Jadlog - .com | | 7 | Via Brasil - Rodoviário | | 8 | Azul Cargo - Express | | 9 | Latam Cargo | | 17 | Buslog | | 20 | TNT | | 99 | Correios - SEDEX 12 | | 100 | Correios - SEDEX 10 | | 104 | Correios - Mini Envios |

Ativando no Admin do Medusa

1. Reinicie o backend após configurar as variáveis de ambiente
2. Acesse Settings > Locations
3. Abra a localização de estoque desejada
4. Clique em Add Fulfillment Provider e selecione Melhor Envio
5. Na aba Shipping Options da service zone do Brasil, crie uma opção de envio para cada serviço desejado
6. Selecione o provider melhor-envio e informe o service_id correspondente (ex: 1 para PAC, 2 para SEDEX)

Dimensões dos produtos

O cálculo usa os campos width, height, length (em cm) e weight (em kg) da variante do produto no Medusa. Configure esses campos em cada variante para obter cotações precisas.

Se não estiverem preenchidos, os valores padrão das variáveis de ambiente são usados.

Peso em gramas: se o campo weight da variante for maior que 30, ele é tratado automaticamente como gramas e convertido para kg.

Dados disponíveis no storefront

Após o cálculo, shippingOption.data.melhor_envio contém:

{
  "service_id": "2",
  "delivery_time": 2,
  "calculated_at": "2026-06-01T12:00:00.000Z",
  "quote": {
    "id": 2,
    "name": "SEDEX",
    "price": "12.17",
    "delivery_time": 2,
    "company": { "name": "Correios" }
  }
}

Use delivery_time para exibir o prazo estimado de entrega no checkout.

Sandbox

Para testar sem processar envios reais:

MELHOR_ENVIO_BASE_URL=https://sandbox.melhorenvio.com.br
MELHOR_ENVIO_ACCESS_TOKEN=seu-token-sandbox

Limitações da v0.1.0

• Geração de etiquetas não implementada — createFulfillment registra a cotação mas não compra a etiqueta
• Cancelamento não chama a API do Melhor Envio
• Sem rastreamento automático via webhooks

Essas funcionalidades estão planejadas para versões futuras.

Licença

MIT