API atual/Referência completa/Métodos de envio

Criar método de envio

Cadastra uma nova opção de entrega para o checkout, com preço fixo, tabela de faixas ou cotação de uma transportadora.

Crie um método quando a loja passa a oferecer uma nova forma de entrega. O mínimo é name e code. Com isso o método nasce ativo, manual, válido para todos os sellers e com preço zero: adicione o preço (flat_rate ou faixas) e os prazos por área em seguida. A resposta devolve o método completo, com o id que as demais rotas pedem.

Criar não dispara e-mails nem eventos externos, mas invalida o cache de cotações: o método passa a valer nas próximas cotações do checkout.

POST/api/v1/admin/shipping-methodsAdmin

Cria um método de envio

Exige manage_shipping.

Corpo da requisição

namestringobrigatório

Nome mostrado ao cliente.

codestringobrigatório

Código único na loja. Repetir devolve 409.

carrierstringpadrão: manual

manual (padrão) ou o código da integração de transportadora.

carrier_service_codestring

Código do serviço no contrato da transportadora. É validado: veja o erro invalid_carrier_service_code.

rate_calculationstringpadrão: M

MR

M manual ou R em tempo real.

descriptionstring

Texto livre.

delivery_timestring

Prazo em texto livre, por exemplo 3-5 dias úteis.

statusstring

AD

A ou D (também aceita active e disabled). Vazio = A.

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.

flat_rateinteger

Preço fixo em centavos.

free_shipping_thresholdinteger

Descontinuado: subtotal em centavos para frete grátis.

estimated_daysinteger

Descontinuado: prazo em dias.

free_shippingboolean

Se o método pode receber frete grátis de promoções.

is_address_requiredboolean

Se exige endereço de entrega. Use false para retirada.

rate_area_iduuid

Descontinuado: área de tarifa única. Prefira os vínculos em /areas.

tax_idsstring

Ids de impostos separados por vírgula.

usergroup_idsstring

Ids de grupos de usuários separados por vírgula. Vazio = todos.

icon_urlstring

URL do ícone do checkout.

surchargeinteger

Descontinuado: acréscimo fixo em centavos.

surcharge_percentinteger

Descontinuado: acréscimo percentual.

use_for_all_vendorsbooleanpadrão: true

Vale para o carrinho de todos os sellers (apenas métodos sem company_id).

company_iduuid

Seller dono do método. Omita para um método da loja.

positioninteger

Ordem de exibição no checkout.

configobject

JSON específico da integração (descontinuado).

service_paramsobject

Parâmetros da transportadora.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Entrega Padrão",
    "code": "entrega_padrao",
    "flat_rate": 1500,
    "delivery_time": "3-5 dias úteis",
    "min_weight": 0,
    "max_weight": 30
  }'

Resposta

201Método criado

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
}

Os campos da resposta são os mesmos de Listar e consultar.

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` ou `code` vazio	`{"error":"name is required"}` / `{"error":"code is required"}`
400	`carrier_service_code` recusado. `reason` é `required`, `format`, `counter_code` ou `wrong_carrier`	`{"error":"invalid_carrier_service_code","reason":"format","detail":"invalid carrier_service_code \"abc\": format"}`
409	Já existe um método com esse `code` na loja	`{"error":"code already exists","detail":"a shipping method with this code already exists"}`
500	Falha ao gravar (por exemplo `status` com valor desconhecido, ou `rate_area_id` que não existe)	`{"error":"failed to create shipping method","detail":"..."}`

Veja também