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

Áreas do método

Vincula um método de envio a regiões de tarifa e define o prazo de entrega de cada uma, incluindo o vínculo padrão para os demais destinos.

Um método de envio raramente entrega no mesmo prazo para o país inteiro. O vínculo método/área liga o método a uma área de tarifa (uma região cadastrada à parte, por estado, cidade ou faixa de CEP) e guarda o prazo daquela região em dias úteis. As faixas de preço com o mesmo rate_area_id são o preço daquela região.

O vínculo com rate_area_id vazio é o padrão: vale para todos os destinos que nenhuma outra área do método cobre. Cada método aceita um vínculo padrão.

Listar vínculos

Cada vínculo vem com as suas faixas de preço (tiers) já carregadas, o que dá a tabela completa do método numa chamada. Ordem: por position, com o vínculo padrão por último.

GET/api/v1/admin/shipping-methods/{id}/areasAdmin

Lista os vínculos método/área

Parâmetros de caminho

iduuidobrigatório

Id do método.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/areas" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vínculos retornados

json

{
  "areas": [
    {
      "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
      "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "rate_area_name": "Norte",
      "min_delivery_days": 8,
      "max_delivery_days": 12,
      "position": 0,
      "created_at": "2026-09-09T16:06:04.11883Z",
      "updated_at": "2026-09-09T16:06:04.11883Z"
    },
    {
      "id": "3385159f-f6dd-4833-a4a9-bff962da8af8",
      "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "position": 0,
      "created_at": "2026-04-24T13:46:27.010854Z",
      "updated_at": "2026-04-24T13:46:27.010854Z",
      "tiers": [
        {
          "id": "16ed1d7f-c392-4a76-b4e9-53563fa5e5ea",
          "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
          "min_weight": 0,
          "max_weight": 0,
          "min_order_value": 0,
          "max_order_value": 0,
          "rate": 1000,
          "rate_area_id": null,
          "min_items": 0,
          "max_items": 0,
          "created_at": "2026-07-11T21:58:14.099586Z"
        }
      ]
    }
  ],
  "total": 2
}

Campos da resposta

areasarray

Vínculos do método. null quando não há nenhum.

totalinteger

Quantidade de vínculos.

areas[].iduuid

Id do vínculo.

areas[].shipping_method_iduuid

Método.

areas[].rate_area_iduuid

Área de tarifa. Ausente = vínculo padrão.

areas[].rate_area_namestring

Nome da área (só na leitura; ausente no padrão).

areas[].min_delivery_daysinteger

Prazo mínimo, em dias úteis.

areas[].max_delivery_daysinteger

Prazo máximo, em dias úteis. 0 = não informado.

areas[].positioninteger

Ordem de exibição.

areas[].created_atstring

Criação, RFC 3339 em UTC.

areas[].updated_atstring

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

areas[].tiersarray

Faixas de preço do vínculo (mesmo formato de Faixas de preço). Ausente quando o vínculo não tem faixas.

Criar um vínculo

POST/api/v1/admin/shipping-methods/{id}/areasAdmin

Cria um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório

Id do método.

Corpo da requisição

rate_area_iduuid

Área de tarifa. Omita ou envie vazio para criar o vínculo padrão (só um por método).

min_delivery_daysinteger

Prazo mínimo, em dias úteis. Não pode ser negativo.

max_delivery_daysinteger

Prazo máximo, em dias úteis. Se maior que zero, precisa ser maior ou igual ao mínimo.

positioninteger

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
    "min_delivery_days": 8,
    "max_delivery_days": 12
  }'

Resposta

201Vínculo criado

json

{
  "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "rate_area_name": "Norte",
  "min_delivery_days": 8,
  "max_delivery_days": 12,
  "position": 0,
  "created_at": "2026-09-09T16:06:04.11883Z",
  "updated_at": "2026-09-09T16:06:04.11883Z"
}

Alterar um vínculo

