Listar e consultar métodos
Lista todos os métodos de envio da loja, de qualquer status, e lê um método pelo id.
Use estas rotas para ver o cadastro de frete completo: o que está ativo, o que foi desativado e a qual seller cada método pertence. Diferente do que o cliente enxerga no checkout, a listagem do administrador traz todos os métodos, inclusive os desativados e os de qualquer seller. A listagem não é paginada.
Listar métodos
/api/v1/admin/shipping-methodsAdminLista os métodos de envio
Sem parâmetros de consulta. Exige view_shipping ou manage_shipping.
Exemplo de requisição
Resposta
200Métodos retornados
Campos da resposta
methodsarrayTodos os métodos, sem ordem garantida (use
position para ordenar na sua tela).totalintegerQuantidade de métodos devolvidos.
methods[].iduuidIdentificador do método (UUID).
methods[].display_idintegerNúmero curto e sequencial para humanos ("método nº 53"). Não substitui o UUID em nenhuma rota.
methods[].tenant_iduuidLoja dona do método.
methods[].namestringNome mostrado ao cliente no checkout.
methods[].codestringCódigo único do método na loja.
methods[].carrierstringTransportadora ou integração:
manual (preço cadastrado por você) ou o código de uma integração, como correios.methods[].carrier_service_codestringCódigo do serviço no contrato da transportadora. Ausente quando não se aplica.
methods[].rate_calculationstringMRComo o preço é obtido:
M manual (tabelas da loja) ou R em tempo real (consulta a transportadora).methods[].descriptionstringTexto livre. Ausente quando vazio.
methods[].delivery_timestringPrazo em texto livre mostrado ao cliente, por exemplo
3-5 dias úteis.methods[].statusstringADA ativo ou D desativado. Só métodos ativos aparecem no checkout.methods[].min_weightnumberPeso mínimo do carrinho, em kg.
0 = sem mínimo.methods[].max_weightnumberPeso máximo do carrinho, em kg.
0 = sem máximo.methods[].free_shipping_thresholdintegerDescontinuado. Subtotal em centavos acima do qual o frete é grátis. Prefira políticas de frete ou faixas.
methods[].flat_rateintegerPreço fixo em centavos (
1500 = R$ 15,00), usado quando não há faixa que se aplique.methods[].estimated_daysintegerDescontinuado. Prazo em dias quando não há prazo por área. Veja Áreas do método.
methods[].configobjectJSON específico da integração (descontinuado). Ausente quando vazio.
methods[].service_paramsobjectParâmetros da transportadora (dimensões padrão etc.). Ausente quando vazio.
methods[].free_shippingbooleanSe o método pode receber frete grátis de promoções.
methods[].is_address_requiredbooleanSe o método exige endereço de entrega (falso para retirada).
methods[].rate_area_iduuidDescontinuado: área de tarifa única do método. Os vínculos atuais ficam em Áreas do método.
methods[].tax_idsstringIds de impostos separados por vírgula.
methods[].usergroup_idsstringIds de grupos de usuários separados por vírgula. Vazio = todos os clientes.
methods[].icon_urlstringURL do ícone mostrado no checkout.
methods[].surchargeintegerDescontinuado. Acréscimo fixo em centavos.
methods[].surcharge_percentintegerDescontinuado. Acréscimo percentual.
methods[].use_for_all_vendorsbooleanSe um método da loja (sem
company_id) vale para o carrinho de todos os sellers.methods[].company_iduuidSeller (lojista) dono do método. Ausente = método da loja inteira.
methods[].vendor_namestringNome do seller dono. Só aparece na listagem.
methods[].positionintegerOrdem de exibição no checkout (menor primeiro).
methods[].created_atstringCriação, RFC 3339 em UTC.
methods[].updated_atstringÚltima alteração, RFC 3339 em UTC.
methods[].shipping_iduuidAlias de
id. Os campos shipping, module, rate_str, timestamp e updated_timestamp também são aliases (nome, carrier, preço como string decimal e datas Unix).Consultar um método
Devolve um único método, em qualquer status, com os mesmos campos da listagem (sem vendor_name).
/api/v1/admin/shipping-methods/{id}AdminLê um método de envio
Parâmetros de caminho
iduuidobrigatórioId do método.
Exemplo de requisição
Resposta
200Método encontrado
Erros
| Status | Quando | Corpo |
|---|---|---|
| 401 | Sem token, token inválido ou expirado | {"error":"invalid or expired token"} |
| 403 | Usuário sem o privilégio view_shipping ou manage_shipping | {"error":"insufficient privileges","privilege_required_any":["manage_shipping","view_shipping"]} |
| 404 | O id não existe, ou não é um UUID válido (a rota não diferencia os dois casos) | {"error":"shipping method not found","detail":"shipping method not found: 00000000-0000-0000-0000-000000000000"} |
| 500 | Falha interna na listagem | {"error":"failed to list shipping methods","detail":"..."} |