Custo de Frete

Configuração de Valor de Entrega por Bairro e Frete Grátis

Este endpoint é utilizado para definir as regras de custo de entrega por Bairro e as condições de frete grátis da loja. A configuração abrange três modalidades: Frete Grátis Global, Valor Mínimo para Frete Grátis (por dia) e Custo Fixo por Bairro.

POST

/store/{store_id}/delivery

Lógica de Aplicação do Frete:

Frete Grátis Global: Se free_delivery for true, o frete é grátis para todos os pedidos.
Frete Fixo por Bairro (neighborhoods): Define o valor do frete para bairros específicos. Este é o frete que será cobrado se nenhuma regra de frete grátis for aplicável.
Frete Grátis Condicional por Dia (delivery_days): Define o valor mínimo que o pedido deve atingir em um dia específico para que o frete seja zerado.

Payload Configuração de Valor de Entrega por Bairro e Frete Grátis

{
  "free_delivery": false,
  "delivery_days": [
    {
      "day": 0,
      "value": "15",
      "status": true
    },
    {
      "day": 1,
      "value": "3.50",
      "status": true
    },
    {
      "day": 2,
      "value": "9.50",
      "status": false
    }
  ],
  "neighborhoods": [
    {
      "id": 6571,
      "value": "20"
    }
  ]
}

Detalhamento do Payload

1. Campos Principais

Campo	Obrigatório	Descrição
free_delivery	✅	Indica se a loja oferece entrega grátis global (para todos os pedidos, todos os dias). Valores: `true` ou `false`.
delivery_days	❌	Array que define o valor mínimo do pedido para ter frete grátis em dias específicos.
neighborhoods	❌	Array para configurar os custos fixos de entrega por bairro.

2. Objeto `delivery_days` (Frete por Dia da Semana)

Este array deve conter a definição para cada dia da semana.

Campo	Obrigatório	Descrição
delivery_days[].day	✅	Dia da semana: 0 (Segunda-feira) a 6 (Domingo).
delivery_days[].value	✅	Valor Mínimo do Pedido (em Reais). Se o pedido atingir este valor, o frete é zerado. Deve ser enviado como string usando ponto (Ex: `"30.00"`).
delivery_days[].status	✅	Indica se a regra de frete grátis por valor mínimo está ativa (`true`) ou inativa (`false`) para aquele dia.

3. Objeto `neighborhoods` (Frete por Bairro)

Este array permite configurar custos de entrega que têm prioridade sobre o frete por dia.

Campo	Obrigatório	Descrição
neighborhoods[].id	✅	ID do Bairro. Regra: Este ID deve ser consultado previamente através do endpoint de Auxiliary.
neighborhoods[].value	✅	Valor do frete em Reais (R$) para o bairro específico (em string, formato decimal com ponto, Ex: `"20.00"`).

Configuração de Frete Fixo por Bairro

Este endpoint é utilizado para definir os bairros de entrega da loja e seus respectivos custos fixos de frete.

POST

/store/{store_id}/neighborhoods

Payload Configuração de Frete Fixo por Bairro

{
  "store_neighborhoods": [
    {
      "neighborhood_id": "16203",
      "delivery_tax": 10
    }
  ]
}

Detalhamento do Payload

Campo	Obrigatório	Descrição
`store_neighborhoods`	✅	Array principal contendo a lista completa de bairros ativos e seus valores de frete.
`store_neighborhoods[].neighborhood_id`	✅	ID do Bairro. O ID único do bairro para o qual o frete será configurado. Consulta de Bairros
`store_neighborhoods[].delivery_tax`	✅	Valor do Frete Fixo (em Reais). O custo da entrega para este bairro.

Importante (Atualização e Ativação)

Atualização por Sobrescrita: A cada chamada a este endpoint, a lista de bairros de entrega da loja é completamente sobrescrita pelo array store_neighborhoods enviado.
Ativação/Desativação: Não existe um campo de status para ativar ou desativar um bairro individualmente. Para desativar a entrega em um bairro, basta omitir o neighborhood_id desse bairro na próxima requisição. Apenas os bairros listados no payload permanecerão ativos para entrega.

Configuração de Frete por Raio

Este endpoint é utilizado para definir os custos de entrega com base na distância geográfica entre a loja e o cliente (frete por raio de alcance). Se a localização do cliente estiver dentro do raio configurado, o valor de frete correspondente será aplicado.

