☰ Meniu · Tranzacții
Referință API

Tranzacții

Un bon închis, trimis de casă. Aduce cashback sau ștampile, poate folosi cashback, poate fi anulat.

Obiectul transaction

external_idstring
Id-ul tău de bon. Unic per local.
statusstring
completed sau voided.
amountinteger
Bonul întreg, în subunități.
redeem_amountinteger
Partea plătită cu cashback.
net_amountinteger
amount − redeem_amount.
cashback_earned, stamps_earnedinteger
Ce a adus bonul.
reward_unlockedboolean
Acest bon a completat un card de ștampile.
currency, register_id, closed_atstring
Așa cum au fost trimise.
locationobject
Doar când bonul a ajuns la o locație cu reguli proprii: {id, name, store_code, register_id, matched_by}. matched_by este register_id sau store_id. Vezi cum transmiteți locația și casa.
cashierobject
Doar când bonul a fost trimis cu cashier: {id, name}.
memberobject
Membrul după bon, cu noul sold.
amount_refundedinteger
Totalul retururilor parțiale de până acum.
line_itemsarray
Pozițiile bonului și ce a făcut fiecare: amount (partea poziției din bon), cashback_earned, earn_percent (null când categoria nu acumulează), redeemable (se putea plăti cu cashback) și quantity_refunded. Gol când bonul a venit fără poziții.
line_items[].promoboolean
Doar pentru localurile cu reguli pentru promoții: dacă linia a fost trimisă ca produs în promoție.
displayobject
cashier_text și receipt_lines în limba oaspetelui, gata de tipărit.
POST/v1/transactions
Permisiune: transactions:write

Aplică un bon închis. Un external_id repetat întoarce rezultatul salvat, cu 200. card_number și gross_amount sunt acceptate ca alias pentru member și amount.

external_idstring, obligatoriu
Id-ul tău de bon, până la 128 de caractere.
memberstring, obligatoriu
Numărul cardului, valoarea scanată, seria, id-ul membrului sau telefonul.
amountinteger, obligatoriu
Bonul întreg înainte de cashback, în subunități, mai mare decât zero.
redeem_amountinteger
Cashback-ul folosit de oaspete pe acest bon. Implicit 0. Plafonat de sold și de redeem_max_percent al programului.
currencystring
ISO 4217. Implicit: moneda programului.
closed_atdatetime
Momentul închiderii bonului, ISO 8601 cu fus orar. Implicit: acum.
register_idstring
Id-ul casei sau al locației tale. Apare în rapoarte. Dacă proprietarul a legat acest cod de o locație, bonul urmează regulile de cashback ale locației.
store_idstring
Codul magazinului (locației) din sistemul vostru contabil, până la 64 de caractere. Se folosește când register_id lipsește sau nu este legat de nicio locație. Când ambele indică locații diferite, câștigă register_id. Vezi cum transmiteți locația și casa.
cashierstring or object
Cine a emis bonul, așa cum îl știe casa dvs.: un șir (nume sau cod) sau {id, name}. Se salvează cu bonul și se întoarce în cashier. Nu schimbă niciodată cashback-ul și nu intră în verificarea de idempotență. Semnalele casierilor ale proprietarului îl folosesc ca să arate cine a emis un bon suspect.
hold_iduuid
Confirmă această rezervare în loc să trimiți redeem_amount.
discount_typestring
Codul reducerii pe acest bon (employee, discount_card, promo), până la 64 de caractere. Cu tipurile de reduceri pornite se aplică regulile proprietarului. O linie poate avea și propriul discount_type.
line_items[].promoboolean
true când produsul este în promoție. Atunci regulile pentru promoții ale proprietarului decid dacă linia acumulează și dacă poate fi plătită cu cashback. Ignorat dacă localul nu a pornit regula.
line_itemsarray
Până la 500 de elemente {sku, name, quantity, unit_price, category}. Se păstrează împreună cu bonul pentru rapoartele de produse și sunt folosite de regulile categoriilor: o categorie fără cashback, care nu se poate plăti cu cashback (produse la promoție) sau cu procentul ei propriu. Fără category căutăm categoria după sku în catalog. Fără poziții, tot bonul acumulează la nivelul oaspetelui.

Cum transmiteți locația și casa

Trimiteți două șiruri opționale cu fiecare bon (POST /v1/transactions), calcul (POST /v1/checks/calculate) și rezervare (POST /v1/holds): register_id este codul casei, store_id este codul magazinului (locației) în sistemul vostru contabil, până la 64 de caractere. Proprietarul introduce ambele coduri în Locații. Locația se caută întâi după register_id; dacă codul casei lipsește sau nu este legat de nicio locație, după store_id. Dacă sunt trimise ambele și indică locații diferite, câștigă register_id. Dacă nu se găsește nimic, bonul urmează regulile generale, iar codurile necunoscute apar la proprietar în lista „nelegate”. Codurile funcționează când localul are regulile pe locații pornite; altfel câmpurile sunt ignorate. Trimiteți ambele câmpuri cu fiecare bon, chiar și cu o singură locație.