Alteração parcial. Atenção ao caminho: esta rota e a de apagar ficam em /shipping/areas/{areaID}, sem o id do método, porque o areaID é o id do vínculo (não o da área de tarifa).

PUT/api/v1/admin/shipping/areas/{areaID}Admin

Altera um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

areaIDuuidobrigatório

Id do vínculo (campo id da listagem).

Corpo da requisição

rate_area_iduuid

Área de tarifa. Enviar string vazia transforma o vínculo no padrão (só um por método). Omita para manter como está.

min_delivery_daysinteger

Prazo mínimo, em dias úteis. Não pode ser negativo.

max_delivery_daysinteger

Prazo máximo, em dias úteis. Não pode ser negativo. Ao contrário da criação, aqui a plataforma não compara com o mínimo.

positioninteger

Ordem de exibição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/shipping/areas/$PAIRING_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "min_delivery_days": 6,
    "max_delivery_days": 10
  }'

Resposta

200Vínculo alterado

json

{
  "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "rate_area_name": "Norte",
  "min_delivery_days": 6,
  "max_delivery_days": 10,
  "position": 0,
  "created_at": "2026-09-09T16:06:04.11883Z",
  "updated_at": "2026-09-09T16:06:04.11883Z"
}

Apagar um vínculo

Apaga o vínculo e as faixas de preço do método que pertencem à mesma área.

DELETE/api/v1/admin/shipping/areas/{areaID}Admin

Apaga um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

areaIDuuidobrigatório

Id do vínculo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/shipping/areas/$PAIRING_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vínculo apagado

json

{
  "message": "method area deleted"
}

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, ou `areaID` que não é UUID	`{"error":"invalid request body","detail":"..."}`
500	Dias negativos, `max_delivery_days` menor que o mínimo, segundo vínculo padrão no mesmo método, vínculo repetido para a mesma área, ou método/área inexistente	`{"error":"failed to create method area","detail":"já existe um registro com esse valor (regra de unicidade/integridade do recurso)..."}`

Veja também

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

Áreas do método

Vincula um método de envio a regiões de tarifa e define o prazo de entrega de cada uma, incluindo o vínculo padrão para os demais destinos.

O vínculo com rate_area_id vazio é o padrão: vale para todos os destinos que nenhuma outra área do método cobre. Cada método aceita um vínculo padrão.

Listar vínculos

Cada vínculo vem com as suas faixas de preço (tiers) já carregadas, o que dá a tabela completa do método numa chamada. Ordem: por position, com o vínculo padrão por último.

GET/api/v1/admin/shipping-methods/{id}/areasAdmin

Lista os vínculos método/área

Parâmetros de caminho

iduuidobrigatório

Id do método.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/areas" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vínculos retornados

json

{
  "areas": [
    {
      "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
      "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
      "rate_area_name": "Norte",
      "min_delivery_days": 8,
      "max_delivery_days": 12,
      "position": 0,
      "created_at": "2026-09-09T16:06:04.11883Z",
      "updated_at": "2026-09-09T16:06:04.11883Z"
    },
    {
      "id": "3385159f-f6dd-4833-a4a9-bff962da8af8",
      "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "position": 0,
      "created_at": "2026-04-24T13:46:27.010854Z",
      "updated_at": "2026-04-24T13:46:27.010854Z",
      "tiers": [
        {
          "id": "16ed1d7f-c392-4a76-b4e9-53563fa5e5ea",
          "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
          "min_weight": 0,
          "max_weight": 0,
          "min_order_value": 0,
          "max_order_value": 0,
          "rate": 1000,
          "rate_area_id": null,
          "min_items": 0,
          "max_items": 0,
          "created_at": "2026-07-11T21:58:14.099586Z"
        }
      ]
    }
  ],
  "total": 2
}

Campos da resposta

areasarray

Vínculos do método. null quando não há nenhum.

totalinteger

Quantidade de vínculos.

areas[].iduuid