Pontos de Atenção e Regras Críticas

Habilitação de Cidade (Pré-condição)

ATENÇÃO: A funcionalidade de Frete por Raio requer que a cidade da loja esteja previamente habilitada para operar neste modelo. Esta é uma configuração de nível de plataforma e é realizada exclusivamente pela equipe do Aiqfome.
Regra de Frete (Bairro vs. Raio)
Lógica de Casamento de Frete: Se o cliente estiver apto tanto para o Frete por Bairro (geolocalização dentro de um bairro mapeado) quanto para o Frete por Raio:
- Se o Frete por Raio estiver Ativo para a Cidade: O sistema priorizará e aplicará o valor do Frete por Raio.
- Se o Frete por Raio estiver Desativado para a Cidade: O sistema ignorará a regra de raio e aplicará o valor do Frete por Bairro.
Fonte de Preço do Frete por Raio
Configuração Exclusiva Aiqfome: Além da habilitação da cidade, o Time Aiqfome pode configurar, internamente, se a loja utilizará:
- Valor do Frete por Raio configurado na Cidade (Regra centralizada).
- Valor do Frete por Raio configurado na Loja (Valores enviados por este endpoint).
Nota: Esta opção é controlada no sistema Aiqfome e não pode ser definida via API pelo integrador.

POST

/store/{store_id}/delivery-costs/radius

Payload Configuração de Frete por Raio

{
  "radius": [
    {
      "distance_km": 10,
      "value": 15,
      "return_tax_value": 5,
      "delivery_code": "teste raio 100km"
    }
  ]
}

Detalhamento do Payload

1. Objeto Principal

Campo	Obrigatório	Descrição
`radius`	✅	Array principal contendo a lista de faixas de alcance (raios) e seus respectivos custos.

2. Objeto `radius[]` (Configuração de Faixa de Raio)

Campo	Obrigatório	Descrição
`radius[].distance_km`	✅	Distância Máxima (em Km) desta faixa de alcance. Ex: um valor de 10 cobre clientes localizados até 10 Km da loja.
`radius[].value`	✅	Valor do Frete (em Reais) para esta faixa de distância. Este é o custo de entrega padrão.
`radius[].return_tax_value`	❌	Valor da Taxa de Retorno (em Reais). Caso o cliente pague na entrega, ele terá uma taxa sobre o retorno incidindo no valor da padrão do raio, para o cliente já é exibido o valor final da entrega com essa taxa somada. Necessário quando o entregador precisa voltar à loja para entregar o dinheiro ou devolver a maquininha. Aplicado somente quando a loja tem Aiqentrega.
`radius[].delivery_code`	❌	Código ou descrição interna que identifica esta faixa de entrega.

Consulta de Bairros de Entrega da Loja

Este endpoint é utilizado para consultar a lista de bairros nos quais a loja configurada possui entrega e qual o valor de frete fixo atualmente associado a cada um.

GET

/store/{store_id}/neighborhoods

Payload Consulta de Bairros de Entrega da Loja

{
  "data": [
    {
      "id": 506,
      "name": "Conjunto Residencial Itamaraty",
      "delivery_tax": 10
    },
    {
      "id": 1797,
      "name": "Galeão",
      "delivery_tax": 8
    },
    {
      "id": 1802,
      "name": "Gleba Ribeirão Sarandi",
      "delivery_tax": 8
    },
    {
      "id": 3993,
      "name": "Condomínio Santa Marina",
      "delivery_tax": 10
    },
    {
      "id": 4011,
      "name": "Conjunto Village Blue",
      "delivery_tax": 10
    },
    {
      "id": 6572,
      "name": "Alto dos Ipês",
      "delivery_tax": 8
    }
  ]
}

Resposta de Sucesso (Status Code 200)

O retorno é um objeto contendo um array na chave data com a lista de bairros e seus respectivos custos de entrega.

Campo	Descrição
`data`	Array principal contendo os objetos de bairro configurados para entrega.
`data[].id`	ID do bairro. É o mesmo ID usado no endpoint de configuração.
`data[].name`	Nome do bairro para fácil identificação.
`data[].delivery_tax`	Valor do Frete Fixo (em Reais) configurado para este bairro.

Consulta de Custos e Regiões de Entrega por Raio da Loja

Este endpoint é utilizado para consultar a configuração de frete por raio (custos) e as regiões geográficas restritas (onde a entrega é proibida) para uma loja específica.

GET

