Dokumentacja wfirma.pl

System wydruków

Wstęp

System wydruków wfirma.pl pozwala na definiowanie własnych szablonów faktur w języku XML. Obecnie możliwe jest definiowane szablonu 4 typów faktur: Faktura VAT, Faktura (bez VAT), Pro forma, Pro forma (bez VAT) oraz dwóch wariantów językowych - dokumentu w języku polskim i polsko-obcojęzycznym.

W pierwszej kolejności należy w zakładce Ustawienia » Szablony dodać nową grupę szablonów. System automatycznie utworzy dla 4 typów faktur predefiniowane szablony zgodne z szablonem "Elegancki". W przypadku wyboru grupy szablonu dla dokumentu, który nie ma swojej definicji, zastosowany zostanie szablon "Elegancki".

Ograniczenia

  1. System dostępny jest dla użytkowników dowolnego pakietu płatnego, którzy dokonali choć jednego zakupu (przedłużenia) pakietu. W przypadku kont w okresie testowym lub promocyjnym usługa jest niedostępna.
  2. Usługa jest obecnie w fazie beta-testów w związku z czym nie są za nią pobierane dodatkowe opłaty.
  3. Usługa w przyszłości będzie dodatkowo płatna, przy czym cena będzie zbliżona do ceny pakietu Początkowego (Fakturowanie).
  4. Zastrzegamy sobie prawo do blokowania usługi w przypadku:
    • Wykrycia prób przełamania zabezpieczeń systemu wydruków.
    • Nadmiernego obciążenia systemu.
  5. W przypadku przekroczenia limitów wykonania skryptu, wystąpienia błędu lub niedostępności usługi, wydruk zostanie wygenerowany w standardowym szablonie "Elegancki".

Schemat działania

Szablony definiowane są w naszym formacie XML. Możliwe jest stosowanie w nich wstawek języka PHP oraz JavaScript. Przed wysłaniem do systemu wydruków przetwarzane są przez interpreter PHP. W trakcie renderowania przez system wydruków wykonywane są polecenia JavaScript. Zewnętrzny kod wykonywany jest w wyizolowanym środowisku z ograniczonym dostępem do zasobów sieciowych (do obrazków z systemu wfirma.pl oraz API wfirmy).

  1. Początek generowania wydruku
  2. Interpreter PHP
    Interpreter generuje ostateczny XML, który posłuży do utworzenia pliku PDF przez system wydruków. Na tym etapie możliwe jest korzystanie z wszystkich funkcji języka PHP oraz wykonywanie zapytań to API za pośrednictwem obiektu ze zmiennej $api.
  3. Pierwszy etap renderowania XML
    Podczas tego etapu wyliczany jest podział na strony. Wykonywany jest również kod JavaScript dla wszystkich elementów z wyjątkiem nagłówka i stopki (elementów <header> i <footer>).
  4. Drugi etap renderowania XML
    Gdy znany jest już podział na stronie i rozmieszczenie wszystkich elementów na koniec renderowane są nagłówki i stopki. Pozwala to na dynamiczne określenie ich treści na podstawie zawartości strony przy użyciu języka JavaScript. Przykładowo możliwe jest dodanie podsumowań elementów strony czy licznika z numerem strony.
  5. Przekazanie gotowego pliku PDF do przeglądarki

Interpreter PHP

W trakcie tego etapu do dyspozycji jest szereg tablic z danymi dotyczącymi faktur, obiekt $api i helper $xml. Pełną zawartość danej tablice można poznać drukując ją <?=print_r($invoice);?>

  • $invoice - podstawowe informacje związane z fakturą
  • $invoiceContents - pozycje faktury
  • $parameters - parametry wywołania wydruku
  • $vatCodes - stawki podatku VAT
  • $api - obiekt pozwala na wykonywanie zapytań do API
  • $xml - helper z przydatnymi metodami
  • $invoice - podstawowe informacje związane z fakturą

    $invoiceContents - pozycje faktury

    $parameters - parametry wywołania wydruku

    $vatCodes - stawki podatku VAT

    $api - obiekt pozwala na wykonywanie zapytań do API

    Dokumentacja API znajduje się pod adresem http://doc.wfirma.pl. Poniżej przykładowe zapytanie do API przy użyciu metody request obiektu $api. Domyślnie request wykonywany jest w kontekście firmy i konta z którego generowany jest wydruk. Uprawnienia pozwalają na wykonywanie jedynie operacji odczytu.

    Nazwa metody Argumenty Opis
    request $action - napis, akcja API
    $input - tablica z parametrami zapytania
    $rawResponse - domyślna wartość false oznacza, że wynik jest automatycznie zamieniany na tablicę. W przypadku potrzeby pobrania dokumentu (np obrazka) należy ustawić wartość true.
    Metoda zwraca tablicę lub bezpośrednią odpowiedź API.

    $xml - obiekt z przydatnymi metodami

    Nazwa metody Argumenty Opis
    sanitize $string - napis do oczyszczenia Metoda usuwa znaki, które mogą zablokować parsowanie XML-a. Alternatywą jest stosowanie bloku <![CDATA[ ... ]]>
    currency $amount - wartość liczbowa Metoda formatuje wartość liczbową do postaci xx xxx,xx
    currencyWord $amount - wartość liczbowa
    $translationLanguageCode - kod języka
    $currency - kod waluty
    Metoda zamienia kwotę na słownie
    low $string - napis Zmiana wszystkich liter na małe, skrót do mb_strtolower($string, "UTF-8");
    up $string - napis Zmiana wszystkich liter na duże, skrót do mb_strtoupper($string, "UTF-8");
    niceFloat $value - wartość liczbowa Metoda usuwa nadmiarowe zera z ułamkowej części kwoty. Przykładowo 1.0000 zamieniane jest na napis 1.
    isFloatEqual $value1 - wartość liczbowa
    $value2 - wartość liczbowa
    $precision - liczba miejsc po przecinku
    Metoda sprawdza z wybraną dokładnością (domyślnie 2), czy dwie liczby rzeczywiste są równe.

    XML definiujący wydruk

    System wydruków oparty jest o podobny do HTML format XML. Możliwe jest również stosowanie kaskadowych arkuszy styli. Nie są one jednak w pełni zgodne ze standardami HTML i CSS. Zaimplementowany jest zbiór podstawowych znaczników i stylów poszerzony o unikalne znaczniki dostępne tylko w naszym systemie. Zaletą tego rozwiązania jest lepsze dostosowanie do potrzeb generowania wydruków (w porównaniu do systemów opartych o silniki przeglądarek).

    Domyślną jednostką wyrażającą pozycję i odległość jest mm. Wartości atrybutów są wrażliwe na wielkość liter.

    Poniżej znajduje się lista elementów wraz z ich atrybutami. Możliwe jest stosowanie własnych elementów takich jak <body>, <div>, <p>, <my-own-tag>. Tego typu elementy domyślnie staną się elementami blokowymi dziedziczącymi cechy bezpośrednio od <element>.

    Przykłady

    Standardowy szablon faktury