API atual/Referência completa/Frete: áreas e retirada

Áreas de tarifa

Lista, consulta, cria, altera e exclui as áreas geográficas que decidem quais regras de frete e imposto valem para um endereço.

Uma área de tarifa (rate area) é uma região, por exemplo "Grande São Paulo" ou "Norte". Métodos de envio e regras de imposto apontam para uma área e só valem para endereços dentro dela. Estas cinco operações mantêm as áreas da loja; as áreas criadas por sellers não aparecem aqui. Ler exige view_shipping ou manage_shipping; criar, alterar e excluir exigem manage_shipping.

Listar áreas

Devolve as áreas da loja, sem paginação. Por padrão só as ativas.

GET/api/v1/admin/rate-areasAdmin

Lista as áreas de tarifa da loja

Parâmetros de consulta

typestring

shippingtax

Filtra pelo uso da área: frete ou imposto.

statusstringpadrão: A

ADactivedisabledall

Estado. Padrão: só as ativas. all traz todas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/rate-areas?type=shipping" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Áreas retornadas

json

{
  "rate_areas": [
    {
      "id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "name": "Norte",
      "description": "Região Norte (7 estados)",
      "type": "shipping",
      "status": "A",
      "min_order_amount": 0,
      "shipping_rate_amount": 0,
      "zip_codes": "",
      "cities": "",
      "addresses": "",
      "zones": [
        { "id": "258257fb-0790-49d9-b981-6acae95891af", "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e", "country_code": "BR", "state_code": "AC", "cep_from": "", "cep_to": "", "min_order_amount": 0 }
      ],
      "created_at": "2026-04-26T20:00:47.422644Z",
      "updated_at": "2026-04-26T20:00:47.422644Z"
    }
  ],
  "total": 1
}

Campos da resposta

rate_areasarray

Áreas. Vazio ([]) quando nenhuma casa.

totalinteger

Quantidade devolvida.

rate_areas[].iduuid

Id da área.

rate_areas[].namestring

Nome.

rate_areas[].descriptionstring

Descrição.

rate_areas[].typestring

shippingtax

Uso: frete ou imposto.

rate_areas[].statusstring

AD

A ativa, D desativada. Uma área desativada não casa com nenhum endereço.

rate_areas[].min_order_amountinteger

Valor mínimo do pedido para a área valer, em centavos. 0 = sem mínimo.

rate_areas[].shipping_rate_amountinteger

Tarifa fixa de frete da área, em centavos. Veja o aviso abaixo.

rate_areas[].zip_codesstring

Padrões de CEP, um por linha.

rate_areas[].citiesstring

Texto livre guardado (não entra no cálculo).

rate_areas[].addressesstring

Texto livre guardado (não entra no cálculo).

rate_areas[].zonesarray

Zonas da área (estado, cidade, bairro, faixa de CEP). Ausente quando não há.

rate_areas[].zones[].country_codestring

País (BR).

rate_areas[].zones[].state_codestring

Sigla do estado. Pode ser vazio.

rate_areas[].zones[].city_iduuid

Cidade do catálogo de localidades. Ausente se não houver.

rate_areas[].zones[].district_iduuid

Bairro do catálogo de localidades. Ausente se não houver.

rate_areas[].zones[].cep_fromstring

Início da faixa de CEP, 8 dígitos. Vazio se a zona não é por faixa.

rate_areas[].zones[].cep_tostring

Fim da faixa de CEP, 8 dígitos.

rate_areas[].zones[].min_order_amountinteger

Mínimo da zona, em centavos.

rate_areas[].geofencesarray

Desenho no mapa (polígonos ou círculos), quando o módulo de geocerca está em uso. Ausente se não houver.

rate_areas[].created_atstring

Criação, RFC 3339 em UTC.

rate_areas[].updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token ou sem privilégio	`{"error":"insufficient privileges", ...}`
500	Falha interna	`{"error":"failed to list rate areas","detail":"..."}`

Consultar uma área

Devolve uma área, incluindo as zonas. Funciona para áreas ativas e desativadas.