/store/{store_id}/delivery-costs

Importante

Ação	Ferramenta
Configurar Custo de Frete por Raio (`data.radius`)	(`POST /delivery-costs/radius`)
Configurar Áreas de Restrição (`data.restricted_regions`)	Painel da Loja (Backoffice)

Atenção: A definição e alteração das regiões delimitadas e restritas só podem ser realizadas por meio do painel do Seller, não sendo suportadas pela API.

Payload Consulta de Custos e Regiões de Entrega por Raio da Loja

{
  "success": true,
  "data": {
    "store": {
      "id": 53852,
      "name": "Teste Aiqfome"
    },
    "city": {
      "id": 6190,
      "name": "Maringá",
      "ibge_code": "4115200",
      "active_delivery_radius_date": "2025-12-22 11:08:43",
      "location": {
        "latitude": -23.4209995,
        "longitude": -51.9330558
      }
    },
    "radius": [
      {
        "id": 23,
        "distance_km": 10,
        "value": 5,
        "return_tax_value": 0,
        "delivery_code": null
      },
      {
        "id": 24,
        "distance_km": 15,
        "value": 7.5,
        "return_tax_value": 0,
        "delivery_code": null
      }
    ],
    "restricted_regions": []
  }
}

Resposta de Sucesso (Status Code 200)

Objeto Principal

O retorno fornece detalhes da loja, da cidade e as configurações de frete.

Campo Principal	Descrição
`data.store`	Objeto contendo o ID e o nome da loja.
`data.city`	Objeto contendo dados da cidade onde a loja está localizada (ID, nome e coordenadas centrais).
`data.radius`	Array contendo as faixas de custo de entrega configuradas por distância (em KM).
`data.restricted_regions`	Array contendo as regiões geográficas onde a entrega é proibida ou restrita.

Detalhamento: Configuração de Raio (`data.radius[]`)

Estes são os custos de frete definidos por distância.

Campo	Descrição
`radius[].id`	ID único da faixa de raio.
`radius[].distance_km`	Distância máxima (em Km) desta faixa de alcance a partir da localização da loja.
`radius[].value`	Valor do Frete (em Reais) para esta faixa de distância.
`radius[].return_tax_value`	Valor da Taxa de Retorno (em Reais) configurada para esta faixa.
`radius[].delivery_code`	Código de identificação da faixa, se configurado.

Detalhamento: Regiões Restritas (`data.restricted_regions[]`)

Estas são áreas onde a entrega não é permitida, geralmente configuradas para evitar zonas de risco ou áreas de difícil acesso.

Campo	Descrição
`restricted_regions[].id`	ID único da região restrita.
`restricted_regions[].city_id`	ID da cidade à qual esta região restrita pertence.
`restricted_regions[].name`	Nome ou identificação da região (Ex: "castolira", "araretama").
`restricted_regions[].region`	Array de coordenadas (Longitude e Latitude) que formam o polígono geográfico da área restrita.

Configuração de Valor de Entrega por Bairro e Frete Grátis​

1. Campos Principais​

2. Objeto delivery_days (Frete por Dia da Semana)​

3. Objeto neighborhoods (Frete por Bairro)​

Configuração de Frete Fixo por Bairro​

Configuração de Frete por Raio​

Pontos de Atenção e Regras Críticas​

1. Objeto Principal​

2. Objeto radius[] (Configuração de Faixa de Raio)​

Consulta de Bairros de Entrega da Loja​

Consulta de Custos e Regiões de Entrega por Raio da Loja​

Importante​

Objeto Principal​

Detalhamento: Configuração de Raio (data.radius[])​

Detalhamento: Regiões Restritas (data.restricted_regions[])​

aiqfome

Configuração de Valor de Entrega por Bairro e Frete Grátis

1. Campos Principais

2. Objeto `delivery_days` (Frete por Dia da Semana)

3. Objeto `neighborhoods` (Frete por Bairro)

Configuração de Frete Fixo por Bairro

Configuração de Frete por Raio

Pontos de Atenção e Regras Críticas

1. Objeto Principal

2. Objeto `radius[]` (Configuração de Faixa de Raio)

Consulta de Bairros de Entrega da Loja

Consulta de Custos e Regiões de Entrega por Raio da Loja

Importante

Objeto Principal

Detalhamento: Configuração de Raio (`data.radius[]`)

Detalhamento: Regiões Restritas (`data.restricted_regions[]`)