VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Dados da loja: CEP, CNPJ, moedas e planos

Moedas

Lista as moedas da loja, resolve a ativa e grava a escolha do visitante.

A moeda de cada visitante fica num cookie. Estas três rotas públicas leem as moedas habilitadas, resolvem a ativa e gravam a escolha. Sem moeda extra habilitada, a loja só tem a principal (em geral BRL).

Moedas da loja

Lojas que vendem para fora do Brasil podem habilitar mais de uma moeda. Esta rota devolve as habilitadas, com tudo que é preciso para formatar valores, e qual está ativa para este visitante (a escolhida pelo cookie venddor_currency, se válida).

GET/api/v1/storefront/currenciesPública

Moedas habilitadas e a moeda ativa do visitante

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/currencies"

Resposta

200Moedas
json
{
  "active": "BRL",
  "items": [
    {
      "code": "BRL",
      "symbol": "R$",
      "decimals": 2,
      "decimalSep": ",",
      "thousandsSep": ".",
      "symbolAfter": false,
      "symbolSpace": true,
      "enabled": true,
      "isPrimary": true,
      "exchangeRate": 1,
      "position": 0,
      "autoUpdate": false,
      "autoSource": "ptax",
      "marginPct": 0,
      "roundingRule": "none"
    },
    {
      "code": "ARS",
      "symbol": "$",
      "decimals": 2,
      "decimalSep": ",",
      "thousandsSep": ".",
      "symbolAfter": false,
      "symbolSpace": true,
      "enabled": true,
      "isPrimary": false,
      "exchangeRate": 164.994,
      "position": 3,
      "autoUpdate": false,
      "autoSource": "ptax",
      "marginPct": 0,
      "roundingRule": "none"
    }
  ]
}

Campos da resposta

activestring
Código da moeda ativa. Cai na principal se o cookie não existe ou aponta para moeda desabilitada.
itemsarray

Moedas habilitadas.

codestring
Código ISO 4217 da moeda (BRL, USD, ARS...).
symbolstring
Símbolo para exibir (R$).
decimalsinteger
Casas decimais.
decimalSep, thousandsSepstring
Separadores decimal e de milhar.
symbolAfterboolean
true: o símbolo vem depois do número.
symbolSpaceboolean
true: há um espaço entre símbolo e número (R$ 10,00).
enabledboolean
Sempre true nestas rotas.
isPrimaryboolean
true na moeda principal da loja, na qual os preços são guardados.
exchangeRatenumber
Taxa de câmbio contra a moeda principal, definida pela loja. 1 na principal.
positioninteger
Ordem de exibição.
autoUpdate, autoSource, marginPctmixed
Configuração da atualização automática da taxa (autoSource é ptax, a cotação do Banco Central, e marginPct a margem aplicada). Informativo.
roundingRulestring
noneend_90integer
Arredondamento psicológico do preço convertido: none mantém, end_90 sobe para terminar em ,90, integer sobe para o real inteiro.

Erros

StatusQuandoCorpo de exemplo
500Falha ao ler as moedas.{"error":"failed to list currencies","detail":"..."}

Moeda ativa

Devolve só a moeda ativa: a do cookie venddor_currency, se válida, senão a principal da loja. Grava o cookie na resposta, para as visitas seguintes não precisarem resolver de novo.

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

A moeda ativa do visitante

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/currencies/active"

Resposta

200Moeda ativa
json
{
  "code": "BRL",
  "symbol": "R$",
  "decimals": 2,
  "decimalSep": ",",
  "thousandsSep": ".",
  "symbolAfter": false,
  "symbolSpace": true,
  "enabled": true,
  "isPrimary": true,
  "exchangeRate": 1,
  "position": 0,
  "autoUpdate": false,
  "autoSource": "ptax",
  "marginPct": 0,
  "roundingRule": "none"
}

Campos da resposta

(corpo)object
Uma moeda, nos campos de Moedas da loja.

Erros

StatusQuandoCorpo de exemplo
404A loja não tem moeda configurada.{"error":"no active currency configured"}
500Falha ao resolver a moeda.{"error":"failed to resolve active currency","detail":"..."}

Escolher a moeda

Valida que a moeda está habilitada e grava o cookie venddor_currency (30 dias, Path=/, SameSite=Lax, legível por JavaScript, Secure quando a conexão é HTTPS). Não devolve corpo. A escolha vale por navegador: se você chama a API de um servidor, guarde o cookie e reenvie-o nas chamadas seguintes.

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

Grava a moeda escolhida pelo visitante em um cookie

Corpo da requisição

codestringobrigatório
Código da moeda habilitada. Não diferencia maiúsculas.

Exemplo de requisição

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

Resposta

204Moeda gravada
http
HTTP/1.1 204 No Content

Erros

StatusQuandoCorpo de exemplo
400code vazio ou corpo inválido.{"error":"code is required"}
404Moeda não habilitada nesta loja.{"error":"currency not enabled on this tenant"}
500Falha ao ler as moedas.{"error":"failed to list currencies","detail":"..."}
O que a moeda escolhida muda

Os preços da API continuam em centavos da moeda principal. A moeda escolhida é usada para exibir valores e, ao fechar o pedido, para registrar o total de apresentação (valor convertido, com o arredondamento da moeda) congelado no pedido.

Veja também

  • Busca de CEP e CNPJ
  • Ids, dinheiro e datas
Anterior
Busca de CEP e CNPJ
Próxima
Planos para sellers
Nesta página
  • Moedas da loja
  • Moeda ativa
  • Escolher a moeda
  • Veja também