Wymiana ofert i dokumentów w systemie AMPER Dokument opisuje dostępne możliwości konfigurowania ofert i formatów dokumentów na potrzeby wymiany danych z systemami obcymi. Użytkownik Użytkownik ma możliwość eksportowania swoich dokumentów do dowolnego z dostępnych formatów. Dostępne są 3 formy eksportu: w przeglądarce na serwer FTP na maila cyklicznie raz na dobę (dotyczy wysłki mailem i FTP) Eksport w przeglądarce W zakładce "moje dokumenty" użytkownik ma opcję pobrania dokumentu w wybranym formacie. Opis techniczny: Aby pobrać wybrany dokument w wybranym formacie należy użyć następującej metody z serwera ampli-ws: GET /documents/:id_dokumentu/export/:id_szablonu Jeżeli dokument oraz szablon istnieją, plik w wybranym formacie zostanie pobrany. Eksport na serwer FTP Użytkownik w zakładce Moje Konto -> Ustawienia ustawia dane dostępowe do serwera FTP takie jak: adres serwera, port, nazwa użytkownika, hasło, katalog do którego mają być wrzucane pliki oraz czy transmisja ma być szyfrowana. Dodatkowo konieczne jest wybranie do jakiego formatu mają być eksportowane dokumenty. Od tego momentu co określony okres czasu wszystkie dokumenty niewyeksportowane poprawnie będą wrzucane na serwer FTP klienta. Domyślnie dla każdego użytkownika jest zakładane konto FTP na serwerze:  ftp://ftp.amplifier.pl . Należy pamiętać, że dokumenty na tym serwerze FTP są automatycznie kasowane po 90 dniach. Dane dostępowe do konta FTP są zapisywane wraz z utworzeniem konta. Opis techniczny: Eksportem i wysyłaniem plików zajmuje się serwer ampli-ws. Serwer udostępnia zestaw standardowych operacji pod adresem:  /ftp-config Aby eksport był możliwy  Customer  musi mieć przypisany obiekt  FTPConfig . { "id": 1, "address": "localhost", "port": 2121, "username": "samplelogin", "password": "samplepass", "directory": "export", "is_secure": false, "customer": 3, "template": 2 // id szablonu do eksportu } Pole  directory  nie jest wymagane, pliki będą wtedy eksportowane do katalogu głównego. W przypadku gdy transmisja ma być szyfrowana z wykorzystaniem TLS należy ustawić  is_secure  na  true . UWAGA! Jeżeli  is_secure  będzie ustawione niepoprawnie połączenie nie powiedzie się. W pliku  documents/tasks.py  zdefiniowana jest funkcja  export_all_to_ftp() . Odpowiada ona za operację eksportu, a przebiega ona w sposób następujący: Dla każdego użytkownika posiadającego konfigurację FTP wykonywany jest eksport dokumentów. Eksportowane są tylko te dokumenty, dla których nie istnieje wpis w historii FTP, bądź wpis zawiera informację o błędzie. Eksport na maila Użytkownik w zakładce Moje Konto -> Ustawienia ustawia adres email na który mają być wysyłane dokumenty oraz format do którego mają być eksportowane. Od tego momentu co określony okres czasu wszystkie dokumenty niewyeksportowane poprawnie będą wysyłane na ten adres. Opis techniczny: Eksportem i wysyłaniem plików zajmuje się serwer ampli-ws. Serwer udostępnia zestaw standardowych operacji pod adresem:  /mail-config Aby eksport był możliwy  Customer  musi mieć przypisany obiekt  MailConfig . { "id": 1, "address": "customer@example.com", "customer": 3, "template": 2 // id szablonu do eksportu } W pliku  documents/tasks.py  zdefiniowana jest funkcja  export_all_to_mail() . Odpowiada ona za operację eksportu, a przebiega ona w sposób następujący: Dla każdego użytkownika posiadającego konfigurację email wykonywany jest eksport dokumentów. Eksportowane są tylko te dokumenty, dla których nie istnieje wpis w historii Mail, bądź wpis zawiera informację o błędzie. Każdy plik wysyłany jest w oddzielnej wiadomości jako załącznik. Historia eksportów Każde zdarzenie eksportu jest zapisywane w bazie danych. Zapisywane jest id dokumentu, data i godzina, cel eksportu (przeglądarka, FTP, mail) oraz informacja o błędzie. W przypadku eksportów automatycznych (FTP, mail) dokumenty, dla których poprzedni eksport się nie powiódł zostaną wyeksportowane ponownie. Administrator Administrator systemu (nie sklepu) ma możliwość podglądu, definiowania, edycji oraz usuwania szablonów. Opis techniczny: Serwer ampli-ws udostępnia zestaw standardowych operacji pod adresem:  /document-templates Aby jakikolwiek dokument mógł zostać wyeksportowany wymagane jest dodanie przynajmniej jednego szablonu. Przykładowy obiekt  DocumentTemplate  wygląda następująco: { "id": 2, "name": "Testowy Format", "extension": ".txt", // konieczne jest umieszczenie kropki razem z roszerzeniem "content": "Numer dokumentu: {{ document.number }}, data: {{ document.date }}" } Pole  content  zawiera w sobie standardowy szablon Django. Mogą być używane wszystkie standardowe dla tego typu szablonów elementy. Jako kontekst przekazywany jest obiekt typu  Document  pod nazwą  document . Dostępne pola dla nagłówka dokumentu Dostęp:  document.nazwa_pola number  - Numer dokumentu date  - Data dokumentu due_date  - Termin dokumentu description  - Opis value_net  - Wartość netto value_gross  - Wartość brutto Tagi własne get_vat_value_net get_vat_value_gross get_vat_value_vat Sposób użycia: {% get_vat_value_net document 23 %} zwraca wartość netto dla stawki VAT 23% Dostępne pola dla pozycji dokumentu Dostęp:  line.nazwa_pola product_name  - Nazwa product_symbol  - Symbol product_vat  - Stawka VAT produktu product_ean  - Kod EAN produktu unit  - Jednostka miary quantity  - Ilość unit_aggregate  - Jednostka miary zbiorcza" quantity_aggregate  - Ilość zbiorcza price_net  - Cena netto price_gross  - Cena brutto value_net  - Wartość netto value_gross  - Wartość brutto manufacturer  - Producent make  - Marka group  - Grupa value_vat  - Wartość VAT pozycji Dostępne pola dla kontrahenta Dostęp:  customer.nazwa_pola name  - Nazwa kontrahenta short_name  - Kod/nazwa skrócona tax_id  - Numer NIP Dostępne pola dla produktu Dostęp:  line.product.nazwa_pola name  - Nazwa produktu friendly_name  - Nazwa skrócona/nazwa zrozumiała dla użytkownika short_description  - Krótki opis produktu description  - Opis short_code  - Kod produktu sku  - SKU vat  - VAT available_on  - Dostępny od is_published  - Czy opulikowany is_featured  - Czy promowany default_unit_of_measure  - Domyślna jednostka miary cumulative_unit_of_measure  - Zbiorcza jednostka miary cumulative_converter  - Przelicznika na jednostkę zbiorczą can_be_split  - Czy jednostka miary zbiorcza podzielna cumulative_unit_ratio_splitter  - Współczynnik podzielności (uzupełniany tylko kiedy can_be_split==True) unit_roundup  - Zaokrąglenie jednostki miary weight  - Waga default_price  - Cena 100 default_image.image.url - url do domyślnego obrazka produktu product_b2b_url - url do produktu w systemie AMPER B2B available_on_stock - czy produkt dostępny na stanie, zwraca True/False stocks_available - podaje rzyczywisty stan produktu na magazynie stocks_available_in_words - podaje stan magazynu w formie słownej none/low/medium/high stock_availability_customer - podaje stan produktu na magazynie do którego jest przypisany kontrahent z uwzględnieniem flagi Zwracaj rzeczywistą wartość stanów w API i ofertach cn_code - kod CN category_path - ścieżka kategorii głównej do jakiej jest przypisany produkt main_category - nazwa kategorii głównej Tagi własne attribute_value unit_of_measure_converter Sposób użycia: {% attribute_value product [id atrybutu] %} {% unit_of_measure_converter product [nazwa jednostki miary] %} W szablonie należy zadeklarować tagi produktu: {% load product_extras %} Kolumny dostępne tylko do typu szablonu Oferty offer_best_promotion.price - najlepsza cena promocyjna offer_best_promotion.promotion_name - nazwa promocji z jakiej pochodzi cena promocyjna offer_best_promotion.promotion_id - id promocji offer_best_promotion.promotion_url - link URL do promocji w B2B offer_best_promotion.promotion_min_order_quantity - minimalna ilość zamówienia w promocji offer_promotion_prices_list - lista cen promocyjnych z programi zwracana w formie 2880.00;1.39;1440.00;1.43;720.00;1.50; . Czyli produkt występuje w trzech progach promocyjnych: 1.39 PLN za zakup 2880, 1.43 PLN za zakup 1440, 1.50 PLN za zakup 720 top_offer_starting_from_a_single_piece - najlepsza cena promocyjna dla minimum jednej sztuki Operacje na liczbach W definicji szablonu na samym początku należy dodać deklarcję: {% load mathfilters %} W szablonie można wtedy używać następujących operacji matematycznych: sub – odejmowanie mul – mnożenie div – dzielenie intdiv – dzielenie całkowite (podłoga) abs – wartość bezwzględna mod – modulo addition – zamiennik filtra add ze wsparciem dla typów float/decimal Przykład: {% load mathfilters %} {% with answer=42 %} 42 * 0.5 = {{ answer|mul:0.5 }} {% endwith %} {% with numerator=12 denominator=3 %} 12 / 3 = {{ numerator|div:denominator }} {% endwith %} Dokumentacja składni używanej przy tworzeniu szablonów https://docs.djangoproject.com/en/3.2/topics/templates/ Przykład {% for line in document.document_lines.all %}{{line.product_name}};{{line.product_symbol}};{{line.quantity}};{{line.price_net}};{{line.value_net}} {% endfor %}