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

Listar e consultar formas

Lista as formas de envio do seller ou devolve uma delas pelo id.

Listar formas

Devolve todas as formas do seller, ativas e desativadas, sem paginação. Inclui as formas geradas automaticamente por áreas de tarifa (código rate_area_ + id). Formas da loja inteira não aparecem aqui.

GET/api/v1/vendor/shipping-methodsSeller

Lista as formas de envio do seller

Exemplo de requisição: listar

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

Resposta: listar

200Lista de formas
json
{
  "methods": [
    {
      "id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
      "display_id": 53,
      "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
      "name": "Motoboy centro",
      "code": "motoboy_centro",
      "carrier": "manual",
      "rate_calculation": "M",
      "delivery_time": "2 horas",
      "status": "A",
      "min_weight": 0,
      "max_weight": 0,
      "free_shipping_threshold": 15000,
      "flat_rate": 1500,
      "estimated_days": 0,
      "free_shipping": false,
      "is_address_required": true,
      "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
      "tax_ids": "",
      "usergroup_ids": "",
      "icon_url": "",
      "surcharge": 0,
      "surcharge_percent": 0,
      "use_for_all_vendors": false,
      "position": 0,
      "created_at": "2026-10-01T14:20:11Z",
      "updated_at": "2026-10-01T14:20:11Z",
      "company_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
    }
  ],
  "total": 1
}

Campos da resposta

methodsarray

Formas do seller (campos abaixo).

iduuid
Identificador da forma de envio.
display_idinteger
Número curto e sequencial, para citar a forma ao telefone ("forma 53"). O UUID continua sendo a chave.
tenant_iduuid
Loja dona do registro.
namestring
Nome mostrado ao cliente no checkout.
codestring
Código único na loja. Não muda depois de criado.
carrierstring
Transportadora ou integração (manual, correios e outras).
carrier_service_codestring
Produto do contrato da transportadora (ex.: 03220). Ausente quando vazio.
rate_calculationstring
M manual (valor fixo ou faixas) ou R em tempo real (consulta a transportadora).
descriptionstring
Texto livre. Ausente quando vazio.
delivery_timestring
Prazo em texto livre, mostrado ao cliente (ex.: 2 horas, 3-5 dias úteis).
statusstring
A ativa ou D desativada.
min_weightnumber
Peso mínimo do carrinho, em kg, para a forma ser oferecida. 0 = sem mínimo.
max_weightnumber
Peso máximo do carrinho, em kg. 0 = sem máximo.
free_shipping_thresholdinteger
Subtotal do carrinho, em centavos, a partir do qual o frete é grátis. 0 = desligado.
flat_rateinteger
Valor fixo do frete, em centavos, usado quando não há faixa que se aplique.
estimated_daysinteger
Prazo em dias, campo antigo. Use delivery_time para o texto.
configobject
JSON livre. Em formas manuais pode ter base_rate e per_kg_rate (centavos). Ausente quando vazio.
service_paramsobject
JSON de parâmetros da transportadora. Ausente quando vazio.
free_shippingboolean
true = frete sempre grátis (ou grátis acima do limite, se free_shipping_threshold > 0).
is_address_requiredboolean
Se o checkout deve pedir endereço de entrega para esta forma.
rate_area_iduuid | null
Área de tarifa que limita onde a forma vale. Ausente = o país todo.
tax_idsstring
Ids de impostos, separados por vírgula.
usergroup_idsstring
Grupos de clientes que enxergam a forma, separados por vírgula. Vazio = todos.
icon_urlstring
URL do ícone da forma.
surchargeinteger
Acréscimo fixo, em centavos, somado ao frete calculado.
surcharge_percentinteger
Acréscimo percentual em pontos-base (100 = 1%), somado ao frete calculado.
use_for_all_vendorsboolean
Sempre false para formas de seller.
company_iduuid
Id do seller dono (o seu).
positioninteger
Ordem de exibição; menor aparece primeiro.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Quantidade de formas devolvidas.

Erros: listar

StatusQuandoCorpo de exemplo
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403O seller não tem conta de vendedor vinculada ao usuário.{"error":"vendor_profile_required"}
Sem filtros nem páginas

A rota devolve tudo de uma vez. Para achar uma forma, filtre no cliente por code ou status. Para listar só as ativas, use status == "A".

Consultar uma forma

Devolve os dados completos de uma forma sua. O corpo é a própria forma, sem envelope.

GET/api/v1/vendor/shipping-methods/{id}Seller

Mostra uma forma de envio

Parâmetros de caminho

iduuidobrigatório
Id da forma de envio.

Exemplo de requisição: consultar

bash
curl "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21" \
  -H "Authorization: Bearer $TOKEN"

Resposta: consultar

200Forma encontrada
json
{
  "id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
  "display_id": 53,
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "name": "Motoboy centro",
  "code": "motoboy_centro",
  "carrier": "manual",
  "rate_calculation": "M",
  "delivery_time": "2 horas",
  "status": "A",
  "min_weight": 0,
  "max_weight": 0,
  "free_shipping_threshold": 15000,
  "flat_rate": 1500,
  "estimated_days": 0,
  "free_shipping": false,
  "is_address_required": true,
  "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54",
  "tax_ids": "",
  "usergroup_ids": "",
  "icon_url": "",
  "surcharge": 0,
  "surcharge_percent": 0,
  "use_for_all_vendors": false,
  "position": 0,
  "created_at": "2026-10-01T14:20:11Z",
  "updated_at": "2026-10-01T14:20:11Z",
  "company_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}

Campos da resposta

(campos)object
Os mesmos campos de cada item de methods acima.

Erros: consultar

StatusQuandoCorpo de exemplo
400O id não é um UUID válido.{"error":"invalid id","detail":"id must be a valid UUID"}
401Sem cabeçalho Authorization, ou token inválido ou expirado.{"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é um token de administrador).{"error":"insufficient permissions"}
403A forma existe, mas pertence a outro seller ou à loja inteira.{"error":"forbidden","detail":"shipping method does not belong to this vendor"}
404Não existe forma com esse id.{"error":"shipping method not found"}
403 em vez de 404

Um id que existe mas é de outro seller (ou da loja inteira) responde 403. Só um id inexistente responde 404.

Veja também

  • Criar forma de envio
  • Faixas de preço
  • Visão geral
Anterior
Formas de envio do seller
Próxima
Criar forma de envio
Nesta página
  • Listar formas
  • Exemplo de requisição: listar
  • Resposta: listar
  • Erros: listar
  • Consultar uma forma
  • Exemplo de requisição: consultar
  • Resposta: consultar
  • Erros: consultar
  • Veja também