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

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 %}