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

bash

curl "$BASE_URL/api/v1/storefront/languages"

Resposta

200Idiomas ligados

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"
    }
  ]
}

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

Status	Quando	Corpo
500	Falha 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

bash

curl -i "$BASE_URL/api/v1/storefront/languages/active" --cookie "venddor_language=es"

Resposta

200Idioma ativo

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"
}

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

Status	Quando	Corpo
404	A loja não tem nenhum idioma padrão	`{"error":"no active language configured"}`
500	Falha 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

bash

curl -i -X POST "$BASE_URL/api/v1/storefront/languages/select" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "es"
}'

Resposta

204Idioma gravado

http

HTTP/1.1 204 No Content
Set-Cookie: venddor_language=es; Path=/; Max-Age=2592000; SameSite=Lax

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Sem `code`	`{"error":"code is required"}`
404	Idioma 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

bash

curl "$BASE_URL/api/v1/storefront/languages/pt-BR/translations?prefix=storefront.,common."

Resposta

200Textos

json

{
  "translations": {
    "common.accessDenied": "Access Denied",
    "common.actionFailed": "Ação falhou",
    "common.actions": "Ações"
  }
}

Campos da resposta

translationsobject

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

Erros

Status	Quando	Corpo
404	Idioma desligado ou inexistente	`{"error":"language not enabled on this tenant"}`
500	Falha ao montar o dicionário	`{"error":"failed to resolve translations","detail":"..."}`