LLoyaltyfyAPI v1
KK
☰ Мәзір · Қатысушылар
API анықтамалығы

Қатысушылар

Мекеменің адалдық бағдарламасына тіркелген, бір Wallet картасы бар қонақ.

Қатысушы объектісі

iduuid
Біздегі қонақ id-і.
card_numberstring
Картадағы нөмір. Біздікі (13 таңба) немесе сіз берген нөмір.
serialuuid
Wallet картасының сериялық нөмірі.
first_name, last_name, phone, email, birthday, languagestring
Профиль. phone халықаралық пішімде (+37366791102), birthday пішімі YYYY-MM-DD.
marketing_consentboolean
Қонақ жарнамалық хабарламалар алуға келісті.
programобъект
Қатысушы бағдарламасының id, name, mechanic және barcode пішімі.
stampsобъект немесе null
current, required, rewards_available. Штампсыз бағдарламаларда null.
cashbackобъект немесе null
balance (кіші бірлікте), белсенді резервтердегі held, жұмсауға болатын available, currency, earn_rate (пайыз), level, level_basis, levels, next_level, redeem_max_percent, min_amount, expires_at. Кэшбэксіз бағдарламаларда null. Кэшбэк деңгейлері бөлімін қараңыз.
discountобъект немесе null
Келулерге негізделген жеңілдік бағдарламалары үшін percent, tier, next_at_visits.
visits, total_spentinteger
Барлық уақыттағы келулер саны және жұмсалған сома.
walletобъект немесе null
apple_url, google_url, card_url: картаны қосуға арналған қол қойылған сілтемелер. Жасағанда және ?expand=wallet берілгенде қайтарылады.
JSON
{
  "object": "member",
  "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
  "card_number": "2000111703779",
  "serial": "b90273b1-10c9-46eb-ba74-8fef48266b5d",
  "first_name": "Ion",
  "last_name": "Popescu",
  "phone": "+37366791102",
  "email": null,
  "birthday": null,
  "language": "ro",
  "marketing_consent": false,
  "program": {
    "id": "06af6eba-eaf5-4662-8a5e-2b6b52c65314",
    "name": "Sandbox Cashback",
    "mechanic": "cashback",
    "barcode": "card_code128"
  },
  "stamps": null,
  "cashback": {
    "balance": 1250,
    "currency": "MDL",
    "earn_rate": 5,
    "level": null,
    "redeem_max_percent": 30,
    "min_amount": 10000,
    "expires_at": "2027-01-04T18:17:17.721+00:00"
  },
  "discount": null,
  "visits": 1,
  "total_spent": 25000,
  "wallet": {
    "apple_url": "https://loyaltyfy.io/api/wallet/issue/3832466f-...?platform=apple&t=...",
    "google_url": "https://loyaltyfy.io/api/wallet/issue/3832466f-...?platform=google&t=...",
    "card_url": "https://loyaltyfy.io/wallet/3832466f-...?t=..."
  },
  "created_at": "2026-10-06T18:17:15.594+00:00"
}
POST/v1/members
Құқық: members:write немесе devices:write

Қонақты тіркеп, Wallet картасын шығарады. Осы телефоны бар қатысушы бұрыннан болса, сол қатысушыны 201 орнына 200 кодымен қайтарады. Idempotency-Key жіберіңіз.

phonestring, міндетті
Халықаралық пішім. Мекеме еліндегі жергілікті пішімдер де қабылданады.
first_namestring, міндетті
80 таңбаға дейін.
consenttrue, міндетті
Қонақтың дербес деректерін өңдеуге келіскенін растайды. Онсыз келген сұраулар қабылданбайды.
last_name, email, birthday, languagestring
Міндетті емес профиль өрістері. language (en, ro, ru, es...) карта мен хабарламалар үшін қолданылады.
card_numberstring
4-тен 32-ге дейін әріп, сан немесе сызықша. Кассаның өз карта нөмірін пайдаланыңыз. Мекеме ішінде бірегей.
programstring
GET /v1/account ішіндегі бағдарлама slug мәні. Әдепкі: мекеменің негізгі бағдарламасы.
marketing_consentboolean
Қонақ жарнамалық хабарламаларға келісті. Әдепкі false.
curl
curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7d1b2c4e-enrol-000123" \
  -d '{
    "phone": "+37366791102",
    "first_name": "Ion",
    "last_name": "Popescu",
    "card_number": "2000111703779",
    "language": "ro",
    "consent": true
  }'
