Kod waluty – co to jest i jak sprawdzić oznaczenia walut?

Kod waluty to nie to samo co kurs waluty. Kod, na przykład EUR, identyfikuje euro, natomiast kurs określa jego wartość w złotych i musi zostać zapisany w danych faktury. Sprawdzenie oznaczenia oraz pobranie właściwego kursu z API NBP pozwala uniknąć błędu o zerowym kursie w KSeF.

Kod waluty – co oznacza?

Kod waluty jest krótkim, najczęściej trzyliterowym oznaczeniem jednostki pieniężnej. Obowiązuje go standard ISO 4217, który porządkuje nazwy, symbole oraz kody walut używane w rozliczeniach międzynarodowych. Przykładowo PLN oznacza polskiego złotego, EUR euro, USD dolara amerykańskiego, a GBP funta szterlinga.

Pierwsze dwie litery kodu zwykle nawiązują do państwa lub obszaru walutowego, a ostatnia wskazuje jednostkę pieniężną. Nie jest to jednak reguła bez wyjątków. Kod XAU oznacza złoto wyrażone w uncjach trojańskich, XDR specjalne prawa ciągnienia Międzynarodowego Funduszu Walutowego, a XXX brak waluty.

Gdzie sprawdzić oznaczenie waluty?

Najpewniejszym źródłem dla zastosowań księgowych i informatycznych jest tabela zgodna z ISO 4217. W dokumentach handlowych należy używać kodu trzyliterowego, a nie samego znaku graficznego. Symbol $ może oznaczać między innymi dolara amerykańskiego, kanadyjskiego, australijskiego, hongkońskiego albo nowozelandzkiego.

Podobny problem dotyczy znaku ¥. W praktyce oznacza on zarówno jena japońskiego, jak i juana chińskiego. Dopiero kod JPY lub CNY jednoznacznie identyfikuje walutę. Węgierski forint ma kod HUF i symbol Ft, a rand południowoafrykański występuje jako ZAR oraz R.

Najczęściej mylone oznaczenia

Przed zapisaniem waluty sprawdź trzy elementy – pełną nazwę, kod ISO i symbol. Taki zestaw ogranicza ryzyko pomyłki przy fakturach, przelewach oraz imporcie danych do programu finansowego.

• dolar amerykański – USD – $
• dolar kanadyjski – CAD – $
• dolar australijski – AUD – $
• juan chiński – CNY – ¥
• jen japoński – JPY – ¥
• korona czeska – CZK – Kč

Kod waluty a kurs waluty – jaka jest różnica?

Kod odpowiada na pytanie, w jakiej walucie wystawiono dokument. Kurs wskazuje, ile ta waluta jest warta względem waluty rozliczeniowej, najczęściej złotego. Faktura w EUR powinna więc zawierać nie tylko oznaczenie EUR, lecz także kurs euro zastosowany do przeliczenia wartości na PLN.

Kod EUR identyfikuje euro, ale nie określa jego wartości. Do przeliczenia faktury potrzebny jest osobny kurs waluty, na przykład 4,3189 PLN za 1 EUR.

W tabelach NBP kurs może dotyczyć jednej jednostki albo większej liczby jednostek. Dla euro, dolara i franka szwajcarskiego podaje się zwykle 1 jednostkę. W przypadku jena japońskiego często stosuje się 100 JPY, a dla forinta węgierskiego 100 HUF. Program księgowy musi znać zarówno kod, jak i podstawę kursu.

Jak pobrać kurs waluty z API NBP?

Serwis api.nbp.pl udostępnia publiczne Web API pod adresem bazowym https://api.nbp.pl/api/. Od 1 sierpnia 2025 r. wszystkie zapytania muszą korzystać z protokołu HTTPS. W tym dniu HTTP zostało zastąpione przez bezpieczne połączenie szyfrowane.

Dane można pobierać jako JSON albo XML. Jeżeli nie wskażesz formatu, API zwróci domyślnie JSON. Format określa parametr `?format=json` lub nagłówek `Accept: application/json`.

Zapytanie o pojedynczy kurs

Do pobrania kursu euro z tabeli A służy adres:

https://api.nbp.pl/api/exchangerates/rates/a/eur/today/?format=json

Dla konkretnej daty można użyć schematu:

https://api.nbp.pl/api/exchangerates/rates/a/eur/2026-08-18/?format=json

Parametr `a` wskazuje typ tabeli, a `eur` jest kodem waluty. Datę zapisuje się w formacie RRRR-MM-DD, zgodnym z ISO 8601. Zakres historyczny może obejmować najwyżej 93 dni w jednym zapytaniu.

Odpowiedzi i błędy API

Nie każda poprawna technicznie ścieżka zwróci kurs. Dzień wolny, brak publikacji tabeli albo nieistniejąca data mogą zakończyć się komunikatem 404. Błąd składni adresu lub przekroczenie limitu danych wywoła odpowiedź 400.

Dlaczego sam kod waluty nie wystarcza w KSeF?

W fakturze walutowej kod pełni funkcję identyfikacyjną, lecz system rozliczeniowy potrzebuje też liczbowego kursu dokumentu. Jeżeli program odbiorcy zaimportuje EUR, ale pole kursu pozostanie puste albo przyjmie wartość 0, może wyświetlić komunikat: „ujemny lub zerowy kurs waluty”.

KSeF może przyjąć fakturę, gdy system wystawcy wcześniej przeliczył kwoty na złote. Nie oznacza to jednak, że każdy program odbiorcy poprawnie odtworzy kurs na podstawie samego kodu EUR. Kurs wpisany wyłącznie w uwagach jest zwykłym tekstem i często nie trafia do pola przeznaczonego na dane liczbowe.

Na fakturze walutowej powinny znaleźć się co najmniej: kod waluty, kwota w walucie obcej, kurs przeliczeniowy, data kursu oraz wartości w PLN, jeśli wymagają ich zasady rozliczenia.

Przy eksporcie dokumentu sprawdź mapowanie pól. Kod EUR powinien trafić do pola waluty, a wartość, na przykład 4,3189, do pola kursu. Trzeba też uwzględnić mnożnik, gdy NBP publikuje notowanie za 100 JPY lub 100 HUF.

Co sprawdzić przed wysłaniem faktury?

Kontrola dokumentu może obejmować następujące elementy:

1. ustal, czy kod waluty odpowiada nazwie na fakturze,
2. pobierz kurs z właściwej tabeli NBP i właściwego dnia,
3. zapisz kurs jako liczbę, a nie jako komentarz w uwagach,
4. sprawdź podstawę notowania, na przykład 1 EUR albo 100 JPY,
5. zweryfikuj, czy eksport przekazuje pole kursu do programu odbiorcy,
6. wykonaj próbny import dokumentu przed wysyłką do KSeF.

Jak zapisać walutę na fakturze?

Najczytelniejszy zapis łączy nazwę i kod, na przykład euro (EUR), dolar amerykański (USD) albo frank szwajcarski (CHF). Sam symbol może pozostać elementem wizualnym, lecz nie powinien zastępować kodu w pliku wymiany danych. Dotyczy to szczególnie faktur przesyłanych między różnymi systemami księgowymi.

W 2026 roku warto także sprawdzić aktualność słownika walut w programie. Niektóre kody zmieniały się wraz z reformami walutowymi, a część oznaczeń dotyczy jednostek rozliczeniowych, metali szlachetnych lub instrumentów technicznych, nie zaś pieniędzy używanych w obrocie detalicznym.