POST

`shop.frete.calcular`

Calcula tarifas compatíveis com o carrinho e destino, combinando perfis quando necessário.

Grupo: ShopRevisão: 2026-10-02Escopo recomendado: shop.frete.calcular

Exemplos seguros e fictícios. O domínio example.invalid e a credencial demonstrativa abaixo não funcionam. Use o token real somente no servidor da sua integração e nunca o inclua em páginas públicas.

Parâmetros

Parâmetros aceitos por shop.frete.calcular
Campo	Tipo	Obrigatoriedade	Descrição	Exemplo fictício
`cep`	string	Obrigatório	CEP de destino; pontuação é normalizada. Envie 8 dígitos.	`"01001000"`
`itens`	array<object> \| string JSON	Obrigatório	Lista de SKU e quantidade. Este método aceita array JSON ou string JSON; string inválida vira lista vazia.	`[{"sku":"DEMO-01","qtd":2}]`
`itens[].sku`	string	um dos dois obrigatório	SKU do produto. Em cada item informado, envie sku OU codigo; sku tem precedência quando ambos são preenchidos.	`"DEMO-01"`
`itens[].codigo`	string	um dos dois obrigatório	Alternativa a itens[].sku. Em cada item informado, é necessário identificar o produto por sku OU codigo.	`"DEMO-01"`
`itens[].qtd`	integer	Opcional	Quantidade; quantidade é alias; valores são arredondados para baixo e limitados ao mínimo 1.	`2`

Exemplos fictícios

Os exemplos documentam o formato; eles não executam nenhuma operação.

Requisição

cURL demonstrativo

curl --request POST \
  'https://example.invalid/api/v1/CREDENCIAL_FICTICIA_SEM_VALOR/shop.frete.calcular' \
  --header 'Content-Type: application/json' \
  --data '{"cep":"01001000","itens":[{"sku":"DEMO-01","qtd":2}]}'

Corpo JSON

{
  "cep": "01001000",
  "itens": [
    {
      "sku": "DEMO-01",
      "qtd": 2
    }
  ]
}

Resposta HTTP 200

{
  "ok": true,
  "method": "shop.frete.calcular",
  "result": {
    "cep": "01001000",
    "uf": "SP",
    "opcoes": [
      {
        "opcao_ids": [
          "55555555-5555-4555-8555-555555555555"
        ],
        "nome": "Entrega padrão",
        "valor_cents": 900,
        "prazo_min_dias": 2,
        "prazo_max_dias": 4,
        "id": "55555555-5555-4555-8555-555555555555",
        "valor": 9,
        "entrega_estimada": null
      }
    ],
    "retirada": null,
    "entrega_local": null,
    "origem": {
      "cep": "01001000",
      "uf": "SP"
    },
    "motivo": null,
    "itens_sem_frete": [],
    "peso_incompleto": false
  }
}

Erros

Condições de erro específicas de shop.frete.calcular
HTTP	Código	Condição
403	`TOKEN_NO_COMPANY`	Token sem empresa associada.

Consulte também os erros globais e limites.

Observações

Respostas sem cotação usam HTTP 200 e motivo cep_invalido, sem_itens, nao_configurado ou sem_cobertura. Não são falhas HTTP.
Use todos os opcao_ids para identificar a composição da opção calculada; id identifica somente a linha.
valor_cents é inteiro em centavos; valor é reais. Valor zero significa frete grátis.
entrega_estimada é null ou {de, ate, processamento_dias}; o cálculo considera dias úteis e processamento configurado.
entrega_local pode ser {ativo:true,elegivel:false} ou elegível com nome, valor_cents, valor, minimo_pedido_cents e instrucoes; zonas por raio podem acrescentar distancia, raio e unidade.
entrega_local pode coexistir com motivo sem_cobertura. Sua presença não garante elegibilidade em um fluxo comercial posterior.
peso_incompleto indica produtos cujo peso foi tratado como zero. O cálculo não é prova de disponibilidade/estoque.
Uma falta de cobertura em qualquer perfil impede cotação parcial do carrinho.
O cálculo por raio pode consultar um serviço de geocodificação e manter um cache técnico do CEP. Ele não cria nem altera pedidos, tarifas ou outras regras comerciais.