Obsługa walut i podatków to jeden z najważniejszych obszarów każdego systemu e-commerce B2B i B2C. To od poprawnej konfiguracji płatności, kursów wymiany, stawek podatkowych i sposobu liczenia VAT zależy nie tylko to, co zobaczy klient w koszyku, ale też spójność raportowania, integracji z ERP i obsługi zamówień.
W tym tekście wyjaśnię, jak działa obsługa walut oraz mechanizm podatkowy w Syliusie, na czym opiera się logika przeliczania cen, czym różni się waluta bazowa od walut dostępnych dla klientów i w jaki sposób framework oblicza podatki dla konkretnych pozycji koszyka.
Konfiguracja dostępna jest w panelu administracyjnym w sekcji Configuration → Currencies. Z tego miejsca administrator może dodać do systemu waluty, które będą później wykorzystywane w kanałach sprzedaży.
Samo dodanie pozycji do systemu jest proste: wystarczy wybrać ją z listy i zapisać konfigurację. Trzeba jednak pamiętać, że utworzenie waluty w konfiguracji globalnej nie oznacza jeszcze, że klient zobaczy ją w sklepie.
Dlatego po dodaniu należy przypisać ją do odpowiedniego kanału. To istotny krok, ponieważ Sylius od początku zakłada pracę z kanałami sprzedaży, a te mogą mieć różne ustawienia walutowe.
Każdy kanał sprzedaży w Syliusie posiada jedną walutę bazową, czyli Base Currency. To właśnie w niej przechowywane są ceny produktów w bazie danych.
Obok waluty bazowej kanał może mieć również skonfigurowaną listę dostępnych walut, czyli Currencies. Są to opcje, które klient może wybrać podczas korzystania ze sklepu. Przykładowo kanał może mieć bazową walutę PLN, ale jednocześnie umożliwiać klientom wyświetlanie cen w EUR albo USD.
To rozróżnienie jest kluczowe. W standardowym mechanizmie wielowalutowości Sylius nie przechowuje osobnej ceny produktu dla każdej waluty. Cena wariantu zapisana jest względem kanału, a ten posiada niezmienną walutę bazową. Wartości w pozostałych walutach są wynikiem przeliczenia. Jeśli projekt wymaga niezależnych cen w różnych walutach, nie jest to już zwykła konfiguracja, tylko osobna decyzja architektoniczna dotycząca pricingu.
Mechanizm wielowalutowości w Syliusie opiera się o Exchange Rate, czyli kurs wymiany. Podczas przeliczania system pobiera cenę źródłową i mnoży ją przez współczynnik ratio. Za sam proces odpowiada komponent CurrencyConverter.
Warto zwrócić uwagę na ważny szczegół: kursy wymiany w Syliusie są dwukierunkowe. Oznacza to, że kurs z PLN do EUR i kurs z EUR do PLN są traktowane jako ten sam wpis. Zapisujemy tylko jeden kurs, powiedzmy EUR → PLN. Jeżeli sklep będzie potrzebował przeliczenia PLN → EUR, po prostu przemnoży przez odwrócony mnożnik (1/mnożnik). Jeśli sklep ma obsługiwać przeliczenia w obu kierunkach w różnych kwotach, by móc zdefiniować spread, wymaga to osobnej implementacji.
Przeczytaj więcej: techniczna lista kontrolna cross-border e-commerce.
Podczas składania zamówienia Sylius zapisuje walutę, w której klient złożył zamówienie, w polu currencyCode. Jest to zawsze base currency danego kanału.
Ma to znaczenie przy bardziej zaawansowanych potrzebach biznesowych, takich jak raportowanie historycznych wartości, integracje księgowe, synchronizacja z ERP albo analiza różnic kursowych. Jeśli organizacja potrzebuje przechowywać kurs użyty w danym zamówieniu, warto uwzględnić to już na etapie projektowania architektury i ewentualnie rozszerzyć standardowy mechanizm.
Sylius nie posiada wbudowanego mechanizmu automatycznej aktualizacji kursów walut. Te mogą być aktualizowane ręcznie z poziomu panelu administracyjnego, za pomocą pluginów albo przez własną integrację, na przykład cykliczne zadanie pobierające dane z ECB lub NBP.
To nie jest przypadkowy brak funkcji, tylko świadoma decyzja architektoniczna. Framework nie uzależnia podstawowego działania systemu od konkretnego zewnętrznego API i nie narzuca jednego źródła danych walutowych. Dzięki temu zespół wdrożeniowy może sam zdecydować, skąd pobierać kursy, jak często je aktualizować i w jaki sposób kontrolować politykę przeliczania cen.
Mechanizm podatków w Syliusie opiera się na kilku pojęciach, które razem tworzą model obliczania VAT lub innych podatków sprzedażowych. Najważniejsze z nich to TaxCategory, TaxRate oraz TaxZone.
TaxCategory określa kategorię podatkową produktu. Może to być na przykład żywność, książki, elektronika albo dowolna inna grupa objęta określoną logiką podatkową.
TaxRate definiuje konkretną stawkę podatkową, która jest powiązana zarówno z kategorią podatkową, jak i ze strefą geograficzną. Dzięki temu ten sam typ produktu może mieć różne opodatkowanie w zależności od lokalizacji klienta lub rynku, na którym działa kanał sprzedaży.
Zone, czyli strefy, mogą między innymi być użyte do definicji podatków. Z perspektywy podatków strefa jest konieczna. Natomiast nie każda strefa może być użyta do podatków. Strefy posiadają „Zasięg" (Scope). Tylko scope „All" i „Tax" może być użyty w podatkach i odpowiadać za obszar geograficzny. Mechanizm ten opiera się o strefy, czyli Zone, które mogą składać się z krajów, prowincji albo innych stref.
Proces obliczania podatku w Syliusie przebiega wieloetapowo. Najpierw framework określa strefę klienta na podstawie adresu zamówienia. Wykorzystywany jest do tego mechanizm ZoneMatcherInterface, który dopasowuje adres do odpowiedniej strefy.
Następnie dla każdej pozycji koszyka system wyszukuje odpowiednią stawkę podatkową, czyli TaxRate, która pasuje do kategorii podatkowej produktu oraz strefy klienta. Jeśli system znajdzie właściwą stawkę, może przejść do obliczenia wartości podatku.
Samo obliczenie wykonywane jest przez kalkulator podatkowy, który odpowiada za wyliczenie konkretnych wartości i zastosowanie ich do pozycji koszyka lub zamówienia. W praktyce oznacza to, że logika podatkowa w Syliusie nie jest zaszyta w jednym miejscu, lecz wynika z konfiguracji kategorii, stawek, stref i typu kalkulatora.
Przy konfiguracji TaxRate dostępna jest flaga included in price? To ustawienie określa, czy podatek jest już zawarty w cenie produktu, czy powinien zostać doliczony do ceny na końcu procesu.
Jeżeli flaga jest aktywna, cena traktowana jest jako brutto. Jeśli flaga nie jest zaznaczona, cena traktowana jest jako netto.
To ustawienie powinno być dobrze przemyślane, szczególnie w projektach łączących sprzedaż B2B i B2C albo działających na wielu rynkach. Błędna konfiguracja może prowadzić do różnic w prezentacji cen, wartości koszyka, raportowaniu i danych przekazywanych do systemów zewnętrznych.
Sylius domyślnie udostępnia dwa kalkulatory podatkowe: DefaultCalculator oraz DecimalCalculator. Każdy z nich pełni inną rolę i może być używany w zależności od potrzeb projektu.
Zaokrągla wynik do pełnych groszy.
Zwraca wynik bez zaokrąglania.
Tak. Jedną z dużych zalet architektury Syliusa jest możliwość rozszerzania logiki podatkowej bez konieczności przebudowy całego mechanizmu. Jeśli projekt wymaga niestandardowego sposobu wyliczania podatków, można przygotować własny kalkulator implementujący odpowiedni interfejs.
W praktyce często oznacza to stworzenie osobnej klasy oraz zmianę konfiguracji kalkulatora w ustawieniach systemu i odpowiednich TaxRate. Dzięki temu własna logika może zostać wpięta w istniejący proces obliczeń, zamiast zastępować całość mechanizmu podatkowego.
| Element | Odpowiedzialność |
|---|---|
| Base Currency | Waluta bazowa kanału sprzedaży |
| Exchange Rate | Przeliczanie cen między walutami |
| CurrencyConverter | Mechanizm przeliczania wartości |
| TaxCategory | Kategoria podatkowa produktu |
| TaxRate | Stawka podatkowa |
| Zone | Obszar obowiązywania podatku |
| ZoneMatcherInterface | Dopasowanie klienta do strefy podatkowej |
| TaxCalculator | Wyliczanie wartości podatku |
Przeczytaj więcej: nasza historia z Syliusem.
Tak. Sylius pozwala przypisywać wiele walut do kanału sprzedaży i przeliczać ceny przy użyciu kursów wymiany.
Nie. Kursy walut można aktualizować ręcznie lub za pomocą własnych integracji i pluginów.
Framework określa strefę klienta, wyszukuje odpowiednią stawkę podatkową i używa kalkulatora do wyliczenia podatku dla pozycji koszyka.
Tak. Architektura frameworka pozwala rozszerzać logikę podatkową i implementować własne kalkulatory.
Nie. Standardowo Sylius składa zamówienie w walucie bazowej, więc nie tylko kurs, ale i widziana waluta nie zostaje zapisana.
Tak. Mechanizm TaxRate pozwala określić, czy podatek jest zawarty w cenie produktu, czy powinien zostać doliczony osobno.
W dynamicznym świecie e-commerce wybór platformy technologicznej nie jest już tylko decyzją o zestawie funkcji. Dla CTO ...
Czytaj więcej →
Wdrożenie Syliusa to nie tylko zmiana technologii, ale test dojrzałości całej organizacji. Nawet najlepszy framework nie...
Czytaj więcej →
Poznaj nowość Syliusa 1.13 – atrybuty – i sprawdź, jak wpływają na wygodę pracy programistów.
Czytaj więcej →
