Frete, áreas e retirada
Como a loja define regiões de tarifa, atende retirada em loja e consulta serviços de transportadoras, com o mapa das rotas.
Esta seção cobre três peças do frete que ficam ao redor dos métodos de envio: as áreas de tarifa (regiões geográficas que decidem quais regras valem para um endereço), a retirada em loja (o cliente compra online e busca no balcão) e e o catálogo de serviços de transportadoras (PAC, SEDEX, Jadlog...).
Os métodos de envio em si (nome, tabela de preços por faixa de peso) são tratados em outra seção; aqui estão as peças que eles usam.
Como funciona
Áreas de tarifa
Um endereço pertence a uma área quando casa com qualquer uma das regras dela: um estado, uma cidade, um bairro ou uma faixa de CEP (nas zones), ou um padrão de CEP em zip_codes. Métodos de envio, faixas de preço e impostos apontam para uma área, e só valem para quem está dentro dela.
Retirada em loja (BOPIS)
BOPIS vem do inglês "buy online, pick up in store". O cliente escolhe retirar o pedido num ponto (um depósito da loja), e a loja prepara.
status | Significado | Próximos |
|---|---|---|
awaiting_preparation | Pedido feito, a loja ainda separa os itens. | ready, cancelled |
ready | Separado e disponível; o cliente recebe o código. | picked_up, expired, cancelled |
picked_up | O cliente retirou. | nenhum |
expired | Passou do prazo sem retirada (marcado pela plataforma). | nenhum |
cancelled | Cancelada pela loja. | nenhum |
Serviços de transportadora
É um catálogo somente leitura dos serviços que a plataforma conhece (por exemplo correios com pac e sedex). Serve para escolher o serviço certo ao configurar um método de envio.
Conceitos importantes
Padrões de CEP
zip_codes aceita vários padrões, um por linha. A comparação é feita só com os dígitos: * vale por qualquer sequência de dígitos e ? por exatamente um dígito (01* casa 01310-100; 013?0100 casa 01310100). Na API você pode enviar uma lista JSON (["01*","02*"]) ou um texto com quebras de linha; a resposta devolve sempre texto com quebras de linha.
cities e addresses também são guardados como texto, mas hoje o cálculo de frete usa apenas as zones e os zip_codes. Para restringir por cidade ou bairro, use uma zona.
Faixa de CEP
Em cada zona, cep_from e cep_to formam um intervalo. Os dois são obrigatórios juntos, com 8 dígitos cada (com ou sem hífen), e cep_from não pode ser maior que cep_to. A plataforma grava só os dígitos.
Código de retirada
O código é gerado quando o pedido de retirada nasce e não aparece nas rotas do administrador. A loja o recebe do cliente no balcão e o digita em Confirmar retirada.
Endpoints
| Método e caminho | Para que serve | Auth | Página |
|---|---|---|---|
GET /api/v1/admin/rate-areas | Lista as áreas da loja | admin | Áreas de tarifa |
POST /api/v1/admin/rate-areas | Cria uma área | admin | Áreas de tarifa |
GET /api/v1/admin/rate-areas/{id} | Detalha uma área | admin | Áreas de tarifa |
PUT /api/v1/admin/rate-areas/{id} | Altera uma área | admin | Áreas de tarifa |
DELETE /api/v1/admin/rate-areas/{id} | Exclui uma área | admin | Áreas de tarifa |
GET /api/v1/admin/pickups | Lista as retiradas | admin | Retirada em loja |
POST /api/v1/admin/pickups/{id}/ready | Marca como pronta | admin | Retirada em loja |
POST /api/v1/admin/pickups/{id}/confirm | Confirma a retirada com o código | admin | Retirada em loja |
POST /api/v1/admin/pickups/{id}/cancel | Cancela a retirada | admin | Retirada em loja |
GET /api/v1/admin/shipping-services | Lista os serviços de transportadoras | admin | Serviços de transportadora |
Erros comuns
- Enviar faixa de CEP incompleta. Só
cep_fromou sócep_todá400. Envie os dois ou nenhum. - Achar que
PUTcomzonesacrescenta zonas. As zonas enviadas substituem todas as existentes. - Enviar valores em reais.
min_order_amounteshipping_rate_amountsão centavos.5000é R$ 50,00, não R$ 5.000,00. - Procurar o código de retirada na lista. Ele não é exibido no painel da API; quem informa é o cliente.
- Insistir em códigos errados. Cinco erros travam a retirada por 15 minutos (
429). - Confirmar retirada que não está
ready. Marque como pronta antes; senão a resposta é400. - Apagar uma área e esperar que métodos de envio sumam. Só o método criado pela própria área é removido; os que apenas a referenciam ficam, mas deixam de casar.