Wymiana ofert i dokumentów w systemie AMPER

Artykuł opisuje, jak klient AMPER otrzymuje swoje dokumenty (faktury, WZ itp.) i ofertę produktową w formacie potrzebnym jego systemowi (ERP, program magazynowy, sklep), oraz jak administrator definiuje te formaty za pomocą szablonów.

Formy eksportu

Forma	Dokumenty	Oferta
pobranie w przeglądarce (B2B)	na żądanie	na żądanie
pobranie przez API	–	na żądanie (`offer-download`)
serwer FTP klienta	automatycznie co 30 minut	automatycznie raz na dobę
e-mail	automatycznie co 30 minut	automatycznie raz na dobę

Format pliku zawsze wyznacza szablon zdefiniowany przez administratora (patrz sekcja Szablony).

Dokumenty

Pobranie w przeglądarce

W zakładce Moje dokumenty klient pobiera dokument w wybranym formacie.

Opis techniczny – metoda serwera AMPER WS:

GET /documents/{id_dokumentu}/export/{id_szablonu}/

Jeśli dokument i szablon istnieją, serwer zwraca plik. Nazwa pliku to numer dokumentu (bez znaków specjalnych) z rozszerzeniem szablonu.

Eksport na serwer FTP

Klient w zakładce Moje konto → Ustawienia podaje dane serwera FTP: adres, port, użytkownika, hasło, katalog docelowy, informację, czy połączenie ma być szyfrowane, oraz szablon (format) dokumentów. Od tej chwili co 30 minut nowe dokumenty trafiają na jego serwer.

Opis techniczny – konfiguracja to obiekt FTPConfig, dostępny pod adresem /ftp-config/:

{
  "id": 1,
  "customer": 3,
  "address": "ftp.example.com",
  "port": 21,
  "username": "samplelogin",
  "password": "samplepass",
  "directory": "export",
  "is_secure": false,
  "is_document_active": true,
  "document_start_from": "2026-10-01T00:00:00+02:00",
  "template": 2,
  "is_offer_active": false,
  "offer_template": null
}

Pole	Opis
`address`, `port`, `username`, `password`	dane serwera FTP
`directory`	katalog docelowy; puste – katalog główny
`is_secure`	`true` – połączenie szyfrowane TLS. Ustawienie niezgodne z serwerem powoduje błąd połączenia
`is_document_active`	musi być `true`, aby dokumenty były eksportowane
`document_start_from`	eksportowane są tylko dokumenty z datą od tego momentu (domyślnie: chwila utworzenia konfiguracji)
`template`	szablon dokumentów – eksportowane są tylko dokumenty typu przypisanego do szablonu
`is_offer_active`, `offer_template`	eksport oferty – patrz sekcja Oferta

Każdy dokument jest wysyłany jako osobny plik. Jeśli szablon ma rozszerzenie .pdf, zamiast szablonu tekstowego wysyłany jest wydruk PDF dokumentu.

Eksport na e-mail

Klient w zakładce Moje konto → Ustawienia podaje adres e-mail i szablon. Od tej chwili co 30 minut nowe dokumenty są wysyłane na ten adres – każdy dokument w osobnej wiadomości jako załącznik.

Opis techniczny – konfiguracja to obiekt MailConfig, dostępny pod adresem /mail-config/:

{
  "id": 1,
  "customer": 3,
  "address": "ksiegowosc@example.com",
  "is_document_active": true,
  "document_start_from": "2026-10-01T00:00:00+02:00",
  "template": 2,
  "is_offer_active": false,
  "offer_template": null
}

Pola mają to samo znaczenie co w FTPConfig. Gdy address jest pusty, wiadomość trafia na główny adres e-mail klienta. Dokumenty bez pozycji nie są wysyłane.

Domyślne konto FTP

Przy zakładaniu konta klienta AMPER tworzy mu konto na serwerze ftp.amplifier.pl; dane dostępowe są zapisywane na koncie klienta. Pliki na tym serwerze są automatycznie usuwane po 90 dniach.

Historia eksportów

Każdy eksport jest zapisywany: dokument (lub oferta), data i godzina, cel (browser, ftp, mail) i ewentualny błąd. Historia jest dostępna pod adresem /export-history/.

