Habilitar e alterar moedas

Habilita uma moeda da plataforma, altera taxa e exibição, troca a moeda principal e remove uma moeda.

Quatro operações de escrita. Todas registram o evento no log de ações do painel (tipo settings).

Habilitar uma moeda

Cadastra na loja uma moeda do catálogo. O formato (símbolo, casas, separadores) é copiado do catálogo no momento da habilitação.

POST/api/v1/admin/currenciesAdmin

Habilita uma moeda

Corpo da requisição

codestringobrigatório

Código do catálogo.

exchangeRatenumberobrigatório

Unidades desta moeda por 1 da principal. Maior que zero.

enabledbooleanpadrão: true

Se já aparece para o cliente.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/currencies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "EUR",
    "exchangeRate": 0.1708,
    "position": 2
  }'

Resposta

201Moeda habilitada

json

{
  "code": "EUR",
  "symbol": "€",
  "decimals": 2,
  "decimalSep": ",",
  "thousandsSep": ".",
  "symbolAfter": true,
  "symbolSpace": true,
  "enabled": true,
  "isPrimary": false,
  "exchangeRate": 0.1708,
  "position": 2,
  "autoUpdate": false,
  "autoSource": "ptax",
  "marginPct": 0,
  "roundingRule": "none"
}

Campos da resposta

codestring

Código ISO 4217.

symbolstring

Símbolo.

decimalsinteger

Casas decimais.

decimalSepstring

Separador decimal.

thousandsSepstring

Separador de milhar.

symbolAfterboolean

true escreve o símbolo depois do valor.

symbolSpaceboolean

Espaço entre símbolo e valor.

enabledboolean

Habilitada para o cliente.

isPrimaryboolean

É a moeda principal.

exchangeRatenumber

Unidades desta moeda por 1 da principal.

positioninteger

Ordem de exibição.

autoUpdateboolean

Atualização automática ligada.

autoSourcestring

ptaxawesomeapi

ptax ou awesomeapi.

marginPctnumber

Margem de proteção em %, aplicada sobre a cotação.

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Erros

