Cotar frete · Meu Ecommerce Developers

POST/v1/rates

Retorna cada serviço habilitado com preço (BRL) e prazo. A loja vem da chave — não envie instanceId. Aceita chave pública (pk_) ou secreta (mk_). CORS habilitado para uso direto no frontend.

Capacidade: Fretes e cotações, disponível pela API REST do Meu Ecommerce.

Autenticação

Chave pública pk_… ou secreta mk_…. A cotação pode ser feita pelo navegador.

Corpo da requisição

Campo	Tipo	Obrigatório no objeto	Descrição
`destinationCep`	string	Sim	CEP de destino (8 dígitos; traços/espaços são ignorados).
`items`	array	Sim	Mín. 1 itens. Máx. 50 itens.
`items[].name`	string	Sim	Product name.
`items[].quantity`	integer	Sim	Units of this product in the cart. Mínimo: 1.
`items[].unitPriceBRL`	number	Sim	Unit price in BRL (used for free-shipping thresholds). Mínimo: 0.
`items[].weightKg`	number	Não	Unit weight in kg. Defaults to 0.3kg if omitted. Maior que 0.
`items[].productId`	string	Não	Your catalog's product id. Advanced plan: remembers this product's estimated dimensions between quotes (otherwise the name is the key).
`items[].variantId`	string	Não	Variant id (size/color), so each variant keeps its own dimensions.
`items[].sku`	string	Não	SKU, used as the product key when there is no productId.
`items[].dimensionsCm`	object	Não	Unit dimensions in cm, when known. Advanced plan: used as-is instead of the AI estimate. Other plans ignore it (they pack into the store's first box).
`items[].dimensionsCm.length`	number	Sim	Maior que 0.
`items[].dimensionsCm.width`	number	Sim	Maior que 0.
`items[].dimensionsCm.height`	number	Sim	Maior que 0.
`requestId`	string	Não	Id de correlação/idempotência. Gerado automaticamente se omitido.

Exemplo

{
  "destinationCep": "20040002",
  "items": [
    {
      "name": "Camiseta de algodão",
      "quantity": 1,
      "unitPriceBRL": 89.9,
      "weightKg": 0.3
    }
  ]
}

Resposta de sucesso

Cotação (pode vir vazia com um reason informativo, ex.: CEP sem cobertura).

Campo	Tipo	Obrigatório no objeto	Descrição
`rates`	array	Sim	—
`rates[].code`	string	Sim	—
`rates[].serviceId`	string	Sim	—
`rates[].label`	string	Sim	—
`rates[].deliveryDays`	integer	Sim	—
`rates[].price`	number	Sim	—
`rates[].free`	boolean	Não	—
`reason`	string	Não	Por que a lista veio vazia, quando aplicável.
`actionUrl`	string	Não	—

Códigos HTTP do contrato

Status	Descrição
200	Cotação (pode vir vazia com um `reason` informativo, ex.: CEP sem cobertura).
400	Corpo inválido.
401	Chave ausente ou inválida.
402	Assinatura necessária (`subscription_required`) ou franquia grátis do mês esgotada (`free_quota_exceeded`, com `Retry-After` até a virada do mês UTC).
404	Loja não encontrada.
413	Corpo grande demais.
429	Limite por minuto excedido (`rate_limited`). Aguarde os segundos indicados em `Retry-After`.
502	Falha ao consultar os Correios.

Consulte erros e limites para os erros de autenticação e escopo, incluindo 403, e o formato de falha.

Schema completo

Baixar OpenAPI · Primeira integração

Contrato e comportamento

requestId pode ser usado para correlação; não há garantia documentada de deduplicação. Uma resposta vazia precisa ser tratada pela aplicação.