GET/api/v1/admin/rate-areas/{id}Admin

Detalha uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/rate-areas/7bce1201-0e92-49d1-8e25-846f35fa697e" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Área retornada

json

{
  "id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "name": "Norte",
  "description": "Região Norte (7 estados)",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 0,
  "shipping_rate_amount": 0,
  "zip_codes": "",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "258257fb-0790-49d9-b981-6acae95891af", "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e", "country_code": "BR", "state_code": "AC", "cep_from": "", "cep_to": "", "min_order_amount": 0 }
  ],
  "created_at": "2026-04-26T20:00:47.422644Z",
  "updated_at": "2026-04-26T20:00:47.422644Z"
}

Os campos são os da lista.

Erros

Status	Quando	Corpo
404	Área inexistente	`{"error":"rate area not found"}`
500	`id` que não é UUID	`{"error":"failed to get rate area","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Criar uma área

Cria uma área da loja, com zonas opcionais. Tudo é gravado numa única transação: uma zona inválida desfaz a criação inteira.

POST/api/v1/admin/rate-areasAdmin

Cria uma área de tarifa

Corpo da requisição

namestringobrigatório

Nome da área.

descriptionstring

Descrição.

typestringpadrão: shipping

shippingtax

Uso da área.

statusstringpadrão: A

ADactivedisabled

Estado inicial.

min_order_amountintegerpadrão: 0

Pedido mínimo da área, em centavos.

shipping_rate_amountintegerpadrão: 0

Tarifa fixa de frete, em centavos. Veja o aviso abaixo.

zip_codesstringpadrão:

Padrões de CEP: texto com um por linha, ou lista JSON de textos.

citiesstring

Texto livre (lista JSON ou linhas). Guardado, sem efeito no cálculo.

addressesstring

Texto livre (lista JSON ou linhas). Guardado, sem efeito no cálculo.

zonesarray

Zonas da área.

country_codestring

País (BR).

state_codestring

Sigla do estado.

city_iduuid

Cidade do catálogo de localidades.

district_iduuid

Bairro do catálogo de localidades.

cep_fromstring

Início da faixa de CEP, 8 dígitos, com ou sem hífen. Obrigatório junto com cep_to.

cep_tostring

Fim da faixa de CEP. Não pode ser menor que cep_from.

min_order_amountinteger

Pedido mínimo da zona, em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/rate-areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Capital SP",
    "description": "CEPs da capital",
    "type": "shipping",
    "min_order_amount": 5000,
    "zip_codes": ["01*", "02*"],
    "zones": [
      { "country_code": "BR", "state_code": "SP", "cep_from": "01000-000", "cep_to": "05999-999" }
    ]
  }'

Resposta

201Área criada

json

{
  "id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1",
  "name": "Capital SP",
  "description": "CEPs da capital",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 5000,
  "shipping_rate_amount": 0,
  "zip_codes": "01*\n02*",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "e40781e9-bfd1-409b-aa20-699429561083", "rate_area_id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1", "country_code": "BR", "state_code": "SP", "cep_from": "01000000", "cep_to": "05999999", "min_order_amount": 0 }
  ],
  "created_at": "2026-10-11T21:26:41.81573Z",
  "updated_at": "2026-10-11T21:26:41.81573Z"
}

Note que os CEPs voltam só com dígitos (01000000) e zip_codes volta como texto com quebra de linha.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
400	Faixa de CEP incompleta, com formato inválido ou com `cep_from` maior que `cep_to`	`{"error":"invalid CEP range: both cep_from and cep_to must be provided"}`
400	Qualquer outra falha ao gravar (nesta rota, até falhas internas voltam como 400)	`{"error":"insert rate area: ..."}`

Alterar uma área

Atualização parcial: só os campos enviados mudam. Atenção a zones: se enviada, substitui todas as zonas existentes; se omitida, elas ficam como estão.

PUT/api/v1/admin/rate-areas/{id}Admin

Altera uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

typestring

shippingtax

Novo uso.

statusstring

ADactivedisabled

Novo estado.

min_order_amountinteger

Novo pedido mínimo, em centavos.

shipping_rate_amountinteger

Nova tarifa fixa, em centavos.

zip_codesstring

Novos padrões de CEP (texto ou lista JSON). Substitui os anteriores.

citiesstring

Novo texto livre.

addressesstring

Novo texto livre.

zonesarray

Novas zonas, com os mesmos campos da criação. Substitui todas as existentes.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/rate-areas/7fd8c24b-f48f-47fc-9bb5-6352737d27f1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "CEPs da capital e Grande SP", "min_order_amount": 8000}'

Resposta

200Área alterada

json

{
  "id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1",
  "name": "Capital SP",
  "description": "CEPs da capital e Grande SP",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 8000,
  "shipping_rate_amount": 0,
  "zip_codes": "01*\n02*",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "e40781e9-bfd1-409b-aa20-699429561083", "rate_area_id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1", "country_code": "BR", "state_code": "SP", "cep_from": "01000000", "cep_to": "05999999", "min_order_amount": 0 }
  ],
  "created_at": "2026-10-11T21:26:41.81573Z",
  "updated_at": "2026-10-11T21:40:00.000Z"
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Zona com faixa de CEP inválida	`{"error":"invalid CEP range: cep_from must be <= cep_to"}`
404	Área inexistente	`{"error":"rate area not found"}`
500	`id` que não é UUID, ou outra falha ao gravar	`{"error":"failed to update rate area","detail":"..."}`

Excluir uma área

Remove a área e suas zonas, e o método de envio que a própria área criou (se houver). Métodos de envio e regras que apenas referenciam a área continuam existindo, mas deixam de casar com qualquer endereço. Não há lixeira.

DELETE/api/v1/admin/rate-areas/{id}Admin

Exclui uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/rate-areas/7fd8c24b-f48f-47fc-9bb5-6352737d27f1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Área excluída

json

{ "message": "rate area deleted" }

Erros

Status	Quando	Corpo
500	Área inexistente (deveria ser 404) ou `id` que não é UUID	`{"error":"failed to delete rate area","detail":"rate area 7fd8c24b-... not found"}`

Veja também

API atual/Referência completa/Frete: áreas e retirada

Áreas de tarifa

Lista, consulta, cria, altera e exclui as áreas geográficas que decidem quais regras de frete e imposto valem para um endereço.

Listar áreas

Devolve as áreas da loja, sem paginação. Por padrão só as ativas.

GET/api/v1/admin/rate-areasAdmin

Lista as áreas de tarifa da loja

Parâmetros de consulta

typestring

shippingtax

Filtra pelo uso da área: frete ou imposto.

statusstringpadrão: A

ADactivedisabledall

Estado. Padrão: só as ativas. all traz todas.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/rate-areas?type=shipping" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Áreas retornadas

json

{
  "rate_areas": [
    {
      "id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "name": "Norte",
      "description": "Região Norte (7 estados)",
      "type": "shipping",
      "status": "A",
      "min_order_amount": 0,
      "shipping_rate_amount": 0,
      "zip_codes": "",
      "cities": "",
      "addresses": "",
      "zones": [
        { "id": "258257fb-0790-49d9-b981-6acae95891af", "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e", "country_code": "BR", "state_code": "AC", "cep_from": "", "cep_to": "", "min_order_amount": 0 }
      ],
      "created_at": "2026-04-26T20:00:47.422644Z",
      "updated_at": "2026-04-26T20:00:47.422644Z"
    }
  ],
  "total": 1
}

Campos da resposta

rate_areasarray

Áreas. Vazio ([]) quando nenhuma casa.

totalinteger

Quantidade devolvida.

rate_areas[].iduuid

Id da área.

rate_areas[].namestring

Nome.

rate_areas[].descriptionstring

Descrição.

rate_areas[].typestring

shippingtax

Uso: frete ou imposto.

rate_areas[].statusstring

AD

A ativa, D desativada. Uma área desativada não casa com nenhum endereço.

rate_areas[].min_order_amountinteger

Valor mínimo do pedido para a área valer, em centavos. 0 = sem mínimo.

rate_areas[].shipping_rate_amountinteger

Tarifa fixa de frete da área, em centavos. Veja o aviso abaixo.

rate_areas[].zip_codesstring

Padrões de CEP, um por linha.

rate_areas[].citiesstring

Texto livre guardado (não entra no cálculo).

rate_areas[].addressesstring

Texto livre guardado (não entra no cálculo).

rate_areas[].zonesarray

Zonas da área (estado, cidade, bairro, faixa de CEP). Ausente quando não há.

rate_areas[].zones[].country_codestring

País (BR).

rate_areas[].zones[].state_codestring

Sigla do estado. Pode ser vazio.

rate_areas[].zones[].city_iduuid

Cidade do catálogo de localidades. Ausente se não houver.

rate_areas[].zones[].district_iduuid

Bairro do catálogo de localidades. Ausente se não houver.

rate_areas[].zones[].cep_fromstring

Início da faixa de CEP, 8 dígitos. Vazio se a zona não é por faixa.

rate_areas[].zones[].cep_tostring

Fim da faixa de CEP, 8 dígitos.

rate_areas[].zones[].min_order_amountinteger

Mínimo da zona, em centavos.

rate_areas[].geofencesarray

Desenho no mapa (polígonos ou círculos), quando o módulo de geocerca está em uso. Ausente se não houver.

rate_areas[].created_atstring

Criação, RFC 3339 em UTC.

rate_areas[].updated_atstring

Última alteração, RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401 / 403	Sem token ou sem privilégio	`{"error":"insufficient privileges", ...}`
500	Falha interna	`{"error":"failed to list rate areas","detail":"..."}`

Consultar uma área

Devolve uma área, incluindo as zonas. Funciona para áreas ativas e desativadas.

GET/api/v1/admin/rate-areas/{id}Admin

Detalha uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/rate-areas/7bce1201-0e92-49d1-8e25-846f35fa697e" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Área retornada

json

{
  "id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "name": "Norte",
  "description": "Região Norte (7 estados)",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 0,
  "shipping_rate_amount": 0,
  "zip_codes": "",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "258257fb-0790-49d9-b981-6acae95891af", "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e", "country_code": "BR", "state_code": "AC", "cep_from": "", "cep_to": "", "min_order_amount": 0 }
  ],
  "created_at": "2026-04-26T20:00:47.422644Z",
  "updated_at": "2026-04-26T20:00:47.422644Z"
}

Os campos são os da lista.

Erros

Status	Quando	Corpo
404	Área inexistente	`{"error":"rate area not found"}`
500	`id` que não é UUID	`{"error":"failed to get rate area","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Criar uma área

Cria uma área da loja, com zonas opcionais. Tudo é gravado numa única transação: uma zona inválida desfaz a criação inteira.

POST/api/v1/admin/rate-areasAdmin

Cria uma área de tarifa

Corpo da requisição

namestringobrigatório

Nome da área.

descriptionstring

Descrição.

typestringpadrão: shipping

shippingtax

Uso da área.

statusstringpadrão: A

ADactivedisabled

Estado inicial.

min_order_amountintegerpadrão: 0

Pedido mínimo da área, em centavos.

shipping_rate_amountintegerpadrão: 0

Tarifa fixa de frete, em centavos. Veja o aviso abaixo.

zip_codesstringpadrão:

Padrões de CEP: texto com um por linha, ou lista JSON de textos.

citiesstring

Texto livre (lista JSON ou linhas). Guardado, sem efeito no cálculo.

addressesstring

Texto livre (lista JSON ou linhas). Guardado, sem efeito no cálculo.

zonesarray

Zonas da área.

country_codestring

País (BR).

state_codestring

Sigla do estado.

city_iduuid

Cidade do catálogo de localidades.

district_iduuid

Bairro do catálogo de localidades.

cep_fromstring

Início da faixa de CEP, 8 dígitos, com ou sem hífen. Obrigatório junto com cep_to.

cep_tostring

Fim da faixa de CEP. Não pode ser menor que cep_from.

min_order_amountinteger

Pedido mínimo da zona, em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/rate-areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Capital SP",
    "description": "CEPs da capital",
    "type": "shipping",
    "min_order_amount": 5000,
    "zip_codes": ["01*", "02*"],
    "zones": [
      { "country_code": "BR", "state_code": "SP", "cep_from": "01000-000", "cep_to": "05999-999" }
    ]
  }'

