Transactions
============

POS clients can record transactions using this API. The client must use the TAG
algorithm to generate the barcode for each delegate.

All the codes for a specific purchase should follow the following convention:

- Purchase Code: a barcode's base;
- Purchase Item Code: the Purchase Code + a zero padded incremental counter
  starting from zero (0000, 0001, … 9999);
- Delegate Barcode: a barcode generated using TAG algorithm and the purchase code as base.

The reference implementation of the `barcode generation algorithm`_ is written
in PHP, but we also have a `JavaScript implementation`_.

A transaction recorded through a POS device should always be accepted by the system
because once such transaction is confirmed in the real world that means a customer
somewhere is walking around with tickets or a receipt that must be loaded into the system.
For this reason, while the system will try and load all the information as correctly
as it can, it will still trust the device and store the data anyway, even if some
inconsistencies are detected.

POST /tx/new
------------

A transaction is composed of global fields and transaction items.

The request should hold the following parameters:

- ``context`` The device ID all products are joined to, usually it's an `event` device;
- ``code`` The Purchase Code, see introduction;
- ``totalAmount`` The total amount (in cents of a dollar);
- ``notes`` Any note entered by the staff member handling the transaction;
- ``createdAt`` The timestamp of the purchase, as an Unix timestamp, in seconds;
- ``recordedBy`` The staff member recording this transaction;
- ``transactions`` The list of individual money transactions logged for this purchase,
  which should add up to the `totalAmount` specified above. Each one should have:

  - ``paymentMethod`` Can be "cash" or "card";
  - ``amount`` The amount paid using this method (in cents of a dollar);
  - ``change`` The change given back to the customer (in cents of a dollar).
    This is only valid if the payment method is "cash";
  - ``transactionId`` The identifier of the transaction. This could be the identifier
    returned by the card reader or gateway used to execute the transfer of money;
- ``items`` The list of items purchased in this transaction. Each item should have:

  - ``code`` The Purchase Item Code, see introduction;
  - ``product`` The device ID of the product sold;
  - ``quantity`` The quantity sold. Should always be greater than zero;
  - ``description`` The description for this line item. Usually this is the product name;
  - ``unitAmount`` The price for an individual unit (in cents of a dollar);
  - ``totalAmount`` The total for this line item (in cents of a dollar). Usually this is
    just quantity times the unit amount;
  - ``discountAmount`` Total discount applied to this line item (in cents of a dollar);
  - ``delegates`` The list of delegates to create for this line item. Each delegate should
    have the following properties:

    - ``product`` The device ID of the product joined to this delegate (commonly called
      ticket). Usually this matches the product of the line item, but could be different
      for example if a product purchased has "sub-products". For example a family pass
      provides two adult tickets and three children. In this case each unit of this
      line item will have 5 associated delegates, two of them with the adult product ID
      and three of them with the child product ID;
    - ``description`` The description of this delegate. Usually this is the product label;
    - ``barcode`` The barcode associated to this delegate. This must be generated using
      the `barcode generation algorithm`_.

Below is a payload example:

- the customer has bought a total of $24 worth of tickets

  - 3 adult tickets for $4 each for a total of $12
  - 1 family pass for $12

- they paid $4 cash using a $5 note, $20 dollar using a debit card, and received $1 change
- the staff member "Richard M" who was handling the transaction wrote a note about it

.. code-block:: json

  {
    "context": 1,
    "code": "GJXS0LM6RYG40",
    "totalAmount": 2400,
    "notes": "Customer is paying the $4 in cash because of low balance",
    "createdAt": 1768268326,
    "recordedBy": "Richard M",
    "transactions": [
      {
        "paymentMethod": "cash",
        "amount": 400,
        "change": 100
      },
      {
        "paymentMethod": "card",
        "transactionId": "ch_3SnT0BCpzQXiFwJY0rQJrzWE",
        "amount": 2000
      }
    ],
    "items": [
      {
        "product": 2,
        "code": "GJXS0LM6RYG400000",
        "quantity": 3,
        "description": "Adult",
        "unitAmount": 400,
        "totalAmount": 1200,
        "discountAmount": null,
        "delegates": [
          {
            "product": 4,
            "description": "Adult",
            "barcode": "GJXS0LM6RYG40XJX01"
          },
          {
            "product": 4,
            "description": "Adult",
            "barcode": "GJXS0LM6RYG40XJX02"
          },
          {
            "product": 4,
            "description": "Adult",
            "barcode": "GJXS0LM6RYG40XJX03"
          }

        ]
      },
      {
        "product": 3,
        "code": "GJXS0LM6RYG400001",
        "quantity": 1,
        "description": "Family Pass",
        "unitAmount": 1200,
        "totalAmount": 1200,
        "discountAmount": null,
        "delegates": [
          {
            "product": 8,
            "description": "Adult",
            "barcode": "GJXS0LM6RYG40XJX04"
          },
          {
            "product": 8,
            "description": "Adult",
            "barcode": "GJXS0LM6RYG40XJX05"
          },
          {
            "product": 9,
            "description": "Child",
            "barcode": "GJXS0LM6RYG40XJX06"
          },
          {
            "product": 9,
            "description": "Child",
            "barcode": "GJXS0LM6RYG40XJX07"
          },
          {
            "product": 9,
            "description": "Child",
            "barcode": "GJXS0LM6RYG40XJX08"
          }
        ]
      }
    ]
  }

.. _barcode generation algorithm: https://git.satellite.co.nz/satellite/satellite-tag-5/tagx/-/blob/main/src/Core/Barcode/Barcode.php
.. _JavaScript implementation: https://git.satellite.co.nz/satellite/satellite-tag-5/tagx/-/blob/main/assets/lib/Barcode.js