Eksport automatyczny pomija dokumenty, które zostały już poprawnie wysłane do danego celu (FTP lub e-mail). Dokumenty, których wysłanie się nie powiodło, zostaną wysłane ponownie przy kolejnym przebiegu.

Oferta

Oferta to lista produktów dostępnych dla klienta, z jego cenami, stanami i promocjami, zapisana w formacie szablonu oferty (np. CSV dla sklepu internetowego).

Pobranie przez API – system klienta pobiera aktualną ofertę w dowolnej chwili:
```
GET /customers/offer-download/{id_szablonu}/?api_key={amper_api_key}
```
Odpowiedź to plik z nagłówkiem Content-Disposition: attachment. Wariant /customers/view-offer/{id_szablonu}/ zwraca tę samą treść bez nagłówka pobierania. Klucz API i jego zasady opisuje artykuł API zewnętrzne. Oferta jest generowana przy każdym zapytaniu – nie pobieraj jej częściej niż raz na godzinę.
FTP i e-mail – w konfiguracji FTP lub e-mail klient włącza is_offer_active i wybiera offer_template. Oferta jest wysyłana raz na dobę, w nocy. Nazwa pliku to file_name szablonu albo offer_<klient>_<znacznik czasu>.
Codzienna oferta na domyślny FTP – klient z włączoną automatyczną ofertą dzienną i przypisanym domyślnym szablonem oferty dostaje ją raz na dobę na swoje konto na ftp.amplifier.pl.

Szablony

Administrator systemu (nie sklepu) przegląda, tworzy, edytuje i usuwa szablony. Aby jakikolwiek dokument lub oferta mogły zostać wyeksportowane, musi istnieć przynajmniej jeden szablon odpowiedniego typu.

Opis techniczny – szablony są dostępne pod adresem /document-templates/:

{
  "id": 2,
  "name": "Faktura – CSV",
  "type": "document",
  "document_type": 4,
  "extension": ".csv",
  "file_name": null,
  "file_encoding": "utf_8_sig",
  "response_encoding": "utf-8-sig",
  "linux_end_lines": false,
  "content": "{% for line in document.document_lines.all %}{{ line.product_symbol }};{{ line.quantity }}{{ newline }}{% endfor %}"
}

Pole	Opis
`name`	nazwa szablonu widoczna dla klienta
`type`	rodzaj: `document` (dokument), `offer` (oferta) albo `complaint` (reklamacja)
`document_type`	typ dokumentu, którego dotyczy szablon – eksport automatyczny wysyła tylko dokumenty tego typu
`extension`	rozszerzenie pliku razem z kropką, np. `.csv`; `.pdf` oznacza wydruk PDF dokumentu zamiast szablonu
`file_name`	stała nazwa pliku (bez rozszerzenia) – używana dla ofert
`file_encoding`	kodowanie pliku (domyślnie `utf_8_sig`, czyli UTF-8 z BOM); np. `cp1250` dla starszych programów
`response_encoding`	kodowanie deklarowane w odpowiedzi HTTP przy pobieraniu
`linux_end_lines`	`true` – końce linii `\n`; `false` – `\r\n` (Windows)
`content`	treść szablonu w składni szablonów Django

Składnia szablonów

Pole content to standardowy szablon Django – działają wszystkie elementy tej składni ({% for %}, {% if %}, filtry). Dokumentacja: szablony Django 4.2.

Zmienne dostępne w szablonie:

Rodzaj szablonu	Zmienne
dokument	`document` – dokument; `newline` – znak końca linii zgodny z ustawieniem `linux_end_lines`
oferta	`products` – lista produktów oferty z cenami klienta (końce linii są ustawiane zgodnie z `linux_end_lines` przy zapisie pliku)

Pola nagłówka dokumentu

Dostęp: document.nazwa_pola

number – numer dokumentu
date – data dokumentu
due_date – termin płatności
description – opis
value_net – wartość netto
value_gross – wartość brutto
document_lines.all – lista pozycji dokumentu

Tagi wartości VAT (wymagają {% load document_tags %} na początku szablonu):

get_vat_value_net – wartość netto dla stawki VAT
get_vat_value_gross – wartość brutto dla stawki VAT
get_vat_value_vat – kwota VAT dla stawki VAT

{% load document_tags %}
{% get_vat_value_net document 23 %}

zwraca wartość netto pozycji ze stawką VAT 23%.

Pola kontrahenta

Dostęp: document.customer.nazwa_pola

