Idiomas e localidades

Esta seção reúne dois recursos de apoio à vitrine. O primeiro é o idioma: cada loja liga os idiomas que quer oferecer, define um padrão, e o visitante pode trocar. A API entrega a lista de idiomas, lembra a escolha do visitante em um cookie e devolve o dicionário de textos traduzidos (as frases de botões e mensagens da loja). O segundo são as localidades: a lista oficial de países, estados, cidades e bairros que alimenta os campos de endereço.

Todas as oito rotas são públicas, funcionam sem login e respondem com Cache-Control: public, max-age=300, stale-while-revalidate=1800, ou seja, podem ser guardadas por 5 minutos.

Como funciona

1. Descubra os idiomas

   Listar idiomas devolve os idiomas ligados e, em active, o que vale para este visitante (o do cookie ou o padrão da loja).

2. Carregue os textos

   Textos traduzidos devolve o dicionário chave: texto. Para economizar tráfego, peça só os prefixos que a tela usa (?prefix=storefront.,common.).

3. Deixe o visitante trocar

   Escolher idioma grava o cookie e responde 204. Depois dele, recarregue os textos.

4. Monte os campos de endereço

   Países, estados, cidades e bairros preenchem os seletores em cascata do endereço.

Conceitos-chave

Idioma padrão e idioma ativo

O padrão é o idioma que a loja escolheu para quem não escolheu nada. O ativo é o que vale para esta requisição: o do cookie, se for um idioma ligado, senão o padrão. Pedidos feitos por clientes logados também registram o idioma ativo no perfil, quando o cliente ainda não fixou um.

Direção e locale

Cada idioma traz direction (LTR ou RTL, como o árabe) e locale (pt-BR, es-ES, ar-SA), que você usa para formatar datas e números.

Cadeia estado, cidade, bairro

Os identificadores são UUIDs. Um estado tem code de 2 letras (SP), uma cidade pertence a um estado (state_id) e tem ibge_code, e um bairro pertence a uma cidade (city_id) e traz a faixa de CEP (cep_range_start, cep_range_end).

Rotas

Erros comuns

• Pedir os textos de um idioma desligado. Responde 404 language not enabled on this tenant. Use os códigos de GET /languages.
• Esquecer de recarregar os textos depois de trocar o idioma. A troca só grava o cookie; os textos não mudam sozinhos.
• Pôr um CDN na frente de languages/active. A resposta depende do cookie do visitante e grava um cookie, mas não declara Vary: Cookie. Um cache compartilhado pode servir o idioma de um visitante a outro. Chame essa rota do navegador, ou leia o cookie você mesmo.
• Baixar todas as cidades. São 5.571. Filtre por state_id, use search e pagine.
• Mandar um id que não é UUID. state_id ou city_id inválidos podem voltar como 500 ou 400 conforme a rota; valide antes.

Próximos passos