Resposta

201Área criada

json

{
  "id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1",
  "name": "Capital SP",
  "description": "CEPs da capital",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 5000,
  "shipping_rate_amount": 0,
  "zip_codes": "01*\n02*",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "e40781e9-bfd1-409b-aa20-699429561083", "rate_area_id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1", "country_code": "BR", "state_code": "SP", "cep_from": "01000000", "cep_to": "05999999", "min_order_amount": 0 }
  ],
  "created_at": "2026-10-11T21:26:41.81573Z",
  "updated_at": "2026-10-11T21:26:41.81573Z"
}

Note que os CEPs voltam só com dígitos (01000000) e zip_codes volta como texto com quebra de linha.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	`name` vazio	`{"error":"name is required"}`
400	Faixa de CEP incompleta, com formato inválido ou com `cep_from` maior que `cep_to`	`{"error":"invalid CEP range: both cep_from and cep_to must be provided"}`
400	Qualquer outra falha ao gravar (nesta rota, até falhas internas voltam como 400)	`{"error":"insert rate area: ..."}`

Alterar uma área

Atualização parcial: só os campos enviados mudam. Atenção a zones: se enviada, substitui todas as zonas existentes; se omitida, elas ficam como estão.

PUT/api/v1/admin/rate-areas/{id}Admin

