Przejdź do treści

Protokół Pact24CashRegister

← Dla Programistów

Opis protokołu komunikacyjnego Pact24CashRegister

Przesyłanie komunikatów do programu Pact24 CashRegister odbywa się za pomocą znanego formatu wymiany danych JSON.

Podstawowa struktura komunikatu:
{
  "mode": "receipt",
  "cashier": {
    "name": "Jan",
    "number": "5"
  },
  "checkout": {
    "been_paid": "0,00",
    "change": "0,00",
    "total": "18,66",
    "discount": null,
    "tax_id": null,
    "payment_type": null
  },
  "lines": [
    {
      "nr": 1,
      "name": "Jabłka",
      "code": 4002,
      "quantity": "2,321",
      "unit": "kg.",
      "price": "3,00",
      "total": "6,96",
      "discount": null
    },
    {
      "nr": 2,
      "name": "Chleb baltonowski",
      "code": "2",
      "quantity": "1",
      "unit": "szt.",
      "price": "2,10",
      "total": "2,10",
      "discount": null
    },
    {
      "nr": 3,
      "name": "Cola 1L",
      "code": "5449000054227",
      "quantity": "2",
      "unit": "szt.",
      "price": "4,80",
      "total": "9,60",
      "discount": null
    }
  ]
}

Atrybut mode :
- jest wymagany
- String
- przyjmuje zawsze jedną z dwóch wartości: "receipt" lub "checkout"
- określa obecny stan paragonu na kasie:
receipt: paragon pusty, paragon w trakcie transakcji, paragon anulowany (=paragon pusty)
checkout: zapłata za paragon

Obiekt cashier:
- nie jest wymagany
- String
- atrybut name to nazwa kasjera, jaka jest prezentowana klientowi
- atrybut number to numer kasjera w systemie

Obiekt checkout:
- jest wymagany
- pole total (string) zawsze wskazuje bieżącą wartość paragonu do zapłaty. Gdy paragon jest pusty wówczas pole to przyjmuje wartość "0,00"
- pole discount (string) to pole tekstowe, w którym jest bieżąca informacja na temat udzielonego całościowego rabatu dla bieżącego paragonu np.:
null- nie udzielono rabatu
"5%"- udzielono rabatu pięcioprocentowego
"2,30"- udzielono rabatu kwotowego w wysokości 2,30
- pole been_paid (string) t o kwota wpłacona przez klienta
- pole change (string) to reszta należna klientowi
- pole tax_id to nr NIP klienta. Domyślnie wartość null lub String z nr NIP np. "9720969679" 
- pole payment_type (string) określa formę płatności za paragon i przyjmuje następujące wartości:
null- gdy atrubyt mode ma wartość receipt
"CASH"- gotówka
"CARD"- karta płatnicza
"BOND"- bon
"CURRENCY"- waluta
"CHECK"- czek
"CREDIT"- kredyt

Obiekt lines: 
- jest wymagany
- jest tablicą zawierającą dane poszczególnych linii paragonu
- gdy paragon jest pusty (lub anulowany), wtedy: "lines": null
- pojedyncza linia jest zdefiniowana przez następujące pola:
nr - numer produktu na paragonie (int)
name- nazwa produktu (string) (jest wymagane)
code- kod produktu np. kod ean-13. Jeżeli produkt nie ma kodu ean, wtedy kod krótki (string)
quantity- ilość (jest wymagane) (string)
unit- jednostka np. 'szt.' lub "kg." itp. 
price - cena jednostkowa (string)
total- wartość linii (total = price * quantity) (string) (jest wymagane)
discount- wartość udzielonego rabatu dla tej pojedynczej linii (string)


Zdarzenia po stronie programu kasowego, które wywołują przesłanie komunikatu do Pact24CashRegister:
- gotowość do pracy (pusty paragon)
- dodanie każdego produktu do paragonu
- stornowanie
- anulacja paragonu
- podsumowanie paragonu
- zakończenie paragonu
- podanie/poprawienie nr NIP klienta

Należy pamiętać aby przy każdorazowym dodaniu lub usunięciu linii paragonowej odpowiednio uaktualnić wartość pól total i discount (o ile był przyznany rabat) obiektu checkout.

Polskie znaki

Aby polskie znaki były prawidłowo wyświetlane na ekranie klienta, należy cały tekst komunikatu kodować zgodnie ze standardem UTF-8.

Przykładowe komunikaty

