################
Payment Matching
################

*******************
General information
*******************

HORES Payment Matching API is designed to process individual payments from bank account statements or similar sources,
record them and automatically or manually match them to reservations or invoices in HORES.

API is designed as simple HTTP API using JSON data format, see available endpoints.

Using SSL encryption (HTTPS) is mandatory.

*************
Authorization
*************

Authentication is done via HTTP Authorization header using permanent token.

Token can be defined for each user in HORES and allows for non-interactive authentication of API operations in the name of
that user. Use "Authorization" header with "Token" keyword such as:

.. sourcecode:: http

  POST /payment_matching/match_payments HTTP/1.1
  Host: example.com
  Accept: application/json
  Authorization: Token 65sad4f64df6sd6f4sdffassdfa


*************
API Endpoints
*************

.. http:get:: /payment_matching/hores_info

  Version and build info about running HORES instance. You can use this endpoint to check if server is running and
  validate your token.

.. http:post:: /payment_matching/match_payments

  Post one or more transactions to process.

  "amount", "transaction_id", "currency_code" and "date_of_payment" fields are mandatory.

  "transaction_id" must be unique for every transaction for particular client across all accounts. Repeated requests
  with same transaction_id will result in warning "transaction already exists" for given transaction. Transaction with
  duplicated "transaction_id" is not updated, duplicated data are ignored!

  Single request may contain multiple transactions. Transactions are processed individually.

  If all transactions within request are processed without error, return code is 0. Otherwise return code is 1 and
  list of "errors" is provided.

  Any other return code beside 0 and 1 means complete failure to process request.

  **Example request**:

  .. sourcecode:: json

    {
      "transactions": [
        {
          "amount": "1000.00",
          "transaction_id": "20230001",
          "date_of_payment": "2023-12-10T12:23:44.233+02:00",
          "currency_code": "EUR",
          "is_transaction_fee": false,
          "variable_symbol": "233445",
          "specific_symbol": "2334",
          "constant_symbol": "0800",
          "bank_account_number": "233456754332",
          "bank_number_code": "3300",
          "transaction_type": null,
          "iban": "CZ6508000000192000145399",
          "bic": "HBUKGB4B",
          "bank_account_name": "Hotel account",
          "private_note": "Reservation 2344",
          "description": "Reservation 2344",
          "original_amount": null,
          "original_amount_currency_code": null,
          "exchange_rate": null,
          "transactional_fee_amount": null
        }
      ]
    }


  :<json numeric amount: Paid amount, use negative number for outgoing payments.
  :<json string transaction_id: Unique payment identification.
  :<json numeric transactional_fee_amount: Transaction fee.
  :<json boolean is_transaction_fee: If true, entire transaction is considered transaction fee.
  :<json string currency_code: ISO code of transaction currency.
  :<json datetime date_of_payment: Date of transaction in ISO format with timezone
  :<json string variable_symbol: Variable symbol
  :<json string specific_symbol: Specific symbol
  :<json string constant_symbol: Constant symbol
  :<json string bank_account_number: Source bank account number
  :<json string bank_number_code: Czech bank code
  :<json string transaction_type: Details of payment method
  :<json string iban: International IBAN account number for source account
  :<json string bid: BIC (SWIFT) code for source account
  :<json string bank_account_name": Account name to identify source account
  :<json string private_note: User note for transaction
  :<json string description: Sender's note for transaction
  :<json numeric original_amount: Amount in currency different from account currency
  :<json string original_amount_currency_code: ISO code for original currency
  :<json numeric exchange_rate: Exchange rate used for automatic conversion


  **Example success response**:

  .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "result": 0,
        "accepted_transactions": ["20230001"]
      }

  **Example warning response**:

  .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "result": 0,
        "accepted_transactions": [20230002],
        "warnings": [
          {
            "transaction_id": "20230001",
            "warning": "Unique violation error, transaction already exists!"
          }
      }


  **Example error response**:

  .. sourcecode:: http

      HTTP/1.1 200 OK
      Vary: Accept
      Content-Type: application/json

      {
        "result": 1,
        "accepted_transactions": [],
        "errors": [
          {
            "transaction_id": "20230001",
            "error": "Missing price!"
          }
      }