API legada/Referência completa/Métodos de frete

Rotas de métodos de frete

Lista, consulta, cria, altera e remove métodos de frete (formas de entrega) da loja.

Estas rotas leem e mantêm o cadastro de métodos de frete. Use-as quando um sistema externo precisa espelhar as formas de entrega da loja ou criá-las em lote. Todas exigem um usuário administrador.

GET/api/v1.0/shippingsAdmin

Listar os métodos de frete

Devolve os métodos da loja em páginas.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso vale 10.

GET/api/v1.0/shippings/{id}Admin

Consultar um método de frete

Devolve um método pelo id.

Parâmetros de caminho

idstringobrigatório

Id do método (UUID).

POST/api/v1.0/shippingsAdmin

Criar um método de frete

Cria um método e responde 201 com o id. O método nasce ativo, a menos que você mande outro status.

Corpo da requisição

shippingstringobrigatório

Nome do método.

statusstringpadrão: A

AD

A ativo. Qualquer outro valor cria o método desativado.

carrierstring

Transportadora ou módulo (correios, manual...).

delivery_timestring

Prazo em texto livre (2-3 dias úteis).

min_weightnumber

Peso mínimo atendido. 0 sem limite.

max_weightnumber

Peso máximo atendido. 0 sem limite.

ratesobject

Tabela de preços, objeto livre.

service_paramsobject

Parâmetros do serviço da transportadora, objeto livre.

PUT/api/v1.0/shippings/{id}Admin

Alterar um método de frete

Altera só o que você enviar e responde 200 com o id. Texto vazio e pesos iguais a 0 contam como "não enviado".

Parâmetros de caminho

idstringobrigatório

Id do método.

Corpo da requisição

shippingstring

Novo nome.

statusstring

AD

A ativa; qualquer outro valor desativa.

carrierstring

Transportadora.

delivery_timestring

Prazo.

min_weightnumber

Peso mínimo (só vale acima de 0).

max_weightnumber

Peso máximo (só vale acima de 0).

ratesobject

Tabela de preços.

service_paramsobject

Parâmetros do serviço.

DELETE/api/v1.0/shippings/{id}Admin

Remover um método de frete

Remove o método e responde 204 sem corpo.

Parâmetros de caminho

idstringobrigatório

Id do método.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/shippings" \
  -H "Content-Type: application/json" \
  -d '{"shipping":"Motoboy","status":"A","carrier":"manual","delivery_time":"30 min"}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/shippings?items_per_page=10"

Resposta

200Lista de métodos de frete

json

{
  "params": { "page": 1, "items_per_page": 10, "total_items": 1 },
  "shippings": [
    {
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "description": "",
      "status": "A",
      "company_id": "",
      "delivery_time": "30 min",
      "carrier": "manual",
      "min_weight": 0,
      "max_weight": 0,
      "position": 0,
      "rates": {},
      "service_params": {},
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "is_address_required": "N",
      "localization": "",
      "rate_calc_type": "",
      "service_id": "",
      "module": "manual"
    }
  ]
}

201Método criado

json

{ "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb" }

Campos da resposta

shipping_idstring

Id do método (UUID).

shippingstring

Nome.

descriptionstring

Descrição; vazia quando não há.

statusstring

AD

A ativo, D desativado.

company_idstring

Id do seller dono do método; vazio quando é da loja.

delivery_timestring

Prazo em texto.

carrierstring

Transportadora ou módulo.

min_weightnumber

Peso mínimo.

max_weightnumber

Peso máximo.

positioninteger

Ordem de exibição.

ratesobject

Tabela de preços, como gravada.

service_paramsobject

Parâmetros do serviço, como gravados.

a_surchargenumber

Sobretaxa fixa em decimal da moeda da loja (2.5 = R$ 2,50).

p_surchargenumber

Sobretaxa percentual (10 = 10%).

tax_idsstring

Ids de impostos separados por vírgula; vazio quando não há.

usergroup_idsstring

Ids de grupos de usuários que enxergam o método, separados por vírgula; vazio para todos.

is_address_requiredstring

YN

Y quando o método exige endereço de entrega.

localizationstring

Sempre vazio.

rate_calc_typestring

Sempre vazio.

service_idstring

Sempre vazio.

modulestring

Igual a carrier.

paramsobject

