Taxas de câmbio

Atualiza a taxa de uma moeda agora a partir da cotação oficial e consulta o histórico de cada tentativa.

Com autoUpdate ligado, a plataforma atualiza a taxa sozinha. Estas duas rotas deixam você disparar a atualização na hora e auditar o que aconteceu.

Atualizar a taxa agora

Busca a cotação na fonte configurada (ptax, com awesomeapi de reserva), aplica a margem e grava a nova taxa. A moeda principal não pode ser atualizada. Falha de fonte não vira erro HTTP: o resultado vem com status: failed.

POST/api/v1/admin/currencies/{code}/refresh-rateAdmin

Atualiza a taxa agora

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Exemplo de requisição

bash

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

Resposta

200Resultado da atualização

json

{
  "code": "EUR",
  "status": "applied",
  "appliedRate": 0.1712
}

Campos da resposta

codestring

Moeda.

statusstring

appliedunchangedfailedblocked_variation

applied (nova taxa gravada), unchanged (mesma taxa), failed (fonte indisponível) ou blocked_variation (variação maior que 15%, taxa mantida).

appliedRatenumber

Taxa em vigor depois da tentativa.

errorstring

Presente quando status é failed.

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"}`
422	Tentativa de atualizar a moeda principal.	`{"error":"primary currency rate is fixed at 1.0","detail":"..."}`
500	Moeda não cadastrada ou erro interno.	`{"error":"failed to refresh rate","detail":"currency XXX not enabled"}`

Consultar o histórico

Uma linha por tentativa de atualização (automática ou manual), da mais recente para a mais antiga.

GET/api/v1/admin/currencies/{code}/rate-historyAdmin

Histórico de taxas

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200; fora disso vale 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/currencies/EUR/rate-history?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Histórico

json

{
  "items": [
    {
      "createdAt": "2026-10-11T12:00:00Z",
      "source": "ptax",
      "rawRate": 5.85,
      "marginPct": 0,
      "appliedRate": 0.1709,
      "status": "applied"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger

Total de linhas.

items[].sourcestring

Fonte que respondeu.

items[].rawRatenumber

Cotação bruta, em moeda principal por unidade estrangeira.

items[].marginPctnumber

Margem usada.

items[].appliedRatenumber

Taxa gravada.

items[].statusstring

applied, unchanged, failed ou blocked_variation.

items[].errorstring

Motivo, quando falhou.

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

Veja também

Moedas

API atual/Referência completa/Moedas

Taxas de câmbio

Atualiza a taxa de uma moeda agora a partir da cotação oficial e consulta o histórico de cada tentativa.

Com autoUpdate ligado, a plataforma atualiza a taxa sozinha. Estas duas rotas deixam você disparar a atualização na hora e auditar o que aconteceu.

Atualizar a taxa agora

POST/api/v1/admin/currencies/{code}/refresh-rateAdmin

Atualiza a taxa agora

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Exemplo de requisição

bash

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

Resposta

200Resultado da atualização

json

{
  "code": "EUR",
  "status": "applied",
  "appliedRate": 0.1712
}

Campos da resposta

codestring

Moeda.

statusstring

appliedunchangedfailedblocked_variation

applied (nova taxa gravada), unchanged (mesma taxa), failed (fonte indisponível) ou blocked_variation (variação maior que 15%, taxa mantida).

appliedRatenumber

Taxa em vigor depois da tentativa.

errorstring

Presente quando status é failed.

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"}`
422	Tentativa de atualizar a moeda principal.	`{"error":"primary currency rate is fixed at 1.0","detail":"..."}`
500	Moeda não cadastrada ou erro interno.	`{"error":"failed to refresh rate","detail":"currency XXX not enabled"}`

Consultar o histórico

Uma linha por tentativa de atualização (automática ou manual), da mais recente para a mais antiga.

GET/api/v1/admin/currencies/{code}/rate-historyAdmin

Histórico de taxas

Parâmetros de caminho

codestringobrigatório

Código da moeda.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200; fora disso vale 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/currencies/EUR/rate-history?page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Histórico

json

{
  "items": [
    {
      "createdAt": "2026-10-11T12:00:00Z",
      "source": "ptax",
      "rawRate": 5.85,
      "marginPct": 0,
      "appliedRate": 0.1709,
      "status": "applied"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger

Total de linhas.

items[].sourcestring

Fonte que respondeu.

items[].rawRatenumber

Cotação bruta, em moeda principal por unidade estrangeira.

items[].marginPctnumber

Margem usada.

items[].appliedRatenumber

Taxa gravada.

items[].statusstring

applied, unchanged, failed ou blocked_variation.

items[].errorstring

Motivo, quando falhou.

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

Veja também

Moedas