Status	Quando	Corpo de exemplo
400	`code` vazio ou corpo inválido.	`{"error":"code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
409	A moeda já está habilitada.	`{"error":"currency already enabled","detail":"currency EUR already enabled"}`
422	Código fora do catálogo ou taxa inválida (zero, negativa ou não finita).	`{"error":"invalid exchange rate","detail":"exchange rate must be > 0"}`

Alterar uma moeda

Atualização parcial: só os campos enviados mudam. Sem nenhum campo, devolve a moeda como está.

PATCH/api/v1/admin/currencies/{code}Admin

Altera uma moeda

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Corpo da requisição

enabledboolean

Liga ou desliga para o cliente. Não vale para a principal nem para moeda usada por mercado ativo.

exchangeRatenumber

Nova taxa, maior que zero. A principal só aceita 1.

positioninteger

Ordem de exibição.

autoUpdateboolean

Liga a atualização automática da taxa.

autoSourcestring

ptaxawesomeapi

ptax (padrão) ou awesomeapi.

marginPctnumber

Margem de proteção em %. A taxa gravada é cotação invertida dividida por (1 + margem/100).

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/currencies/EUR" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeRate": 0.17,
    "autoUpdate": true,
    "marginPct": 2
  }'

Resposta

200Moeda alterada

json

{
  "code": "EUR",
  "symbol": "€",
  "decimals": 2,
  "decimalSep": ",",
  "thousandsSep": ".",
  "symbolAfter": true,
  "symbolSpace": true,
  "enabled": true,
  "isPrimary": false,
  "exchangeRate": 0.17,
  "position": 2,
  "autoUpdate": true,
  "autoSource": "ptax",
  "marginPct": 2,
  "roundingRule": "none"
}

Campos da resposta

codestring

Código ISO 4217.

symbolstring

Símbolo.

decimalsinteger

Casas decimais.

decimalSepstring

Separador decimal.

thousandsSepstring

Separador de milhar.

symbolAfterboolean

true escreve o símbolo depois do valor.

symbolSpaceboolean

Espaço entre símbolo e valor.

enabledboolean

Habilitada para o cliente.

isPrimaryboolean

É a moeda principal.

exchangeRatenumber

Unidades desta moeda por 1 da principal.

positioninteger

Ordem de exibição.

autoUpdateboolean

Atualização automática ligada.

autoSourcestring

ptaxawesomeapi

ptax ou awesomeapi.

marginPctnumber

Margem de proteção em %, aplicada sobre a cotação.

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Moeda não cadastrada.	`{"error":"currency not enabled on this tenant"}`
409	Tentou desativar a principal, ou desativar moeda usada por mercado ativo.	`{"error":"cannot disable primary currency","detail":"..."}`
422	Taxa inválida, ou taxa diferente de 1 na principal.	`{"error":"primary currency rate must be 1.0","detail":"..."}`

Definir a moeda principal

Promove uma moeda habilitada a principal e refaz a taxa de todas as outras: a nova taxa de cada uma é a antiga dividida pela taxa da nova principal. Roda em uma transação.

POST/api/v1/admin/currencies/{code}/set-primaryAdmin

Define a moeda principal

Parâmetros de caminho

codestringobrigatório

Moeda que vira principal.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/currencies/EUR/set-primary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Principal trocada (sem corpo)

Resposta vazia.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Moeda não cadastrada.	`{"error":"currency not enabled on this tenant"}`
409	A moeda está desativada.	`{"error":"cannot promote disabled currency","detail":"..."}`

Remover uma moeda

Apaga o cadastro da moeda na loja (não a do catálogo). É idempotente: moeda que não está cadastrada responde 204.

DELETE/api/v1/admin/currencies/{code}Admin

Remove uma moeda

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/currencies/EUR" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Removida (sem corpo)

Resposta vazia.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
409	É a moeda principal, ou está em uso por um mercado ativo.	`{"error":"cannot remove primary currency","detail":"..."}`

Veja também

Moedas

API atual/Referência completa/Moedas

Habilitar e alterar moedas

Habilita uma moeda da plataforma, altera taxa e exibição, troca a moeda principal e remove uma moeda.

Quatro operações de escrita. Todas registram o evento no log de ações do painel (tipo settings).

Habilitar uma moeda

Cadastra na loja uma moeda do catálogo. O formato (símbolo, casas, separadores) é copiado do catálogo no momento da habilitação.

POST/api/v1/admin/currenciesAdmin

Habilita uma moeda

Corpo da requisição

codestringobrigatório

Código do catálogo.

exchangeRatenumberobrigatório

Unidades desta moeda por 1 da principal. Maior que zero.

enabledbooleanpadrão: true

Se já aparece para o cliente.

positionintegerpadrão: 0

Ordem de exibição.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/currencies" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "EUR",
    "exchangeRate": 0.1708,
    "position": 2
  }'

Resposta

201Moeda habilitada

json

{
  "code": "EUR",
  "symbol": "€",
  "decimals": 2,
  "decimalSep": ",",
  "thousandsSep": ".",
  "symbolAfter": true,
  "symbolSpace": true,
  "enabled": true,
  "isPrimary": false,
  "exchangeRate": 0.1708,
  "position": 2,
  "autoUpdate": false,
  "autoSource": "ptax",
  "marginPct": 0,
  "roundingRule": "none"
}

Campos da resposta

codestring

Código ISO 4217.

symbolstring

Símbolo.

decimalsinteger

Casas decimais.

decimalSepstring

Separador decimal.

thousandsSepstring

Separador de milhar.

symbolAfterboolean

true escreve o símbolo depois do valor.

symbolSpaceboolean

Espaço entre símbolo e valor.

enabledboolean

Habilitada para o cliente.

isPrimaryboolean

É a moeda principal.

exchangeRatenumber

Unidades desta moeda por 1 da principal.

positioninteger

Ordem de exibição.

autoUpdateboolean

Atualização automática ligada.

autoSourcestring

ptaxawesomeapi

ptax ou awesomeapi.

marginPctnumber

Margem de proteção em %, aplicada sobre a cotação.

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Erros

Status	Quando	Corpo de exemplo
400	`code` vazio ou corpo inválido.	`{"error":"code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
409	A moeda já está habilitada.	`{"error":"currency already enabled","detail":"currency EUR already enabled"}`
422	Código fora do catálogo ou taxa inválida (zero, negativa ou não finita).	`{"error":"invalid exchange rate","detail":"exchange rate must be > 0"}`

Alterar uma moeda

Atualização parcial: só os campos enviados mudam. Sem nenhum campo, devolve a moeda como está.

PATCH/api/v1/admin/currencies/{code}Admin

Altera uma moeda

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Corpo da requisição

enabledboolean

Liga ou desliga para o cliente. Não vale para a principal nem para moeda usada por mercado ativo.

exchangeRatenumber

Nova taxa, maior que zero. A principal só aceita 1.

positioninteger

Ordem de exibição.

autoUpdateboolean

Liga a atualização automática da taxa.

autoSourcestring

ptaxawesomeapi

ptax (padrão) ou awesomeapi.

marginPctnumber

Margem de proteção em %. A taxa gravada é cotação invertida dividida por (1 + margem/100).

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/currencies/EUR" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "exchangeRate": 0.17,
    "autoUpdate": true,
    "marginPct": 2
  }'

