Moedas
Como a loja habilita moedas além do real, define a taxa de câmbio e deixa a taxa se atualizar sozinha.
Uma loja vende em uma moeda principal (normalmente o real, BRL) e pode mostrar preços em outras moedas habilitadas. O cliente escolhe a moeda na vitrine; os preços são convertidos pela taxa de câmbio cadastrada aqui. Os preços do catálogo continuam guardados na moeda principal.
Como funciona
- Consulte o catálogo de moedas existentes na plataforma.
- Habilite uma delas informando a taxa.
- Ajuste a taxa à mão, ou ligue a atualização automática para a plataforma buscar a cotação (fonte
ptaxdo Banco Central, comawesomeapide reserva) e aplicar uma margem de proteção (Taxas de câmbio). - Para trocar a moeda principal, use
set-primary: a plataforma refaz a taxa de todas as outras moedas em relação à nova principal.
Campos de uma moeda
| Campo | Significado |
|---|---|
code | Código ISO 4217 em maiúsculas (BRL, USD, EUR). |
symbol, decimals, decimalSep, thousandsSep, symbolAfter, symbolSpace | Como o valor é escrito (R$ 1.234,56). |
enabled | Se a moeda aparece para o cliente. |
isPrimary | Se é a moeda principal. |
exchangeRate | Taxa contra a principal (4 casas decimais). |
position | Ordem de exibição (menor primeiro). |
autoUpdate, autoSource, marginPct, roundingRule | Atualização automática (veja abaixo). |
Regras de arredondamento
roundingRule ajusta o preço convertido: none (padrão, mantém os centavos), end_90 (sobe para o próximo valor terminado em ,90) e integer (sobe para o real inteiro seguinte). Um valor desconhecido é tratado como none.
Endpoints
| Método | Caminho | Para quê |
|---|---|---|
| GET | /api/v1/admin/currencies | Lista as moedas da loja |
| GET | /api/v1/admin/currencies/catalog | Lista o catálogo da plataforma |
| GET | /api/v1/admin/currencies/{code} | Consulta uma moeda |
| POST | /api/v1/admin/currencies | Habilita uma moeda |
| PATCH | /api/v1/admin/currencies/{code} | Altera uma moeda |
| POST | /api/v1/admin/currencies/{code}/set-primary | Define a moeda principal |
| DELETE | /api/v1/admin/currencies/{code} | Remove uma moeda |
| POST | /api/v1/admin/currencies/{code}/refresh-rate | Atualiza a taxa agora |
| GET | /api/v1/admin/currencies/{code}/rate-history | Histórico de taxas |
Erros comuns
- Inverter a taxa.
exchangeRateé "moeda estrangeira por 1 da principal", não o preço do dólar em reais. Para US$ 1 = R$ 5,00, a taxa deUSDé0.2. - Habilitar uma moeda duas vezes. A segunda chamada devolve 409. Use
PATCH. - Tentar desativar ou remover a principal. Devolve 409. Troque a principal antes.
- Apagar uma moeda usada por um mercado ativo. Devolve 409 com o nome do mercado.
- Enviar
exchangeRatediferente de 1 para a principal. Devolve 422. - Esperar que o
PATCHvalideautoSourceeroundingRule. Valores desconhecidos são gravados; uma regra desconhecida simplesmente não arredonda.