Wielowalutowe fakturowanie subskrypcji: praktyczne reguły zaokrąglania i minimalny model danych, aby sumy były zgodne na webie, w aplikacji i w eksportach księgowych.
Częsty ból głowy: checkout na stronie pokazuje jedną sumę, aplikacja mobilna nieznacznie inną, a eksport księgowy daje trzecią wartość. Każdy system robi „rozsądne” obliczenia, ale nie te same.
Subskrypcje pogarszają sprawę, bo powtarzasz obliczenia wielokrotnie. Małe różnice kumulują się przy odnowieniach, proration przy upgrade’ach w trakcie okresu, kredytach i zwrotach, ponownych obciążeniach po nieudanych płatnościach i okresach częściowych na początku lub końcu planu.
Dryf zazwyczaj zaczyna się od drobnych wyborów, które pozostają niewidoczne, dopóki nie staną się problemem: kiedy zaokrąglać (na pozycji czy na końcu), jaka jest baza podatkowa (netto vs brutto), jak obsługiwać waluty z 0 lub 3 miejscami dziesiętnymi oraz jaki kurs FX zastosować (jaki znacznik czasu, które źródło, jaka precyzja). Jeśli web zaokrągla po 2 miejscach na każdej linii, a mobilka robi to dopiero dla całkowitej sumy, można dostać różnicę 0,01 nawet przy tych samych danych wejściowych.
Cel jest nudny, ale ważny: ta sama faktura powinna dawać te same sumy wszędzie, za każdym razem. To uspokaja klientów, zmniejsza zgłoszenia do supportu i sprawdza się w audytach.
„Spójne” oznacza, że dla danego ID faktury i wersji:
Przykład: klient przechodzi z EUR 19.99 na EUR 29.99 w połowie miesiąca, dostaje prorowane obciążenie, potem drobny kredyt za przestój. Jeśli jeden system zaokrągla każdą pozycję prorowaną, a inny tylko końcową sumę, eksportowana faktura może nie zgadzać się z tym, co widział klient, choć każda liczba wydaje się „wystarczająco bliska”.
Zanim zaczniesz dyskutować o kursach FX czy zasadach zaokrąglania podatku, ustabilizuj podstawy. Jeśli one są rozmyte, faktury będą się rozjeżdżać między aplikacją web, mobilną i eksportami księgowymi.
Każda pozycja faktury i suma faktury powinna jasno zawierać trzy kwoty: netto (przed podatkiem), podatek i brutto (netto + podatek). Wybierz jedną jako źródło prawdy do przechowywania i obliczeń, a pozostałe pochodnie obliczaj tak samo wszędzie. Wiele zespołów przechowuje netto i podatek, a potem liczy brutto jako netto + podatek, ponieważ ułatwia to audyty i zwroty.
Bądź jawny co do tego, w jakiej walucie jest każda liczba. Zespoły często mieszają trzy różne pojęcia:
Mogą być takie same, ale nie muszą. Jeśli faktura jest w EUR, a karta rozlicza w USD, faktura nadal musi być spójna w EUR, nawet jeśli wpłata bankowa różni się.
Następnie traktuj pieniądze jako liczby całkowite w jednostkach drobnych (np. grosze). Przechowywanie 9.99 jako liczby zmiennoprzecinkowej to częsty sposób na problemy typu 9.989999 później, szczególnie kiedy doliczasz podatek, rabaty, proration czy wiele pozycji. Przechowuj 999 (groszy) z kodem waluty i formatuj dopiero do wyświetlenia.
Na koniec, zdecyduj o trybie podatkowym cen:
Konkretny check: plan pokazany jako 10.00 (brutto, 20% VAT) powinien wygenerować tę samą zapisaną kwotę brutto w jednostkach drobnych na web i mobile, a potem netto i podatek powinny być pochodne zgodnie z jedną wspólną regułą.
Różnice FX często zaczynają się zanim porozmawiasz o podatkach i zaokrąglaniu. Dwa systemy mogą być „w porządku” i nadal się nie zgadzać, bo użyły różnych źródeł, różnych znaczników czasu lub różnych precyzji.
Dostawcy kursów rzadko się zgadzają co do ostatniego miejsca. Jedni podają kursy mid-market, inni doliczają spread. Jedni aktualizują co minutę, inni co godzinę czy dzień. Nawet przy tym samym dostawcy, jeden system może zaokrąglać kurs do 4 miejsc, a drugi trzymać 8+, co zmienia sumy po pomnożeniu kwot subskrypcji i podatków.
Najważniejsza decyzja to, co oznacza znacznik czasu kursu. Jeśli pobierasz w EUR, a klient płaci w USD, czy przypinasz kurs przy wystawieniu faktury, czy przy zaksięgowaniu płatności? Oba są powszechne, ale mieszanie ich między web, mobile i eksportami gwarantuje niezgodności.
Gdy już wybierzesz regułę, zapisz dokładny kurs, którego użyto, na fakturze. Nie przeliczaj później z „aktualnych” kursów, nawet jeśli możesz znaleźć historyczne tabele. Korekty dostawcy, różnice stref czasowych i drobne zmiany precyzji sprawią, że stare faktury będą się rozjeżdżać przy eksportach lub regeneracji PDF-ów.
Prosty przykład: wystawiasz fakturę o 23:59, ale płatność udaje się o 00:02. Te znaczniki czasu często wypadają w różnych „dniach” u dostawcy, więc dzienny tabela kursów może dać inne liczby.
Zdecyduj i udokumentuj te szczegóły FX:
Przypadki specjalne do obsłużenia od początku: waluty bez miejsc dziesiętnych (jak JPY), bardzo precyzyjne kursy i zwroty. Zwroty powinny generalnie używać oryginalnego kursu zapisanego na fakturze. W przeciwnym razie kwota zwrotu może różnić się od oczekiwanej przez klienta i od eksportu księgowego.
Jeśli chcesz, żeby faktury zgadzały się w web, mobile i eksportach, model danych musi przechowywać wyniki, nie tylko dane wejściowe. Cel jest prosty: ta sama faktura powinna renderować te same jednostki drobne wszędzie, nawet miesiące później.
Niewielki zestaw encji zwykle wystarczy:
Kluczowa zasada: pola z pieniędzmi powinny być liczbami całkowitymi w jednostkach drobnych. Przechowuj zarówno cenę jednostkową, jak i policzone kwoty linii. To zapobiega późniejszym przeliczeniom z inną regułą zaokrąglania lub innym źródłem FX.
FX musi być zapisany na fakturze, nie wnioskowany. Nawet jeśli masz wspólną tabelę kursów, faktura powinna zachować dokładny fx_rate_value użyty przy finalizacji (i skąd pochodził), aby eksporty mogły odtworzyć te same liczby.
Potrzebujesz osobnej tabeli rozbicia podatku tylko wtedy, gdy jedna faktura może mieć wiele stawek lub jurysdykcji jednocześnie (np. mieszane pozycje, VAT UE + lokalna opłata, albo zmiany podatku zależne od adresu w obrębie jednej faktury). Wtedy zapisz po jednej linii na stawkę podatkową z taxable_base_minor i tax_amount_minor.
Na koniec: traktuj sfinalizowaną fakturę jako niemodyfikowalną. Zapisz migawkę policzonych wartości w momencie, gdy stanie się finalna, i nigdy nie przeliczaj sum z subskrypcji później. Ten wybór eliminuje większość błędów „dlaczego grosze się zmieniły?”.
Zaokrąglanie to nie matematyczny szczegół. To reguła produktu. Jeśli web zaokrągla pewnie, mobilka inaczej, a eksport księgowy trzecią metodą, dostaniesz różne sumy, nawet gdy dane wejściowe są identyczne.
Są trzy powszechne strategie, które różnią się punktem, w którym „zablokowujesz” jednostki drobne:
Dla subskrypcji dobrym domyślnym wyborem jest zaokrąglanie na linii. Jest przewidywalne dla klientów (każda pozycja wygląda „poprawnie”), łatwe do audytu (możesz wytłumaczyć każdą kwotę linii) i stabilne przy odnowieniach. Zaokrąglanie na jednostce może dryfować przy zmianie ilości lub gdy pokazujesz ceny jednostkowe w UI. Zaokrąglanie tylko całej sumy często wywołuje pytania „dlaczego ta pozycja się nie sumuje?”, bo widoczne sumy linii nie zgadzają się z pokazanym totalem.
Klasyczny problem z groszami pojawia się przy wielu małych pozycjach lub ułamkowych podatkach. Przykład: 20 pozycji każda daje 0.004 reszty zaokrąglenia. Zaokrąglając na linii, to może dać 0.08 różnicy w porównaniu z zaokrągleniem dopiero na końcu. Przy konwersjach FX te drobne reszty pojawiają się częściej i kumulują się w eksportach i raportach przychodów.
Cokolwiek wybierzesz, niech będzie deterministyczne. Te same dane wejściowe muszą zawsze dawać te same wyniki w web, mobile i eksportach:
Jeśli budujesz równoległe flowy billingowe dla web i mobile, zapisz regułę zaokrąglania jako testowalną specyfikację, nie jako zachowanie UI.
Aby zachować te same liczby w web, mobile i w eksportach księgowych, traktuj obliczenie jak przepis. Kluczowa idea: licz z wysoką precyzją, ale zapisuj i sumuj tylko liczby całkowite w walucie faktury.
Zacznij od każdej pozycji z kwotą netto w wysokiej precyzji. Zachowaj dodatkowe miejsca dziesiętne podczas mnożenia przez ilość, stosowania rabatów i (jeśli potrzeba) konwersji waluty. Potem zaokrąglij raz do jednostek drobnych waluty faktury zgodnie z wybraną regułą. Zapisz tę liczbę całkowitą jako line_net.
Oblicz podatek od zapisanego line_net (lub od subtotalu grupy podatkowej, jeśli reguły pozwalają na grupowanie po stawce). Zastosuj tę samą regułę zaokrąglenia i zapisz podatek jako liczbę całkowitą w jednostkach drobnych. To jest miejsce, gdzie systemy często się rozjeżdżają: jedna strona zaokrągla przed podatkiem, druga po.
Oblicz brutto każdej linii jako (zapisane netto + zapisany podatek). Sumy faktury to sumy zapisanych jednostek drobnych. Nie przeliczaj sum z wartości zmiennoprzecinkowych do wyświetlania. Widoki i eksporty powinny czytać zapisane liczby całkowite i je formatować.
Jeśli lokalne reguły wymagają sum podatkowych na poziomie faktury, może być konieczne rozdzielenie reszty. Przykład: trzy linie po 0.01 podatku każda mogą dać 0.03, ale zaokrąglenie na poziomie faktury mówi 0.02. Zdecyduj deterministyczną regułę rozstrzygania (np. dodawaj lub odejmuj 1 jednostkę drobną zaczynając od największej opodatkowanej linii, potem stabilnie sortuj po ID linii). Zapisz korektę jako małą korektę podatkową na dotkniętych liniach, aby każdy system mógł to odtworzyć.
Zablokuj fakturę. Po ostatecznym zaokrągleniu i redystrybucji reszty traktuj fakturę jako niemodyfikowalną. Jeśli cena subskrypcji zmieni się później, wystaw nową fakturę lub notę kredytową, ale nigdy nie przepisuj starych liczb.
Konkretny check: jeśli plan EUR 9.99 ma 19% VAT, twoje zapisane netto może być 999 groszy, podatek 190 groszy, brutto 1189 groszy. Każdy klient powinien renderować 11,89 EUR z tych zapisanych liczb całkowitych, a nie przez ponowne obliczanie VAT na żywo.
Zaokrąglanie podatku to miejsce, gdzie poprawna matematyka zamienia się w niezgodne faktury. Główna kwestia jest prosta: wcześniejsze zaokrąglenie zmienia końcowy wynik.
Jeśli zaokrąglasz podatek per pozycja (lub per ilość), a potem sumujesz, możesz dostać inną sumę niż gdy zsumujesz niezaokrąglony podatek dla całej faktury i zaokrąglisz raz na końcu. Przy wielu pozycjach różnice się sumują, szczególnie gdy jednostki drobne i konwersje FX już tworzą małe ułamki.
Konkretny przykład (2 miejsca): dwie pozycje mają każda podstawę opodatkowania 0.05 przy stawce 10%. Niezaokrąglony podatek na linii to 0.005. Jeśli zaokrąglasz per linia, każda stanie się 0.01, więc suma podatku to 0.02. Jeśli zaokrąglasz na poziomie faktury, suma podstaw to 0.10, podatek to 0.01. Obie metody są bronione. Po prostu się nie zgadzają.
Gdy musisz pokazać podatek per linia, a jednocześnie suma faktury ma się zgadzać dokładnie, alokuj resztę deterministycznie:
Eksporty mogą nadal dryfować, gdy księgowo grupują pozycje (po produkcie, stawce podatku, jurysdykcji). Aby eksporty i suma faktury się zgadzały, alokuj reszty w ramach każdej wymaganej grupy najpierw, potem zweryfikuj, że sumy grup składają się do tej samej sumy podatku i brutto faktury.
Jeśli księgowo wymaga podziału podatku po stawkach lub jurysdykcjach, ale UI pokazuje jedną liczbę podatku, i tak zapisz rozbicie (suma per stawka/jurysdykcja plus audytowalna reguła alokacji). UI może wyświetlać jedną sumę, a eksporty niosą szczegółowe kubełki bez zmiany łącznej sumy faktury.
Większość rozbieżności faktur pojawia się na brzegach. Ustal reguły wcześnie, a przestaną Cię zaskakiwać.
Waluty bez miejsc dziesiętnych wymagają szczególnej uwagi. JPY i KRW nie mają jednostek drobnych, więc każdy krok zakładający „grosze” cicho stworzy różnice. Zdecyduj, czy zaokrąglać na każdej linii, na poziomie podatku czy tylko przy sumie, i upewnij się, że każdy klient używa tych samych ustawień waluty.
VAT transgraniczny lub GST może zmieniać stawkę podatku w zależności od lokalizacji klienta i od dowodów, które akceptujesz (adres rozliczeniowy, IP, NIP). Trudność nie polega na samej stawce, lecz na tym, kiedy ją „zamrażasz”. Wybierz punkt w czasie (checkout, data wystawienia faktury lub początek okresu świadczenia) i się go trzymaj.
Proration to miejsce, gdzie ułamki mnożą się. Upgrade w trakcie cyklu może dać kwoty typu 9.3333... za dzień. Zdecyduj, czy prorytujesz kwoty netto, brutto, czy najpierw okres usługi, a potem oblicz resztę. Zmiana kolejności zmienia ostatnią jednostkę drobną.
Zapisz te zasady, aby nie dryfowały w czasie:
Zwroty to ostateczna pułapka. Jeśli oryginalna faktura miała 0.01 reszty rozdysponowanej na jedną pozycję, zwrot powinien odwrócić tę dokładną alokację. W przeciwnym razie klient widzi jedną sumę, a twój dziennik wykazuje inną.
Większość rozbieżności faktur nie jest wynikiem „trudnej matematyki”. Pochodzą z małych, niespójnych wyborów w różnych częściach stacku.
Duży błąd to przechowywanie pieniędzy jako liczb zmiennoprzecinkowych. Wartość 19.99 nie może być dokładnie reprezentowana w wielu systemach, więc drobne błędy narastają przy sumowaniu linii, stosowaniu rabatów czy obliczaniu podatku. Przechowuj kwoty jako całkowite w jednostkach drobnych oraz kod waluty i skalę jednostek drobnych.
Inny częsty problem to ponowne obliczanie FX podczas eksportu. Klient zapłacił w oparciu o konkretny kurs w określonym czasie. Jeśli eksport księgowy pobiera „dzisiejszy” kurs, możesz otrzymać inną sumę, nawet jeśli każdy krok był poprawny. Traktuj fakturę jako snapshot: zapisz kurs FX użyty, przeliczone kwoty i wyniki zaokrąglania.
Różnice zaokrąglania pojawiają się też, gdy UI i backend zaokrąglają na różnych etapach. Na przykład backend może zaokrąglać podatek per linia, a UI tylko przy sumie faktury. Obie metody mogą wyglądać sensownie, ale nie będą się zgadzać.
Pięć powtarzających się winowajców wyjaśnia większość rozjazdów:
Szybka naprawa jest nudna, ale skuteczna: policz raz na backendzie, zapisz pełną migawkę faktury, a web i mobile renderuj dokładnie te zapisane liczby.
Gdy liczby różnią się między web, mobile i eksportami księgowymi, zwykle nie jest to problem matematyczny. To problem przechowywania i zaokrąglania.
Zacznij od zasady, że klienci powinni wyświetlać to, co faktura przechowuje, a nie przeliczać to samodzielnie. Backend powinien być jedynym źródłem prawdy, a każdy kanał czytać te same zapisane wartości.
Zwroty i noty kredytowe powinny odzwierciedlać oryginalne wyniki zaokrąglania faktury. Jeśli oryginalna faktura zaokrąglała podatek per linia, zwrot powinien robić to samo, używając tej samej precyzji waluty i zapisanego kursu FX. W przeciwnym razie mogą pojawić się drobne resztki, które będą się kumulować.
Praktyczny sposób wymuszenia tego to zapisanie wyraźnej migawki obliczeń z każdą fakturą: waluta, precyzja jednostek drobnych, tryb zaokrąglania, kurs FX i jego znacznik czasu oraz sfinalizowane kwoty linii.
Oto jedna faktura, która pozostaje spójna wszędzie.
Załóżmy, że faktura jest w EUR (2 miejsca), VAT 20%, i klient jest obciążony w USD. Backend zapisuje migawkę FX: 1 EUR = 1.0857 USD.
| Item | Net (EUR) |
|---|---|
| Pro plan (monthly) | 19.99 |
| Extra seats | 10.00 |
| Discount (10% of 29.99, rounded) | -3.00 |
Net total (EUR) = 26.99
VAT 20% (EUR) = 5.40 (bo 26.99 x 0.20 = 5.398, zaokrąglone do 5.40)
Gross total (EUR) = 32.39
Teraz backend wyprowadza sumy w walucie obciążenia z zapisanych sum EUR i zapisanego snapshotu FX:
Jeśli zapisujesz też kwoty per linię w USD, często pojawi się różnica 0.01, gdy zaokrąglasz każdą przeliczoną linię i potem je sumujesz. To właśnie miejsce, gdzie faktury zwykle się rozjeżdżają.
Uczyń to deterministycznym: przelicz i zaokrąglaj każdą linię, potem rozdziel wszelkie pozostałe centy (dodatnie lub ujemne) w ustalonym porządku (np. po line_id rosnąco), aż suma per-linia równa się już ustalonej brutto sumie w USD.
Web i mobile powinny wyświetlać zapisane przez backend sumy linii, sumy podatków, kurs FX i brutto, zamiast ich ponownego przeliczania. Eksport księgowy powinien wypuścić te same zapisane liczby plus migawkę FX (kurs, znacznik czasu lub źródło), aby księgi zgadzały się z tym, co widział klient.
Praktyczny następny krok to zaimplementowanie obliczeń jako jednej współdzielonej usługi, która wygeneruje jedną migawkę faktury (linie, podatki, sumy, FX, korekty zaokrąglenia) i sprawić, by każdy kanał renderował z niej. Jeśli budujesz te flowy na Koder.ai (koder.ai), model migawki pomaga web, mobile i eksportom pozostać zgodnymi, bo wszyscy czytają te same zapisane wartości.
Ponieważ każdy system często podejmuje nieco inne decyzje o tym kiedy zaokrąglać, co zaokrąglać (netto vs brutto) i jaką precyzję zachować dla podatków i kursów FX. Te drobne różnice pokazują się jako 0,01–0,02 rozbieżności, zwłaszcza gdy proration, kredyty i ponowne obciążenia powtarzają obliczenia.
Przechowuj kwoty jako liczby całkowite w jednostkach drobnych (np. grosze) wraz z kodem waluty i formatuj je tylko do wyświetlenia. Liczby zmiennoprzecinkowe nie reprezentują wielu dziesiętnych dokładnie, więc pojawiają się drobne błędy przy dodawaniu podatków, rabatów czy wielu pozycji.
Wybierz jedno pole jako źródło prawdy i w ten sam sposób pochodne obliczaj wszędzie. Częstym wyborem jest przechowywanie netto i podatku w jednostkach drobnych, a potem obliczanie brutto = netto + podatek, bo ułatwia to zwroty i audyt.
Waluta faktury to waluta, w której prawnie wyrażone są sumy faktury i do niej powinieneś się odnosić przy rozliczeniach. Waluta wyświetlania to ta pokazywana przy przeglądaniu cen, a waluta rozliczenia to ta, którą wpłaca dostawca płatności; mogą się różnić bez błędu faktury, pod warunkiem że obliczenia w walucie faktury pozostają spójne.
Nie pobieraj kursów przy eksporcie ani przy regeneracji PDF-ów. Zapisz dokładny kurs FX użyty przy fakturze (wartość, precyzja, dostawca i czas obowiązywania), a potem zawsze go używaj, żeby stare faktury odtwarzały te same liczby miesiącami później.
Wybierz jedną regułę: albo „kurs z czasu wystawienia faktury”, albo „kurs z chwili zaksięgowania płatności”, i stosuj ją wszędzie. Mieszanie znaczników czasu między systemami często powoduje rozbieżności, szczególnie przy przejściu przez północ i strefy czasowe.
Domyślnie zaokrąglaj na poziomie linii dla faktur subskrypcyjnych, a potem sumuj zapisane kwoty linii. To zazwyczaj najłatwiej wytłumaczyć klientom, unika zgłoszeń typu „pozycje się nie sumują” i jest stabilne przy odnowieniach, jeśli każdy kanał używa tej samej reguły.
Wybierz jawnie zaokrąglanie podatku per linia albo na poziomie faktury i uczynij je deterministycznym. Jeśli musisz dopasować się do wartości całej faktury, rozdziel resztę w sposób ustalony i zapisz powstałe wartości podatku dla każdej linii, aby każdy system mógł pokazać ten sam wynik.
Proration generuje ułamki dziesiętne (np. stawki dzienne), więc kolejność operacji ma znaczenie. Wybierz jedną metodę (np. najpierw prorytuj netto, potem policz podatek od zapisanego netto), zaokrąglaj w ustalonym kroku i zapisz sfinalizowane kwoty linii, by upgrade’y, downgrade’y, kredyty i zwroty odzwierciedlały oryginalne obliczenia.
Niech backend wygeneruje sfinalizowaną migawkę faktury (linie, podatki, sumy, zasady jednostek drobnych, migawka FX, tryb zaokrąglania) i traktuj ją jako niezmienną po finalizacji. Web, mobile, PDF-y i eksporty powinny renderować te zapisane liczby zamiast przeliczać je samodzielnie; to też dobry wzorzec przy budowaniu rozliczeń na Koder.ai.
