VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Idiomas e localidades

Idiomas da vitrine

Lista os idiomas ligados na loja, lê o idioma ativo do visitante, grava a escolha dele e baixa o dicionário de textos traduzidos.

Estas quatro rotas implementam o seletor de idioma da vitrine. O idioma escolhido fica no cookie venddor_language (válido por 30 dias, Path=/, SameSite=Lax, legível pelo JavaScript; Secure quando a conexão é HTTPS). Em chamadas feitas por um app, que não tem o cookie do navegador, guarde o código você mesmo e passe-o nas rotas que o pedem.

Listar idiomas

GET/api/v1/storefront/languagesPública

Lista os idiomas habilitados e o ativo

Devolve os idiomas ligados na loja e, em active, o código do idioma válido para este visitante: o do cookie venddor_language se for um idioma ligado, senão o padrão da loja.

Exemplo de requisição

Resposta

200Idiomas ligados

Campos da resposta

activestring
Código do idioma ativo para este visitante.
itemsarray
Idiomas ligados (a resposta real traz todos; o exemplo mostra dois).
items[].codestring
Código do idioma (pt-BR, es, ar). É o valor para select e para os textos.
items[].nameEnstring
Nome em inglês.
items[].nameNativestring
Nome no próprio idioma, para exibir no seletor.
items[].directionstring
LTRRTL
Sentido de escrita. RTL (direita para esquerda) exige espelhar a interface.
items[].localestring
Locale para formatar datas e números (es-ES).
items[].enabledboolean
Sempre true aqui.
items[].isDefaultboolean
true no idioma padrão da loja.
items[].positioninteger
Ordem de exibição configurada. Pode ser igual para vários idiomas (0).
items[].createdAtstring
Quando o idioma foi cadastrado, RFC 3339.
items[].updatedAtstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
500Falha ao listar{"error":"failed to list languages","detail":"..."}

Idioma ativo

GET/api/v1/storefront/languages/activePública

Consulta o idioma ativo do visitante

Devolve o idioma ativo (cookie válido ou padrão da loja) e grava de novo o cookie venddor_language, renovando a validade. Use ao abrir o app para saber em que idioma desenhar a primeira tela.

Exemplo de requisição

Resposta

200Idioma ativo

Campos da resposta

codestring
Código do idioma ativo.
nameEnstring
Nome em inglês.
nameNativestring
Nome no próprio idioma.
directionstring
LTRRTL
Sentido de escrita.
localestring
Locale para formatação.
enabledboolean
Sempre true.
isDefaultboolean
Se é o padrão da loja.
positioninteger
Ordem configurada.
createdAtstring
Cadastro do idioma, RFC 3339.
updatedAtstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
404A loja não tem nenhum idioma padrão{"error":"no active language configured"}
500Falha ao ler{"error":"failed to list languages","detail":"..."}

Escolher o idioma

POST/api/v1/storefront/languages/selectPública

Escolhe o idioma do visitante

Valida o código contra os idiomas ligados e grava o cookie venddor_language. É idempotente e responde 204 sem corpo. O código é normalizado (pt-br vira pt-BR).

Corpo da requisição

codestringobrigatório
Código de um idioma ligado na loja.

Exemplo de requisição

Resposta

204Idioma gravado

Erros

StatusQuandoCorpo
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
400Sem code{"error":"code is required"}
404Idioma desligado ou inexistente{"error":"language not enabled on this tenant"}

Textos traduzidos

GET/api/v1/storefront/languages/{code}/translationsPública

Consulta os textos traduzidos de um idioma

Devolve o dicionário de textos da vitrine para o idioma. Ele já vem mesclado: pacote da plataforma, depois idioma padrão da loja, depois o idioma pedido, de modo que uma chave sem tradução cai no idioma padrão em vez de sumir. O dicionário completo é grande (cerca de 47 mil chaves e 3 MB na loja de teste, a maior parte do painel de administração): peça só os prefixos que a sua tela usa.

Parâmetros de caminho

codestringobrigatório
Código de um idioma ligado na loja (pt-BR, es).

Parâmetros de consulta

prefixstring
Lista de prefixos de chave separados por vírgula (storefront.,common.). Só as chaves que começam com algum deles são devolvidas. Ausente: o dicionário inteiro. Um prefixo que não casa com nada devolve {"translations": {}} com 200.

Exemplo de requisição

Resposta

200Textos

Campos da resposta

translationsobject
Mapa chave para texto. As chaves usam pontos como separador (common.actions). O exemplo está abreviado.

Erros

StatusQuandoCorpo
404Idioma desligado ou inexistente{"error":"language not enabled on this tenant"}
500Falha ao montar o dicionário{"error":"failed to resolve translations","detail":"..."}
Textos podem vir em outro idioma

No exemplo, common.accessDenied vem em inglês dentro do dicionário pt-BR: o texto guardado para essa chave na loja de teste está em inglês. O dicionário devolve o que a loja tem cadastrado; não presuma que todo valor está no idioma pedido, e não use o texto como prova de que a chave foi traduzida.

Veja também

  • Países, estados, cidades e bairros
  • Dados gerais da loja
  • Visão geral de idiomas e localidades
Anterior
Idiomas e localidades
Próxima
Países, estados, cidades e bairros
Nesta página
  • Listar idiomas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Idioma ativo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Escolher o idioma
  • Exemplo de requisição
  • Resposta
  • Erros
  • Textos traduzidos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/storefront/languages"
bash
curl -i "$BASE_URL/api/v1/storefront/languages/active" --cookie "venddor_language=es"
bash
curl -i -X POST "$BASE_URL/api/v1/storefront/languages/select" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "es"
}'
bash
curl "$BASE_URL/api/v1/storefront/languages/pt-BR/translations?prefix=storefront.,common."
json
{
  "active": "pt-BR",
  "items": [
    {
      "code": "es",
      "nameEn": "Spanish",
      "nameNative": "Español",
      "direction": "LTR",
      "locale": "es-ES",
      "enabled": true,
      "isDefault": false,
      "position": 0,
      "createdAt": "2026-05-15T21:04:23.044062Z",
      "updatedAt": "2026-07-11T22:52:18.895198Z"
    },
    {
      "code": "pt-BR",
      "nameEn": "Portuguese (Brazil)",
      "nameNative": "Português (Brasil)",
      "direction": "LTR",
      "locale": "pt-BR",
      "enabled": true,
      "isDefault": true,
      "position": 0,
      "createdAt": "2026-05-15T11:19:40.892818Z",
      "updatedAt": "2026-07-19T13:10:47.284292Z"
    }
  ]
}
json
{
  "code": "es",
  "nameEn": "Spanish",
  "nameNative": "Español",
  "direction": "LTR",
  "locale": "es-ES",
  "enabled": true,
  "isDefault": false,
  "position": 0,
  "createdAt": "2026-05-15T21:04:23.044062Z",
  "updatedAt": "2026-07-11T22:52:18.895198Z"
}
json
{
  "translations": {
    "common.accessDenied": "Access Denied",
    "common.actionFailed": "Ação falhou",
    "common.actions": "Ações"
  }
}
http
HTTP/1.1 204 No Content
Set-Cookie: venddor_language=es; Path=/; Max-Age=2592000; SameSite=Lax