Resposta

200Moeda alterada

json

{
  "code": "EUR",
  "symbol": "€",
  "decimals": 2,
  "decimalSep": ",",
  "thousandsSep": ".",
  "symbolAfter": true,
  "symbolSpace": true,
  "enabled": true,
  "isPrimary": false,
  "exchangeRate": 0.17,
  "position": 2,
  "autoUpdate": true,
  "autoSource": "ptax",
  "marginPct": 2,
  "roundingRule": "none"
}

Campos da resposta

codestring

Código ISO 4217.

symbolstring

Símbolo.

decimalsinteger

Casas decimais.

decimalSepstring

Separador decimal.

thousandsSepstring

Separador de milhar.

symbolAfterboolean

true escreve o símbolo depois do valor.

symbolSpaceboolean

Espaço entre símbolo e valor.

enabledboolean

Habilitada para o cliente.

isPrimaryboolean

É a moeda principal.

exchangeRatenumber

Unidades desta moeda por 1 da principal.

positioninteger

Ordem de exibição.

autoUpdateboolean

Atualização automática ligada.

autoSourcestring

ptaxawesomeapi

ptax ou awesomeapi.

marginPctnumber

Margem de proteção em %, aplicada sobre a cotação.

roundingRulestring

noneend_90integer

none, end_90 ou integer.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Moeda não cadastrada.	`{"error":"currency not enabled on this tenant"}`
409	Tentou desativar a principal, ou desativar moeda usada por mercado ativo.	`{"error":"cannot disable primary currency","detail":"..."}`
422	Taxa inválida, ou taxa diferente de 1 na principal.	`{"error":"primary currency rate must be 1.0","detail":"..."}`

Definir a moeda principal

Promove uma moeda habilitada a principal e refaz a taxa de todas as outras: a nova taxa de cada uma é a antiga dividida pela taxa da nova principal. Roda em uma transação.

POST/api/v1/admin/currencies/{code}/set-primaryAdmin

Define a moeda principal

Parâmetros de caminho

codestringobrigatório

Moeda que vira principal.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/currencies/EUR/set-primary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Principal trocada (sem corpo)

Resposta vazia.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Moeda não cadastrada.	`{"error":"currency not enabled on this tenant"}`
409	A moeda está desativada.	`{"error":"cannot promote disabled currency","detail":"..."}`

Remover uma moeda

Apaga o cadastro da moeda na loja (não a do catálogo). É idempotente: moeda que não está cadastrada responde 204.

DELETE/api/v1/admin/currencies/{code}Admin

Remove uma moeda

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/currencies/EUR" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Removida (sem corpo)

Resposta vazia.

Erros

Status	Quando	Corpo de exemplo
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio `manage_settings` (administrador raiz e administrador total passam).	`{"error":"insufficient privileges","required":"manage_settings"}`
409	É a moeda principal, ou está em uso por um mercado ativo.	`{"error":"cannot remove primary currency","detail":"..."}`

Veja também

Moedas