Id do vínculo.

areas[].shipping_method_iduuid

Método.

areas[].rate_area_iduuid

Área de tarifa. Ausente = vínculo padrão.

areas[].rate_area_namestring

Nome da área (só na leitura; ausente no padrão).

areas[].min_delivery_daysinteger

Prazo mínimo, em dias úteis.

areas[].max_delivery_daysinteger

Prazo máximo, em dias úteis. 0 = não informado.

areas[].positioninteger

Ordem de exibição.

areas[].created_atstring

Criação, RFC 3339 em UTC.

areas[].updated_atstring

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

areas[].tiersarray

Faixas de preço do vínculo (mesmo formato de Faixas de preço). Ausente quando o vínculo não tem faixas.

Criar um vínculo

POST/api/v1/admin/shipping-methods/{id}/areasAdmin

Cria um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório

Id do método.

Corpo da requisição

rate_area_iduuid

Área de tarifa. Omita ou envie vazio para criar o vínculo padrão (só um por método).

min_delivery_daysinteger

Prazo mínimo, em dias úteis. Não pode ser negativo.

max_delivery_daysinteger

Prazo máximo, em dias úteis. Se maior que zero, precisa ser maior ou igual ao mínimo.

positioninteger

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/areas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
    "min_delivery_days": 8,
    "max_delivery_days": 12
  }'

Resposta

201Vínculo criado

json

{
  "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "rate_area_name": "Norte",
  "min_delivery_days": 8,
  "max_delivery_days": 12,
  "position": 0,
  "created_at": "2026-09-09T16:06:04.11883Z",
  "updated_at": "2026-09-09T16:06:04.11883Z"
}

Alterar um vínculo

Alteração parcial. Atenção ao caminho: esta rota e a de apagar ficam em /shipping/areas/{areaID}, sem o id do método, porque o areaID é o id do vínculo (não o da área de tarifa).

PUT/api/v1/admin/shipping/areas/{areaID}Admin

Altera um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

areaIDuuidobrigatório

Id do vínculo (campo id da listagem).

Corpo da requisição

rate_area_iduuid

Área de tarifa. Enviar string vazia transforma o vínculo no padrão (só um por método). Omita para manter como está.

min_delivery_daysinteger

Prazo mínimo, em dias úteis. Não pode ser negativo.

max_delivery_daysinteger

Prazo máximo, em dias úteis. Não pode ser negativo. Ao contrário da criação, aqui a plataforma não compara com o mínimo.

positioninteger

Ordem de exibição.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/shipping/areas/$PAIRING_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "min_delivery_days": 6,
    "max_delivery_days": 10
  }'

Resposta

200Vínculo alterado

json

{
  "id": "7a6849c3-7b89-4721-b0f3-6814f383588a",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_area_id": "7bce1201-0e92-49d1-8e25-846f35fa697e",
  "rate_area_name": "Norte",
  "min_delivery_days": 6,
  "max_delivery_days": 10,
  "position": 0,
  "created_at": "2026-09-09T16:06:04.11883Z",
  "updated_at": "2026-09-09T16:06:04.11883Z"
}

Apagar um vínculo

Apaga o vínculo e as faixas de preço do método que pertencem à mesma área.

DELETE/api/v1/admin/shipping/areas/{areaID}Admin

Apaga um vínculo método/área

Exige manage_shipping.

Parâmetros de caminho

areaIDuuidobrigatório

Id do vínculo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/shipping/areas/$PAIRING_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Vínculo apagado

json

{
  "message": "method area deleted"
}

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, ou `areaID` que não é UUID	`{"error":"invalid request body","detail":"..."}`
500	Dias negativos, `max_delivery_days` menor que o mínimo, segundo vínculo padrão no mesmo método, vínculo repetido para a mesma área, ou método/área inexistente	`{"error":"failed to create method area","detail":"já existe um registro com esse valor (regra de unicidade/integridade do recurso)..."}`