Кейбір бағдарламалар тіркелген кезде сәлемдесу штампын береді, сондықтан жаңа қатысушы stamps.current: 1 мәнімен бастауы мүмкін.
GET/v1/members/{member}
Құқық: members:read

{member} дегеніміз карта нөмірі, сканерленген штрихкод мәні, Wallet сериялық нөмірі, қатысушы id-і немесе телефон (URL-кодталған). Wallet ішіне қосуға арналған жаңа сілтемелер үшін ?expand=wallet қосыңыз.

curl
# by the number on the card (or the barcode the scanner read)
curl https://loyaltyfy.io/api/v1/members/2000111703779 \
  -H "Authorization: Bearer sk_test_..."

# by phone, with fresh add-to-wallet links
curl "https://loyaltyfy.io/api/v1/members/%2B37366791102?expand=wallet" \
  -H "Authorization: Bearer sk_test_..."
PATCH/v1/members/{member}
Құқық: members:write

Профиль өрістерін жаңартады немесе кассадан карта нөмірін байлайды. Тек өзгертетін өрістерді жіберіңіз: phone, first_name, last_name, email, birthday, language, card_number, marketing_consent.

curl
curl -X PATCH https://loyaltyfy.io/api/v1/members/%2B37366791102 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "card_number": "2000111703779", "birthday": "1990-04-12" }'
GET/v1/members
Құқық: members:read

Қатысушылар тізімі, жаңасынан бастап. Беттеумен. ?phone= немесе ?card_number= берілсе, нөл немесе бір қатысушыдан тұратын тізім қайтарады.

curl
curl "https://loyaltyfy.io/api/v1/members?limit=50" \
  -H "Authorization: Bearer sk_test_..."
GET/v1/members/{member}/history
Құқық: members:read

Картадағы әр өзгеріс, жаңасынан бастап, себебі қандай болса да: API, мекеменің касса қосымшасы, POS, жазылу коннекторы. type мәндері: accrual, cashback, cashback_earn, gift, reward_redeemed, reversal, жаңа мәндер қосылуы мүмкін. source мәндері: api, pos, cashier немесе system. Беттеумен.

Жауап · 200
{
  "object": "list",
  "url": "/v1/members/2000111703779/history",
  "has_more": false,
  "data": [
    {
      "object": "history_entry",
      "id": "937310bd-cb77-49a0-a4ff-855399f5cde3",
      "type": "cashback_earn",
      "stamps_delta": 0,
      "cashback_delta": 1250,
      "amount": 25000,
      "reward_unlocked": false,
      "source": "system",
      "external_id": null,
      "created_at": "2026-10-06T18:17:17.790+00:00"
    }
  ]
}
POST/v1/members/{member}/rewards/redeem
Құқық: transactions:write немесе devices:write

Қатысушыға жиналған бір штамп сыйлығын беріп, stamps.rewards_available мәнін азайтады. Сыйлық жоқ болса, no_reward_available арқылы қабылданбайды. Idempotency-Key жіберіңіз.

curl
curl -X POST https://loyaltyfy.io/api/v1/members/4285324286429/rewards/redeem \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: reward-4285324286429-0001"
POST/v1/members/{member}/adjustments
Құқық: members:adjust

3-тен 300 таңбаға дейінгі reason көрсетіп кэшбэк қосады (оң amount) немесе алып тастайды (теріс). Мекеме түзетуге рұқсат берген жағдайда ғана, бір түзетуге белгіленген лимитке дейін жұмыс істейді. Қайталанған external_id сақталған түзетуді қайтарады. balance.adjusted жібереді.

curl
curl https://loyaltyfy.io/api/v1/members/2000111703779/adjustments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "ADJ-2026-0009", "amount": 2000, "reason": "Goodwill after a complaint" }'

# a negative amount takes cashback away
Интеграция бойынша сұрақтар: api@loyaltyfy.io. Бір жұмыс күні ішінде жауап береміз.