Prepojenie Vernostné API Webhook

Api definuje 2 endpointy, ktoré pokrývajú základný flow registrácie účtu do vernostného systému k danej karte klienta a načítanie prípadnej zľavy na účet pre konkrétnu vernostnú kartu ešte pred uzatvorením účtu.

Konkrétny endpoint 1,2 a komunikačný token bude nastaviteľný v administrácii Papaya POS

Token: komunikacny_token (typ tokenu Autorizacny Bearer)

CODE

Authorization: Bearer mytoken123

Endpoint - Čítanie zľavy pre Vernostnú kartu zákazníka

Slúži na načítanie zľavy z externého vernostného systému pre danú vernostnú kartu.

Request:

JSON

{
    "orderId": "00123487979878", #UUID
    "cardId": "memberCardId",
    "status": "open",
    "total": 50.00,
    "totalWithoutVat": 41.67,
    "currency": "EUR",
    "vat": 8.33,
    "created": "2025-10-21T10:30:00.000Z",
    "updated": "2025-10-21T10:35:12.000Z",
    "branchId": "SLOVAK_PUB",
    "note": "Customer requested extra napkins",
    "orderItems": [
      {
        "id": "214124213", #UUID (accEntryId)
        "productId": "11111", #UUID (accItemId)
        "name": "Espresso",
        "description": "Double shot espresso made from premium Arabica beans",
        "quantity": 2,
        "unitPrice": 2.50,
        "totalPrice": 5.00,
        "vat": 1.00,
        "vatRate": 20,
        "categoryId": "321827891478912", #UUID
        "categoryName": "Hot Beverages",
        "ean": "1234567890",
        "note": null
      },
      {
        "id": "214124214", #UUID (accEntryId)
        "productId": "22222", #UUID (accItemId)
        "name": "Butter Croissant",
        "description": "Freshly baked French butter croissant",
        "quantity": 1,
        "unitPrice": 3.50,
        "totalPrice": 3.50,
        "vat": 0.70,
        "vatRate": 20,
        "categoryId": "321827891478912", #UUID
        "categoryName": "Bakery",
        "ean": "8594123456790",
        "note": null
      },
      {
        "id": "214124215", #UUID (accEntryId)
        "productId": "3333332131", #UUID
        "name": "Club Sandwich",
        "description": "Triple-decker sandwich with turkey, bacon, lettuce, and tomato",
        "quantity": 1,
        "unitPrice": 6.50,
        "totalPrice": 6.50,
        "vat": 1.30,
        "vatRate": 20,
        "categoryId": "21421423131241", #UUID
        "categoryName": "Food",
        "ean": "8594123456791",
        "note": "No mayonnaise"
      }
    ]
  }
}

3 typy zliav

V odpovedi posiela vernostný systém nasledujúce hodnoty 3 možné typy zliav pre daného zákazníka a daný účet, ktoré sa majú v Papaya POS aplikovať.

percentage_on_bill

CODE

Status 200

Percentuálna zľava na celý účet. Zľava sa aplikuje na celý účet zákazníka:

JSON

 {
  "discounts": [
    {
      "type": "percentage_on_bill",
      "appliesTo": "bill",
      "percentage": 10,
      "amount": 5.00,
      "description": "10% loyalty discount"
    }
  ],
  "totalDiscount": 5.00,
  "message": "10% discount on entire bill" # will be shown to user
}

percentage_on_item

CODE

Status 200

Percentuálna zľava na jednotlivé položky:

JSON

{
  "discounts": [
    {
      "type": "percentage_on_item",
      "appliesTo": "item",
      "percentage": 20,
      "amount": 3.00,
      "productId": "prod_201", #UUID
      "productName": "Premium Coffee Blend",
      "description": "20% off Premium Coffee Blend"
    }
  ],
  "totalDiscount": 3.00,
  "message": "20% discount on Premium Coffee Blend" # will be shown to user
}

coupon_zero_vat

CODE

Status 200

Zľavový kupón s nulovou DPH. Aplikuje sa v zápornej hodnote ako položka na účte.

JSON

{
  "discounts": [
    {
      "type": "coupon_zero_vat",
      "appliesTo": "bill",
      "amount": 5.00,
      "vatRate": 0,
      "couponCode": "WELCOME5",
      "description": "Welcome coupon"
    }
  ],
  "totalDiscount": 5.00,
  "message": "Coupon discount: €5 off"  # will be shown to user
}

Endpoint - Zaevidovanie transakcie na Vernostnú kartu zákazníka

Po uzavretí účtu v prípade, že bola načítaná vernostná karta sa dáta ohľadom úspešnej transakcie odošlu na nasledovný endpoint.

Request

JSON

{
      "event": "order.completed",
      "orderId": "00123487979878", #UUID
      "cardId": "memberCardId",
      "paid": 1,
      "status": "closed",
      "total": 25.50,
      "totalWithoutVat": 21.00,
      "currency": "EUR",
      "vat": 4.50,
      "created": "2025-10-21T10:30:00.000Z",
      "completed": "2025-10-21T10:35:12.000Z",
      "branchId": "SLOVAK_PUB",
      "orderItems": [
        {
          "id": "21423423134", #UUID
          "productId": "11111", #UUID 
          "name": "Espresso",
          "quantity": 2,
          "unitPrice": 2.50,
          "totalPrice": 5.00,
          "vat": 1.00,
          "vatRate": 20
        },
        {
          "id": "21423423135", #UUID
          "productId": "11111", #UUID
          "name": "Croissant",
          "quantity": 1,
          "unitPrice": 3.50,
          "totalPrice": 3.50,
          "vat": 0.70,
          "vatRate": 20
        }
      ],
    }

Response

Header

CODE

Status 200

JSON

{
  "success": true,
  "message": "Order processed successfully",
  "orderDetails": {
    "orderId": "00123487979878", #UUID/String
  }
}

Error responses

Nepodporovaný typ Event

Header

CODE

Status 400

Body

JSON

{
  "error": "Unsupported event type",
  "message": "Event type 'order.nieco' is not supported",
  "error_id": 1
}

Chýba parameter v request

Header

CODE

Status 400

Body

JSON

{
  "error": "Missing required field",
  "message": "orderId is required",
  "error_id": 2
}

Zákaznícka karta sa nenašla

Header

CODE

Status 400

Body

JSON

{
  "error": "Customer not found",
  "message": "No customer found with the provided customerId or cardId",
  "error_id" : 3
}