name – nazwa kontrahenta
short_name – kod / nazwa skrócona
tax_id – NIP

Pola pozycji dokumentu

Dostęp: line.nazwa_pola (w pętli {% for line in document.document_lines.all %})

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
value_vat – wartość VAT pozycji
manufacturer – producent
make – marka
group – grupa
product – produkt (pola poniżej, np. line.product.cn_code)

Pola produktu

Dostęp: line.product.nazwa_pola w szablonie dokumentu albo product.nazwa_pola w pętli {% for product in products %} w szablonie oferty.

name – nazwa produktu
friendly_name – nazwa handlowa (zrozumiała dla użytkownika)
short_description – krótki opis
description – opis
short_code – kod produktu
sku – SKU
ean – kod EAN
vat – stawka VAT
cn_code – kod CN
available_on – dostępny od
is_published – czy opublikowany
is_featured – czy wyróżniony
default_unit_of_measure – podstawowa jednostka miary
cumulative_unit_of_measure – jednostka zbiorcza
cumulative_converter – przelicznik na jednostkę zbiorczą
can_be_split – czy jednostka zbiorcza jest podzielna
cumulative_unit_ratio_splitter – współczynnik podzielności (tylko gdy can_be_split = True)
unit_roundup – zaokrąglanie do jednostki
weight – waga
default_price – cena katalogowa
final_price – cena dla klienta (tylko w szablonie oferty)
default_image.image.url – adres domyślnego zdjęcia produktu
product_b2b_url – adres produktu w AMPER B2B
available_on_stock – czy produkt jest na stanie (True / False)
stocks_available – rzeczywisty stan produktu (stan minus rezerwacje, ze wszystkich magazynów)
stocks_available_in_words – stan słownie: none / low / medium / high
stock_availability_customer – stan dla klienta z uwzględnieniem opcji Zwracaj rzeczywistą wartość stanów w API i ofertach (tylko w szablonie oferty)
category_path – ścieżka kategorii głównej produktu
main_category – nazwa kategorii głównej

Tagi produktu (wymagają {% load product_extras %}):

attribute_value – wartość atrybutu produktu
unit_of_measure_converter – przelicznik dla wskazanej jednostki miary

{% load product_extras %}
{% attribute_value product [id atrybutu] %}
{% unit_of_measure_converter product [nazwa jednostki miary] %}

Pola dostępne tylko w szablonie oferty:

offer_best_promotion.price – najlepsza cena promocyjna
offer_best_promotion.promotion_name – nazwa promocji, z której pochodzi cena
offer_best_promotion.promotion_id – ID promocji
offer_best_promotion.promotion_url – adres promocji w B2B
offer_best_promotion.promotion_min_order_quantity – minimalna ilość zamówienia w promocji
offer_promotion_prices_list – lista progów cenowych w formie 2880.00;1.39;1440.00;1.43;720.00;1.50; – produkt ma trzy progi: 1,39 zł przy zakupie 2880 szt., 1,43 zł przy 1440 szt. i 1,50 zł przy 720 szt.
top_offer_starting_from_a_single_piece – najlepsza cena promocyjna obowiązująca już od jednej sztuki

Operacje na liczbach

Na początku szablonu dodaj:

{% load mathfilters %}

Dostępne filtry:

sub – odejmowanie
mul – mnożenie
div – dzielenie
intdiv – dzielenie całkowite (z zaokrągleniem w dół)
abs – wartość bezwzględna
mod – reszta z dzielenia
addition – dodawanie (zamiennik filtra add, działa także dla liczb dziesiętnych)

{% load mathfilters %}
{% with answer=42 %}
42 * 0.5 = {{ answer|mul:0.5 }}
{% endwith %}
{% with numerator=12 denominator=3 %}
12 / 3 = {{ numerator|div:denominator }}
{% endwith %}

Przykłady

Dokument – CSV z pozycjami:

{% for line in document.document_lines.all %}{{ line.product_name }};{{ line.product_symbol }};{{ line.quantity }};{{ line.price_net }};{{ line.value_net }}{{ newline }}{% endfor %}

Oferta – CSV z cenami klienta i stanem:

EAN;Nazwa;Cena netto;Stan
{% for product in products %}{{ product.ean }};{{ product.name }};{{ product.final_price }};{{ product.stock_availability_customer }}
{% endfor %}