API atual/Referência completa/Formas de envio

Alterar e apagar forma

Altera parcialmente uma forma de envio do seller ou a apaga de vez.

Alterar uma forma

A alteração é parcial: só os campos enviados mudam. O code não pode ser alterado. Devolve a forma já atualizada e limpa o cache de cotações.

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

Altera uma forma de envio do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Corpo da requisição

namestring

Nome mostrado ao cliente.

carrierstring

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_calculationstring

MR

M manual ou R em tempo real.

descriptionstring

Texto livre.

delivery_timestring

Prazo em texto livre mostrado ao cliente.

statusstring

AD

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

min_weightnumber

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

max_weightnumber

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

free_shipping_thresholdinteger

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

flat_rateinteger

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

estimated_daysinteger

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_shippingboolean

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

is_address_requiredboolean

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.

surchargeinteger

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

surcharge_percentinteger

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

positioninteger

Ordem de exibição; menor aparece primeiro.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flat_rate": 1800,
    "delivery_time": "1 a 2 horas"
  }'

Resposta: alterar

200Forma atualizada

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": "1 a 2 horas",
  "status": "A",
  "min_weight": 0,
  "max_weight": 0,
  "free_shipping_threshold": 15000,
  "flat_rate": 1800,
  "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": "18.00",
  "company_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "timestamp": 1790864411,
  "updated_timestamp": 1790864411
}

Campos da resposta

(campos)object

A forma completa, igual a Consultar uma forma.

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: alterar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`carrier_service_code` ou combinação de transportadora recusada (mesmo corpo da criação).	`{"error":"invalid_carrier_service_code","reason":"wrong_carrier","detail":"..."}`
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	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha interna, ou valor que o banco recusou (por exemplo, um `status` desconhecido).	`{"error":"failed to update shipping method"}`

Remove a forma e suas faixas de preço. A exclusão é definitiva e não há lixeira. Pedidos antigos continuam mostrando o nome da forma que escolheram. Se a forma foi gerada por uma área de tarifa, ela volta a ser criada na próxima vez que a área for salva com tarifa.

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

Apaga uma forma de envio do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Exemplo de requisição: apagar

bash

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

Resposta: apagar

200Forma apagada

json

{
  "message": "shipping method deleted"
}

Campos da resposta

messagestring

Texto fixo de confirmação (em inglês).

Erros: apagar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
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	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha ao apagar.	`{"error":"failed to delete shipping method"}`

Veja também

API atual/Referência completa/Formas de envio

Alterar e apagar forma

Altera parcialmente uma forma de envio do seller ou a apaga de vez.

Alterar uma forma

A alteração é parcial: só os campos enviados mudam. O code não pode ser alterado. Devolve a forma já atualizada e limpa o cache de cotações.

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

Altera uma forma de envio do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Corpo da requisição

namestring

Nome mostrado ao cliente.

carrierstring

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_calculationstring

MR

M manual ou R em tempo real.

descriptionstring

Texto livre.

delivery_timestring

Prazo em texto livre mostrado ao cliente.

statusstring

AD

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

min_weightnumber

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

max_weightnumber

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

free_shipping_thresholdinteger

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

flat_rateinteger

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

estimated_daysinteger

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_shippingboolean

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

is_address_requiredboolean

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.

surchargeinteger

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

surcharge_percentinteger

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

positioninteger

Ordem de exibição; menor aparece primeiro.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/shipping-methods/3a7d9e10-2b4c-4f6a-9c1d-5e8f7a6b4c21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flat_rate": 1800,
    "delivery_time": "1 a 2 horas"
  }'

Resposta: alterar

200Forma atualizada

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": "1 a 2 horas",
  "status": "A",
  "min_weight": 0,
  "max_weight": 0,
  "free_shipping_threshold": 15000,
  "flat_rate": 1800,
  "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": "18.00",
  "company_id": "5f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "timestamp": 1790864411,
  "updated_timestamp": 1790864411
}

Campos da resposta

(campos)object

A forma completa, igual a Consultar uma forma.

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: alterar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`
400	`carrier_service_code` ou combinação de transportadora recusada (mesmo corpo da criação).	`{"error":"invalid_carrier_service_code","reason":"wrong_carrier","detail":"..."}`
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	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha interna, ou valor que o banco recusou (por exemplo, um `status` desconhecido).	`{"error":"failed to update shipping method"}`

Apagar uma forma

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

Apaga uma forma de envio do seller

Parâmetros de caminho

iduuidobrigatório

Id da forma de envio.

Exemplo de requisição: apagar

bash

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

Resposta: apagar

200Forma apagada

json

{
  "message": "shipping method deleted"
}

Campos da resposta

messagestring

Texto fixo de confirmação (em inglês).

Erros: apagar

Status	Quando	Corpo de exemplo
400	O `id` não é um UUID válido.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
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	A forma existe, mas pertence a outro seller ou à loja inteira.	`{"error":"forbidden","detail":"shipping method does not belong to this vendor"}`
404	Não existe forma com esse id.	`{"error":"shipping method not found"}`
500	Falha ao apagar.	`{"error":"failed to delete shipping method"}`