VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Métodos de envio

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

GET/api/v1/admin/shipping-methodsAdmin

Lista os métodos de envio

Sem parâmetros de consulta. Exige view_shipping ou manage_shipping.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/shipping-methods" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Métodos retornados
json
{
  "methods": [
    {
      "id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "display_id": 71,
      "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
      "name": "Entrega Padrão",
      "code": "entrega_padrao",
      "carrier": "manual",
      "rate_calculation": "M",
      "delivery_time": "3-5 dias úteis",
      "status": "A",
      "min_weight": 0,
      "max_weight": 0,
      "free_shipping_threshold": 0,
      "flat_rate": 1500,
      "estimated_days": 0,
      "free_shipping": false,
      "is_address_required": false,
      "tax_ids": "",
      "usergroup_ids": "",
      "icon_url": "",
      "surcharge": 0,
      "surcharge_percent": 0,
      "use_for_all_vendors": true,
      "position": 0,
      "created_at": "2026-10-11T21:35:34.649864Z",
      "updated_at": "2026-10-11T21:35:34.649864Z",
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "shipping": "Entrega Padrão",
      "module": "manual",
      "rate_str": "15.00",
      "timestamp": 1791754534,
      "updated_timestamp": 1791754534,
      "vendor_name": "Loja Seller Teste",
      "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
    }
  ],
  "total": 1
}

Campos da resposta

methodsarray
Todos os métodos, sem ordem garantida (use position para ordenar na sua tela).
totalinteger
Quantidade de métodos devolvidos.
methods[].iduuid
Identificador do método (UUID).
methods[].display_idinteger
Número curto e sequencial para humanos ("método nº 53"). Não substitui o UUID em nenhuma rota.
methods[].tenant_iduuid
Loja dona do método.
methods[].namestring
Nome mostrado ao cliente no checkout.
methods[].codestring
Código único do método na loja.
methods[].carrierstring
Transportadora ou integração: manual (preço cadastrado por você) ou o código de uma integração, como correios.
methods[].carrier_service_codestring
Código do serviço no contrato da transportadora. Ausente quando não se aplica.
methods[].rate_calculationstring
MR
Como o preço é obtido: M manual (tabelas da loja) ou R em tempo real (consulta a transportadora).
methods[].descriptionstring
Texto livre. Ausente quando vazio.
methods[].delivery_timestring
Prazo em texto livre mostrado ao cliente, por exemplo 3-5 dias úteis.
methods[].statusstring
AD
A ativo ou D desativado. Só métodos ativos aparecem no checkout.
methods[].min_weightnumber
Peso mínimo do carrinho, em kg. 0 = sem mínimo.
methods[].max_weightnumber
Peso máximo do carrinho, em kg. 0 = sem máximo.
methods[].free_shipping_thresholdinteger
Descontinuado. Subtotal em centavos acima do qual o frete é grátis. Prefira políticas de frete ou faixas.
methods[].flat_rateinteger
Preço fixo em centavos (1500 = R$ 15,00), usado quando não há faixa que se aplique.
methods[].estimated_daysinteger
Descontinuado. Prazo em dias quando não há prazo por área. Veja Áreas do método.
methods[].configobject
JSON específico da integração (descontinuado). Ausente quando vazio.
methods[].service_paramsobject
Parâmetros da transportadora (dimensões padrão etc.). Ausente quando vazio.
methods[].free_shippingboolean
Se o método pode receber frete grátis de promoções.
methods[].is_address_requiredboolean
Se o método exige endereço de entrega (falso para retirada).
methods[].rate_area_iduuid
Descontinuado: área de tarifa única do método. Os vínculos atuais ficam em Áreas do método.
methods[].tax_idsstring
Ids de impostos separados por vírgula.
methods[].usergroup_idsstring
Ids de grupos de usuários separados por vírgula. Vazio = todos os clientes.
methods[].icon_urlstring
URL do ícone mostrado no checkout.
methods[].surchargeinteger
Descontinuado. Acréscimo fixo em centavos.
methods[].surcharge_percentinteger
Descontinuado. Acréscimo percentual.
methods[].use_for_all_vendorsboolean
Se um método da loja (sem company_id) vale para o carrinho de todos os sellers.
methods[].company_iduuid
Seller (lojista) dono do método. Ausente = método da loja inteira.
methods[].vendor_namestring
Nome do seller dono. Só aparece na listagem.
methods[].positioninteger
Ordem de exibição no checkout (menor primeiro).
methods[].created_atstring
Criação, RFC 3339 em UTC.
methods[].updated_atstring
Última alteração, RFC 3339 em UTC.
methods[].shipping_iduuid
Alias 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).

GET/api/v1/admin/shipping-methods/{id}Admin

Lê um método de envio

Parâmetros de caminho

iduuidobrigatório
Id do método.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Método encontrado
json
{
  "id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "display_id": 71,
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "name": "Entrega Padrão",
  "code": "entrega_padrao",
  "carrier": "manual",
  "rate_calculation": "M",
  "delivery_time": "3-5 dias úteis",
  "status": "A",
  "min_weight": 0,
  "max_weight": 0,
  "free_shipping_threshold": 0,
  "flat_rate": 1500,
  "estimated_days": 0,
  "free_shipping": false,
  "is_address_required": false,
  "tax_ids": "",
  "usergroup_ids": "",
  "icon_url": "",
  "surcharge": 0,
  "surcharge_percent": 0,
  "use_for_all_vendors": true,
  "position": 0,
  "created_at": "2026-10-11T21:35:34.649864Z",
  "updated_at": "2026-10-11T21:35:34.649864Z",
  "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "shipping": "Entrega Padrão",
  "module": "manual",
  "rate_str": "15.00",
  "timestamp": 1791754534,
  "updated_timestamp": 1791754534
}

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Usuário sem o privilégio view_shipping ou manage_shipping{"error":"insufficient privileges","privilege_required_any":["manage_shipping","view_shipping"]}
404O 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"}
500Falha interna na listagem{"error":"failed to list shipping methods","detail":"..."}
Como achar um método sem saber o id

Não há filtro na listagem. Leia tudo uma vez e procure pelo code, que é único na loja e estável entre ambientes. Guarde o id do resultado para as demais rotas.

Campos repetidos

shipping_id, shipping, module, rate_str, timestamp e updated_timestamp repetem dados já presentes em outros campos, em outro formato (preço como string decimal, datas Unix). Em código novo, ignore-os.

Veja também

  • Criar um método
  • Alterar um método
  • Faixas de preço
Anterior
Métodos de envio
Próxima
Criar método de envio
Nesta página
  • Listar métodos
  • Exemplo de requisição
  • Resposta
  • Consultar um método
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também