API legada/Referência completa/Frete e rotas

GETFormas de envio para apps

Lista as formas de envio cadastradas na loja, para aplicativos de terceiros autorizados com token de app e o escopo read_shipping.

Devolve todas as formas de envio da loja: as da própria loja e as cadastradas por sellers, com status, transportadora, prazo e taxas. É a rota de leitura de frete da API de aplicativos (as rotas /api/admin/... autenticadas por token de app). Use para espelhar o cadastro de frete em um sistema externo ou para montar uma tela de configuração.

Esta rota é só para token de app (vat_...). Um JWT de administrador não funciona aqui. Como obter e usar tokens de app: Autenticação.

GET/api/admin/shipping-methodsAutenticada

Listar as formas de envio da loja

Cabeçalhos

Authorizationstringobrigatório

Bearer vat_..., um token de app com o escopo read_shipping.

A rota não tem parâmetros de consulta: não filtra nem pagina.

Exemplo de requisição

bash

curl "$BASE_URL/api/admin/shipping-methods" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Formas de envio (lista reduzida a 1 item)

json

{
  "total": 6,
  "methods": [
    {
      "id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "display_id": 53,
      "name": "Motoboy",
      "code": "motoboy_msdxztz7",
      "carrier": "manual",
      "rate_calculation": "M",
      "delivery_time": "30 min",
      "status": "A",
      "min_weight": 0,
      "max_weight": 0,
      "flat_rate": 500,
      "free_shipping_threshold": 0,
      "estimated_days": 0,
      "free_shipping": false,
      "is_address_required": false,
      "use_for_all_vendors": false,
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "position": 0,
      "created_at": "2026-08-04T00:51:15.019077Z",
      "updated_at": "2026-09-15T19:47:24.604493Z",
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "module": "manual",
      "rate_str": "5.00"
    }
  ]
}

Campos da resposta

totalinteger

Quantidade de formas de envio devolvidas.

methodsarray

As formas de envio. A lista pode ser grande e não tem paginação.

methods[].iduuid

Id da forma de envio. shipping_id repete o mesmo valor.

methods[].display_idinteger

Número curto, sequencial, que o painel mostra ao lado do UUID.

methods[].namestring

Nome exibido ao cliente. shipping repete o valor.

methods[].codestring

Código interno estável (por exemplo standard, express, correios_pac).

methods[].carrierstring

Transportadora: correios, jadlog, frenet, simfrete ou manual. module repete o valor.

methods[].rate_calculationstring

MR

M tarifa manual por área de entrega; R cotação em tempo real na API da transportadora.

methods[].delivery_timestring

Texto de prazo exibido (7-10 dias úteis).

methods[].estimated_daysinteger

Prazo em dias (campo antigo; o prazo por área tem prioridade).

methods[].statusstring

AD

A ativa, D desativada.

methods[].flat_rateinteger

Tarifa fixa em centavos (campo antigo, mantido para dados legados). rate_str mostra o mesmo valor em reais, como string.

methods[].free_shipping_thresholdinteger

Valor mínimo do carrinho, em centavos, para frete grátis (campo antigo).

methods[].free_shippingboolean

A forma aceita promoções de frete grátis.

methods[].min_weightnumber

Peso mínimo atendido, em kg (0 é sem mínimo).

methods[].max_weightnumber

Peso máximo atendido, em kg (0 é sem máximo).

methods[].is_address_requiredboolean

A forma exige endereço de entrega.

methods[].use_for_all_vendorsboolean

Disponível por padrão para todos os sellers.

methods[].company_iduuid|null

Seller dono da forma. Ausente quando a forma vale para a loja toda.

methods[].vendor_namestring

Nome do seller dono, quando houver.

methods[].positioninteger

Ordem de exibição.

methods[].created_atstring

Criação, em RFC 3339.

methods[].updated_atstring

Última alteração, em RFC 3339.

Há ainda campos de configuração: config e service_params (JSON livre com os parâmetros da integração com a transportadora, devolvido como está no cadastro), tax_ids e usergroup_ids (listas de ids separadas por vírgula), surcharge, surcharge_percent e rate_area_id (campos antigos de tarifa), icon_url, timestamp e updated_timestamp (Unix). Trate config e service_params como dados sensíveis: dependendo da transportadora, o cadastro guarda credenciais ali.

Erros

Status	Quando	Corpo
401	Sem `Authorization` ou sem token `vat_...`	`{"error": "app_token_required"}`
401	Token `vat_...` inválido, expirado ou revogado	`{"error": "invalid or expired app access token"}`
403	Token sem o escopo `read_shipping`	`{"error": "missing_scope", "required": "read_shipping"}`
500	Falha ao ler as formas de envio	`{"message": "failed to list shipping methods", ...}`

Veja também