Cerere · POST /v1/transactions
{
  "external_id": "000131",
  "member": "2000111703779",
  "amount": 12550,
  "store_id": "122927",
  "register_id": "122930",
  "line_items": [
    { "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
    { "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
  ]
}

Calculul și tranzacția au atunci un obiect location cu locația la care s-a calculat bonul: id, name, store_code, register_id și matched_by (register_id sau store_id). Fără location în răspuns, bonul a urmat regulile generale.

Răspuns · 201 (fragment)
{
  "object": "transaction",
  "external_id": "000131",
  "register_id": "122930",
  ...
  "location": {
    "object": "location",
    "id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
    "name": "Store 1",
    "store_code": "122927",
    "register_id": "122930",
    "matched_by": "register_id"
  }
}
curl
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000123",
    "member": "2000111703779",
    "amount": 25000,
    "currency": "MDL",
    "register_id": "POS-1",
    "store_id": "S-1",
    "closed_at": "2026-10-06T18:17:00+03:00",
    "line_items": [
      { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
      { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
    ]
  }'
Răspuns · 201
{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "completed",
  "amount": 25000,
  "redeem_amount": 0,
  "cashback_earned": 1250,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "net_amount": 25000,
  "currency": "MDL",
  "register_id": "POS-1",
  "closed_at": "2026-10-06T15:17:00+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:17:17.921+00:00",
  "voided_at": null,
  "amount_refunded": 0,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
  ],
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}
GET/v1/transactions/{external_id}
Permisiune: transactions:write

Întoarce o tranzacție după id-ul tău de bon.

POST/v1/transactions/{external_id}/void
Permisiune: transactions:write

Anulează un bon: cashback-ul și ștampilele acumulate se retrag, cashback-ul folosit revine. O anulare repetată nu are niciun efect.

curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."
Răspuns · 200
{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "voided",
  "amount": 25000,
  "cashback_earned": 1250,
  "voided_at": "2026-10-06T18:17:21.003+00:00",
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
    ...
  },
  ...
}
POST/v1/transactions/{external_id}/refunds
Permisiune: transactions:write

Returnează o parte dintr-un bon cu cashback, după amount sau după line_items. După sumă, cashback-ul se recalculează proporțional cu bonul. După poziții, cashback-ul urmează ce a acumulat cu adevărat fiecare poziție: un produs la promoție care nu a acumulat nimic nu retrage nimic, iar cashback-ul cheltuit de oaspete revine doar pentru pozițiile care se puteau plăti cu el. Trimiteți propriul external_id al returnării; repetarea lui este sigură. Se pot face mai multe returnări pe un bon; ultima închide exact resturile. Bonurile programelor cu ștampile și vizite se returnează integral prin anulare.

external_idstring, obligatoriu
Id-ul vostru al acestei returnări, până la 128 de caractere.
amountinteger
Suma returnată în unități minime. Nu o trimiteți când line_items spun ce s-a returnat.
line_itemsarray
Pozițiile returnate: {sku, quantity} sau {name, quantity}, exact ca pe bon. Unitățile deja returnate se iau în calcul; cererea unui număr mai mare răspunde refund_exceeds_line cu refundable. Un bon trimis fără poziții răspunde no_line_items: returnați-l după sumă.
line_items[].promoboolean
Acceptat și ignorat: returul urmează ce a acumulat și ce putea plăti linia inițială.
register_idstring
Id-ul casei voastre, pentru numerotarea pe case.
store_idstring
Codul magazinului vostru. Este acceptat pentru simetrie cu bonul; returul urmează locația bonului inițial.
curl
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000017", "amount": 5000 }'

# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
Răspuns · 201
{
  "object": "refund",
  "id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
  "external_id": "RET-2026-000017",
  "transaction": "CHK-2026-000124",
  "amount": 5000,
  "cashback_reversed": 200,
  "redeem_restored": 1000,
  "line_items": [],
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

// by lines
{
  "object": "refund",
  "external_id": "RET-2026-000018",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Permisiune: transactions:write

Returnează una sau mai multe poziții ale unui bon: oaspetele aduce înapoi un produs din trei. Cashback-ul acumulat pe acele poziții se retrage, iar cashback-ul cu care le-a plătit revine, după ce a acumulat fiecare poziție și cu ce se putea plăti, niciodată proporțional cu bonul. Răspunsul este același obiect ca la o returnare, cu object: "return". Trimiteți propriul external_id al returnării; repetarea lui este sigură. Bonurile trimise fără line_items nu se returnează pe poziții: returnați-le după amount.

external_idstring, obligatoriu
Id-ul vostru al acestei returnări, până la 128 de caractere.
line_itemsarray, obligatoriu
Pozițiile returnate: {sku, quantity} sau {name, quantity}, exact ca pe bon. Unitățile deja returnate se iau în calcul; cererea unui număr mai mare răspunde refund_exceeds_line cu refundable.
line_items[].promoboolean
Acceptat și ignorat: returul urmează ce a acumulat și ce putea plăti linia inițială.
register_idstring
Id-ul casei voastre, pentru numerotarea pe case.
store_idstring
Codul magazinului vostru. Este acceptat pentru simetrie cu bonul; returul urmează locația bonului inițial.
curl
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
"Răspuns · 201"
{
  "object": "return",
  "id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
  "external_id": "RET-2026-000019",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  "livemode": false,
  "created_at": "2026-11-06T09:12:40.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}
GET/v1/transactions
Permisiune: transactions:write

Listează tranzacțiile, cele mai noi primele. Filtrează cu ?member=. Cu paginare.

Întrebări despre integrare: api@loyaltyfy.io. Răspundem în cel mult o zi lucrătoare.