page, items_per_page e total_items (total de métodos da loja).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
400	Falta `shipping` na criação	`{"message":"shipping name is required","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Método inexistente	`{"message":"shipping method not found","status":404}`

Veja também

Rotas de métodos de frete

Lista, consulta, cria, altera e remove métodos de frete (formas de entrega) da loja.

GET/api/v1.0/shippingsAdmin

Listar os métodos de frete

Devolve os métodos da loja em páginas.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor inválido ou menor que 1 é ignorado.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 250. Fora disso vale 10.

GET/api/v1.0/shippings/{id}Admin

Consultar um método de frete

Devolve um método pelo id.

Parâmetros de caminho

idstringobrigatório

Id do método (UUID).

POST/api/v1.0/shippingsAdmin

Criar um método de frete

Cria um método e responde 201 com o id. O método nasce ativo, a menos que você mande outro status.

Corpo da requisição

shippingstringobrigatório

Nome do método.

statusstringpadrão: A

AD

A ativo. Qualquer outro valor cria o método desativado.

carrierstring

Transportadora ou módulo (correios, manual...).

delivery_timestring

Prazo em texto livre (2-3 dias úteis).

min_weightnumber

Peso mínimo atendido. 0 sem limite.

max_weightnumber

Peso máximo atendido. 0 sem limite.

ratesobject

Tabela de preços, objeto livre.

service_paramsobject

Parâmetros do serviço da transportadora, objeto livre.

PUT/api/v1.0/shippings/{id}Admin

Alterar um método de frete

Altera só o que você enviar e responde 200 com o id. Texto vazio e pesos iguais a 0 contam como "não enviado".

Parâmetros de caminho

idstringobrigatório

Id do método.

Corpo da requisição

shippingstring

Novo nome.

statusstring

AD

A ativa; qualquer outro valor desativa.

carrierstring

Transportadora.

delivery_timestring

Prazo.

min_weightnumber

Peso mínimo (só vale acima de 0).

max_weightnumber

Peso máximo (só vale acima de 0).

ratesobject

Tabela de preços.

service_paramsobject

Parâmetros do serviço.

DELETE/api/v1.0/shippings/{id}Admin

Remover um método de frete

Remove o método e responde 204 sem corpo.

Parâmetros de caminho

idstringobrigatório

Id do método.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/shippings" \
  -H "Content-Type: application/json" \
  -d '{"shipping":"Motoboy","status":"A","carrier":"manual","delivery_time":"30 min"}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/shippings?items_per_page=10"

Resposta

200Lista de métodos de frete

json

{
  "params": { "page": 1, "items_per_page": 10, "total_items": 1 },
  "shippings": [
    {
      "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb",
      "shipping": "Motoboy",
      "description": "",
      "status": "A",
      "company_id": "",
      "delivery_time": "30 min",
      "carrier": "manual",
      "min_weight": 0,
      "max_weight": 0,
      "position": 0,
      "rates": {},
      "service_params": {},
      "a_surcharge": 0,
      "p_surcharge": 0,
      "tax_ids": "",
      "usergroup_ids": "",
      "is_address_required": "N",
      "localization": "",
      "rate_calc_type": "",
      "service_id": "",
      "module": "manual"
    }
  ]
}

201Método criado

json

{ "shipping_id": "85e87a54-dcee-4947-8cfa-f6406f2f3cbb" }

Campos da resposta

shipping_idstring

Id do método (UUID).

shippingstring

Nome.

descriptionstring

Descrição; vazia quando não há.

statusstring

AD

A ativo, D desativado.

company_idstring

Id do seller dono do método; vazio quando é da loja.

delivery_timestring

Prazo em texto.

carrierstring

Transportadora ou módulo.

min_weightnumber

Peso mínimo.

max_weightnumber

Peso máximo.

positioninteger

Ordem de exibição.

ratesobject

Tabela de preços, como gravada.

service_paramsobject

Parâmetros do serviço, como gravados.

a_surchargenumber

Sobretaxa fixa em decimal da moeda da loja (2.5 = R$ 2,50).

p_surchargenumber

Sobretaxa percentual (10 = 10%).

tax_idsstring

Ids de impostos separados por vírgula; vazio quando não há.

usergroup_idsstring

Ids de grupos de usuários que enxergam o método, separados por vírgula; vazio para todos.

is_address_requiredstring

YN

Y quando o método exige endereço de entrega.

localizationstring

Sempre vazio.

rate_calc_typestring

Sempre vazio.

service_idstring

Sempre vazio.

modulestring

Igual a carrier.

paramsobject

page, items_per_page e total_items (total de métodos da loja).

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"invalid request body","status":400}`
400	Falta `shipping` na criação	`{"message":"shipping name is required","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Método inexistente	`{"message":"shipping method not found","status":404}`