API atual/Referência completa/Formas de envio

POSTCriar forma de envio

Cria uma forma de envio do seller, com preço fixo, por faixas ou por consulta à transportadora.

Use para oferecer uma nova opção de entrega aos clientes dos seus produtos. A forma nasce ativa (a menos que você mande status: "D"), pertence a você e passa a entrar nas cotações de frete na hora; o cache de cotações é limpo. Se o preço depende de peso, valor ou itens, crie as faixas em seguida em Faixas de preço.

POST/api/v1/vendor/shipping-methodsSeller

Cria uma forma de envio do seller

Corpo da requisição

namestringobrigatório

Nome mostrado ao cliente.

codestringobrigatório

Código único em toda a loja (não só entre as suas formas). Letras minúsculas, números e _ são o padrão. Não pode ser alterado depois. Códigos que começam com frenet_, intelipost_, simfrete_, via_ ou lets_ são cotados pelo agregador correspondente, se a loja o tiver ativo.

carrierstringpadrão: manual

Transportadora. Vazio vira manual.

carrier_service_codestring

Produto do contrato da transportadora. Para manual deixe vazio. Para correios com rate_calculation R é obrigatório: 5 dígitos, e os códigos de balcão 04014 e 04510 são recusados.

rate_calculationstringpadrão: M

MR

M manual ou R em tempo real.

descriptionstring

Texto livre.

delivery_timestring

Prazo em texto livre mostrado ao cliente.

statusstringpadrão: A

AD

A ativa ou D desativada. Vazio vira A. Também aceita active e disabled.

min_weightnumberpadrão: 0

Peso mínimo do carrinho em kg. 0 = sem mínimo.

max_weightnumberpadrão: 0

Peso máximo do carrinho em kg. 0 = sem máximo.

free_shipping_thresholdintegerpadrão: 0

Subtotal em centavos a partir do qual o frete é grátis. 0 = desligado.

flat_rateintegerpadrão: 0

Valor fixo do frete em centavos (1500 = R$ 15,00).

estimated_daysintegerpadrão: 0

Prazo em dias (campo antigo).

configobject

JSON livre. Em formas manuais, base_rate e per_kg_rate (centavos) calculam o frete por peso: base_rate + per_kg_rate x kg, arredondando os kg para cima.

service_paramsobject

JSON de parâmetros da transportadora.

free_shippingbooleanpadrão: false

true = frete sempre grátis. Com free_shipping_threshold maior que zero, a forma só aparece quando o carrinho atinge o limite.

is_address_requiredbooleanpadrão: false

Se o checkout deve pedir endereço de entrega.

rate_area_iduuid

Área de tarifa que limita onde a forma vale (veja Áreas de tarifa). Vazio = o país todo.

tax_idsstring

Ids de impostos separados por vírgula.

usergroup_idsstring

Grupos de clientes que enxergam a forma, ids separados por vírgula. Vazio = todos os clientes.

icon_urlstring

URL do ícone.

surchargeintegerpadrão: 0

Acréscimo fixo em centavos, somado ao frete calculado (não incide sobre frete grátis).

surcharge_percentintegerpadrão: 0

Acréscimo percentual em pontos-base (250 = 2,5%) sobre o frete calculado.

positionintegerpadrão: 0

Ordem de exibição; menor aparece primeiro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/shipping-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Motoboy centro",
    "code": "motoboy_centro",
    "carrier": "manual",
    "rate_calculation": "M",
    "delivery_time": "2 horas",
    "status": "A",
    "flat_rate": 1500,
    "free_shipping_threshold": 15000,
    "is_address_required": true,
    "rate_area_id": "7c2e4b9a-1d3f-4a5c-8b6e-0f9d8c7b6a54"
  }'

Resposta

201Forma criada

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",
  "shipping_id": "3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21",
  "shipping": "Motoboy centro",
  "module": "manual",
  "rate_str": "15.00",
  "company_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "timestamp": 1790864411,
  "updated_timestamp": 1790864411
}

Campos da resposta

(campos)object

A forma completa, com os mesmos campos de Listar e consultar.

Os campos company_id e use_for_all_vendors, se enviados, são ignorados: a forma sempre pertence a você e nunca vale para os outros sellers.

Erros

Status	Quando	Corpo de exemplo
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`name` vazio.	`{"error":"name is required"}`
400	`code` vazio.	`{"error":"code is required"}`
400	`carrier_service_code` recusado. O campo `reason` é `required`, `format`, `counter_code` ou `wrong_carrier`.	`{"error":"invalid_carrier_service_code","reason":"format","detail":"invalid carrier_service_code \"3220\": format"}`
401	Sem cabeçalho `Authorization`, ou token inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é um token de administrador).	`{"error":"insufficient permissions"}`
403	O seller não tem conta de vendedor vinculada ao usuário.	`{"error":"vendor_profile_required"}`
409	Já existe uma forma com esse `code` na loja.	`{"error":"code already exists","detail":"a shipping method with this code already exists"}`
500	Falha interna, ou valor que o banco recusou (por exemplo, um `status` desconhecido).	`{"error":"failed to create shipping method"}`

Veja também