Dokumentation

API-Dokumentation

Die API stellt Endpunkte zum Abruf einzelner Monatskurse, vollständiger Jahresreihen, Jahresdurchschnitte, Zeiträume und zur direkten Währungsumrechnung bereit. Alle Endpunkte erwarten einen Bearer Token im Authorization-Header.

Authentifizierung

Senden Sie Ihren API-Schlüssel im Authorization-Header bei jeder Anfrage an /api/v1/*. Tokens beginnen mit ukk_ und werden manuell ausgestellt.

curl -H "Authorization: Bearer ukk_…" \
  https://ukk-api.xevieso.com/api/v1/currencies

Anfragegrenze

60 Anfragen pro Minute pro API-Schlüssel im gleitenden Zeitfenster. Bei Überschreitung wird 429 mit Retry-After zurückgegeben. Antworten enthalten X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.

Endpunkte

Währungen auflisten

GET/api/v1/currencies

Liefert alle bekannten Währungen mit ISO-Code und Bezeichnung.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  https://ukk-api.xevieso.com/api/v1/currencies

{
  "currencies": [
    { "code": "USD", "name": "US-Dollar" },
    { "code": "GBP", "name": "Pfund Sterling" }
  ]
}

Monatskurs abrufen

GET/api/v1/rates/monthly

Liefert den Monatskurs einer Währung. Wird nur year angegeben, werden alle bisherigen Monate des Jahres zurückgegeben.

currency *: ISO-Code (z. B. USD).
year *: Vierstelliges Jahr.
month: 1–12. Bei Auslassung: alle verfügbaren Monate des Jahres.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates/monthly?currency=USD&year=2024&month=3"

{
  "currency": "USD",
  "year": 2024,
  "month": 3,
  "rate": "1.08720000",
  "isFinal": true
}

Jahresdurchschnitt abrufen

GET/api/v1/rates/yearly

Liefert den Jahresdurchschnitt, sobald alle zwölf Monate des Jahres als final bestätigt sind.

currency *: ISO-Code.
year *: Vierstelliges Jahr.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates/yearly?currency=USD&year=2024"

{
  "currency": "USD",
  "year": 2024,
  "rate": "1.08205000"
}

Zeitraum abrufen

GET/api/v1/rates

Liefert alle Monatskurse einer Währung in einem geschlossenen Zeitraum.

currency *: ISO-Code.
from *: Startmonat im Format YYYY-MM.
to *: Endmonat im Format YYYY-MM.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/rates?currency=GBP&from=2024-01&to=2024-06"

{
  "currency": "GBP",
  "rates": [
    { "year": 2024, "month": 1, "rate": "0.85230000", "isFinal": true },
    { "year": 2024, "month": 2, "rate": "0.85510000", "isFinal": true }
  ]
}

Betrag umrechnen

GET/api/v1/convert

Rechnet einen Betrag zum Monatskurs zwischen zwei Währungen um. Mindestens eine Seite muss EUR sein.

amount *: Numerischer Betrag.
from *: ISO-Code der Quellwährung.
to *: ISO-Code der Zielwährung.
year *: Vierstelliges Jahr.
month *: 1–12.

curl -H "Authorization: Bearer $UKK_TOKEN" \
  "https://ukk-api.xevieso.com/api/v1/convert?amount=100&from=USD&to=EUR&year=2024&month=3"

{
  "amount": 100,
  "from": "USD",
  "to": "EUR",
  "year": 2024,
  "month": 3,
  "converted": "91.9794",
  "rate": "0.91979..."
}

Fehlercodes

200: Erfolg.
400: Ungültige Parameter (Zod-Validierung).
401: Token fehlt oder ist ungültig/widerrufen.
404: Keine Daten für die angefragte Periode/Währung.
429: Anfragegrenze überschritten.
500: Interner Fehler.

Caching

Antworten enthalten Cache-Control. Da Monatskurse nach Veröffentlichung stabil sind, sind clientseitige Caches mit Stunden- oder Tagesgranularität sinnvoll.