Altera uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

typestring

shippingtax

Novo uso.

statusstring

ADactivedisabled

Novo estado.

min_order_amountinteger

Novo pedido mínimo, em centavos.

shipping_rate_amountinteger

Nova tarifa fixa, em centavos.

zip_codesstring

Novos padrões de CEP (texto ou lista JSON). Substitui os anteriores.

citiesstring

Novo texto livre.

addressesstring

Novo texto livre.

zonesarray

Novas zonas, com os mesmos campos da criação. Substitui todas as existentes.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/rate-areas/7fd8c24b-f48f-47fc-9bb5-6352737d27f1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "CEPs da capital e Grande SP", "min_order_amount": 8000}'

Resposta

200Área alterada

json

{
  "id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1",
  "name": "Capital SP",
  "description": "CEPs da capital e Grande SP",
  "type": "shipping",
  "status": "A",
  "min_order_amount": 8000,
  "shipping_rate_amount": 0,
  "zip_codes": "01*\n02*",
  "cities": "",
  "addresses": "",
  "zones": [
    { "id": "e40781e9-bfd1-409b-aa20-699429561083", "rate_area_id": "7fd8c24b-f48f-47fc-9bb5-6352737d27f1", "country_code": "BR", "state_code": "SP", "cep_from": "01000000", "cep_to": "05999999", "min_order_amount": 0 }
  ],
  "created_at": "2026-10-11T21:26:41.81573Z",
  "updated_at": "2026-10-11T21:40:00.000Z"
}

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Zona com faixa de CEP inválida	`{"error":"invalid CEP range: cep_from must be <= cep_to"}`
404	Área inexistente	`{"error":"rate area not found"}`
500	`id` que não é UUID, ou outra falha ao gravar	`{"error":"failed to update rate area","detail":"..."}`

Excluir uma área

DELETE/api/v1/admin/rate-areas/{id}Admin

Exclui uma área de tarifa

Parâmetros de caminho

iduuidobrigatório

Id da área.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/rate-areas/7fd8c24b-f48f-47fc-9bb5-6352737d27f1" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Área excluída

json

{ "message": "rate area deleted" }

Erros

Status	Quando	Corpo
500	Área inexistente (deveria ser 404) ou `id` que não é UUID	`{"error":"failed to delete rate area","detail":"rate area 7fd8c24b-... not found"}`