1. Pusty paragon z zalogowanym kasjerem "Jan" o numerze 5:
{
  "mode": "receipt",
  "cashier": {
    "name": "Jan",
    "number": "5"
  },
  "checkout": {
    "been_paid": "0,00",
    "change": "0,00",
    "total": "0,00",
    "discount": null,
    "tax_id": null,
    "payment_type": null
  },
  "lines": null
}
2. Dodanie pierwszego produktu:
{
  "mode": "receipt",
  "cashier": {
    "name": "Jan",
    "number": "5"
  },
  "checkout": {
    "been_paid": "0,00",
    "change": "0,00",
    "total": "6,96",
    "discount": null,
    "tax_id": null,
    "payment_type": null
  },
  "lines": [
    {
      "nr": 1,
      "name": "Jabłka",
      "code": "4002",
      "quantity": "2,321",
      "unit": "kg.",
      "price": "3,00",
      "total": "6,96",
      "discount": null
    }
  ]
}

3. Dodanie kolejnego produktu:
{
  "mode": "receipt",
  "cashier": {
    "name": "Jan",
    "number": 5
  },
  "checkout": {
    "been_paid": "0,00",
    "change": "0,00",
    "total": "16,56",
    "discount": null,
    "tax_id": null,
    "payment_type": null
  },
  "lines": [
    {
      "nr": 1,
      "name": "Jabłka",
      "code": "4002",
      "quantity": "2,321",
      "unit": "kg.",
      "price": "3,00",
      "total": "6,96",
      "discount": null
    },
    {
      "nr": 2,
      "name": "Cola 1L",
      "code": "5449000054227",
      "quantity": "2",
      "unit": "szt.",
      "price": "4,80",
      "total": "9,60",
      "discount": null
    }
  ]
}

4. Zapłata za paragon (gotówka, do zapłaty: 16,50 zł; wpłacono: 20 zł; reszta: 3,50 zł oraz klient podał NIP):
{
  "mode": "checkout",
  "cashier": {
    "name": "Jan",
    "number": "5"
  },
  "checkout": {
    "been_paid": "20,00",
    "change": "3,50",
    "total": "16,50",
    "discount": null,
    "tax_id": "9721002531",
    "payment_type": "CASH"
  },
  "lines": [
    {
      "nr": 1,
      "name": "Jabłka",
      "code": "4002",
      "quantity": "2,321",
      "unit": "kg.",
      "price": "3,00",
      "total": "6,96",
      "discount": null
    },
    {
      "nr": 2,
      "name": "Cola 1L",
      "code": "5449000054227",
      "quantity": "2",
      "unit": "szt.",
      "price": "4,80",
      "total": "9,60",
      "discount": null
    }
  ]
}

5. Stornowanie pozycji (gdy z przykładu nr 3 dokonamy storna ostatniego produktu, to wysyłamy komunikat z przykładu nr 2).

6. Anulowanie paragonu (wówczas wysyłamy komunikat z przykładu nr 1).


Uwaga - Program Pact24CashRegister służy tylko do prezentacji otrzymanych danych i nie weryfikuje poprawności logicznej (np. czy kwota do zapłaty faktycznie wynika z podsumy kwoty za poszczególne produkty). Zakładamy, że dane otrzymane na temat paragonu są zawsze prawdziwe.

Komunikacja z programem Pact24CashRegister

Przesyłanie powyższych komunikatów do programu Pact24CashRegister odbywać się może na dwa sposoby:
I. REST API (zalecany):

Do tego celu wykorzystywana jest metoda POST dla adresu http://adres_ip/update 
gdzie adres_ip to adres komputera, na którym jest zainstalowany i uruchomiony program Pact24CashRegister (najczęściej jest to localhost).

Przykład wysłania komunikatu:
curl -X POST http://localhost/update -d @plik_z_komunikatem.json
II. Poprzez zapis do pliku w formacie JSON

Obsługa wyjątków

Zaleca się obsługę zdarzenia, gdy host (komputer z Pact24CashRegister) będzie niedostępny.
Należy wówczas:
a) przechwycić wyjątek
b) kontynuować pracę jakby wszystko odbyło się prawidłowo.
Dzięki temu gdy komputer z Pact24CashRegister będzie ponownie aktywny, wszystko zacznie samoczynnie działać (nie będzie konieczny restart programu kasowego).



Zgłoszenia i baza wiedzy

(Myślenie…)