توثيق المطوّرين

واجهة نقطة البرمجية لأنظمة نقاط البيع

اربط أي نظام نقاط بيع ببرنامج الولاء لدى التاجر في نقطة: تحقّق من بطاقة العميل، أضف النقاط عند البيع، استبدل المكافآت وألغِ الأخطاء. JSON عبر HTTPS ومصادقة OAuth 2.0.

التفاصيل التقنية أدناه باللغة الإنجليزية، كما هو معتاد في توثيق الواجهات البرمجية.

Base URL https://nuqtaloyalty.com/api/v1

Overview

Each merchant has its own credentials, so a POS only ever sees that merchant's customers. The flow is:

  1. The Nuqta team generates a client ID and client secret for the merchant in the admin panel. The secret is shown once; store it in your POS's secret store.
  2. Your POS exchanges them for an access token (valid 1 hour).
  3. Every API call sends Authorization: Bearer <access_token>. When the token expires, request a new one.

All amounts are decimal strings in the merchant's currency (JOD has 3 decimals: "18.750"). Points are integers. Times are ISO 8601.

Authentication

POST /pos/oauth/token — OAuth 2.0 client credentials grant. Send the credentials as form fields, JSON, or HTTP Basic auth.

curl -X POST https://nuqtaloyalty.com/api/v1/pos/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=client_credentials \
  -d client_id=nq_xxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_secret=nqs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP/1.1 200 OK
{
  "access_token": "41|Qm9vZ…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pos:lookup pos:earn pos:redeem pos:void",
  "merchant": "demo-cafe"
}
ErrorHTTPMeaning
invalid_request400client_id or client_secret missing
unsupported_grant_type400grant_type must be client_credentials
invalid_client401Wrong or revoked credentials, or the merchant is paused
invalid_client429Too many failed attempts for this client (see Retry-After)

The scope lists what the credentials may do. A call outside that scope returns 403 FORBIDDEN. Revoking the credentials in the admin panel ends every token issued with them immediately.

Verify a card

POST /pos/lookup (scope pos:lookup). Send one of: barcode (what you scanned from the Wallet pass), membership_number, or phone_number in E.164 (+962791234567).

curl -X POST https://nuqtaloyalty.com/api/v1/pos/lookup \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"barcode": "WP10000001"}'
{
  "data": {
    "membership_number": "WP10000001",
    "full_name": "Rana Saleh",
    "points_balance": 1250,
    "monetary_value": { "minor": 12500, "amount": "12.500", "currency": "JOD", "formatted_en": "JOD 12.500" },
    "tier": { "code": "GOLD", "name_en": "Gold", "points_to_next_tier": 750 },
    "redemption": { "min_redeem_points": 100, "can_redeem": true },
    "wallet": { "apple_pass_url": "…", "google_save_url": "…" },
    "vouchers": [
      { "id": "9b1e…", "code": "7KQ3M9XP", "kind": "PERCENT_OFF", "percent_off": 20,
        "label_en": "20% off", "title_en": "Weekend treat", "min_spend": null, "expires_at": "2026-10-29T20:59:59Z" }
    ]
  }
}

Unknown cards return 404 CUSTOMER_NOT_FOUND. Lookups never change a balance.

Merchants with several cards (e.g. points and a stamp card) use one set of credentials for all of them: a scanned barcode or membership number always finds the right card, and the response carries its program_slug. A phone_number that has a card in more than one program returns 409 MULTIPLE_CARDS with the cards in error.details.cards; send the chosen membership_number, or add program (the program slug) next to the phone number.

Issue points

POST /pos/transactions/earn (scope pos:earn). Points are calculated by Nuqta from the merchant's earn rate and the customer's tier.

curl -X POST https://nuqtaloyalty.com/api/v1/pos/transactions/earn \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: INV-2231" \
  -d '{
        "barcode": "WP10000001",
        "gross_amount": "18.750",
        "currency": "JOD",
        "receipt_number": "INV-2231",
        "occurred_at": "2026-09-28T10:38:15Z"
      }'
FieldRequiredNotes
barcode / membership_number / phone_numberone ofIdentifies the card
programoptionalProgram slug, when a phone number has cards in several programs
gross_amountyesDecimal string, at most the currency's decimals
idempotency_keyyesBody field or Idempotency-Key header
receipt_numbernoUp to 100 characters; shown in reports
occurred_atnoWithin the last 30 days
metadatanoUp to 25 keys of your own (e.g. cashier id)

Returns 201 with data.transaction (points, balance before and after, tier change) and the updated data.customer. The customer's Wallet card updates within seconds.

Redeem

POST /pos/transactions/redeem (scope pos:redeem). Spend points as a discount on the current sale.

curl -X POST https://nuqtaloyalty.com/api/v1/pos/transactions/redeem \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"idempotency_key": "burn-INV-2232", "membership_number": "WP10000001", "points": 500}'

The balance is checked under a lock, so two tills can never spend the same points. Not enough points returns 422 INSUFFICIENT_BALANCE with details.available_points; below the merchant's minimum returns 422 INVALID_POSTING. The response's gross_amount is the discount value to apply on the receipt.

Void

POST /pos/transactions/void (scope pos:void). Reverses an earn or a redemption exactly, for refunds and mistakes. A transaction can be voided once.

curl -X POST https://nuqtaloyalty.com/api/v1/pos/transactions/void \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"idempotency_key": "void-INV-2231", "original_transaction": "INV-2231", "reason": "Returned goods"}'

original_transaction is the transaction UUID from the earlier response, or the idempotency key you used for it.

Coupons

Merchants create voucher campaigns in their portal; each member gets a personal coupon code. A lookup lists the member's usable coupons in data.vouchers. To use one on the current sale call POST /pos/vouchers/redeem (scope pos:redeem):

curl -X POST https://nuqtaloyalty.com/api/v1/pos/vouchers/redeem \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"idempotency_key": "cpn-INV-2240", "membership_number": "WP10000001",
       "coupon": "7KQ3M9XP", "order_total": "12.500", "receipt_number": "INV-2240"}'
{ "data": { "coupon": { "code": "7KQ3M9XP", "status": "REDEEMED", … },
            "settlement": { "order_total": { "amount": "12.500" }, "discount": { "amount": "2.500" }, "amount_due": { "amount": "10.000" } } } }
KindDiscountorder_total
PERCENT_OFFPercentage of the order, rounded downrequired
AMOUNT_OFFFixed amount, never more than the orderrequired
FREE_ITEM0 – hand over the gift named in title_enoptional

coupon is the coupon's id or its printed code. Each coupon works once: a used, expired or below-minimum coupon returns 422 COUPON_UNAVAILABLE with details.reason (USED, EXPIRED, MIN_SPEND, ORDER_TOTAL_REQUIRED); a code that isn't this member's returns 404 COUPON_NOT_FOUND. Coupons are discounts only – they don't change the points balance. Apply the coupon first, then earn points on amount_due.

Idempotency

Every earn, redeem and void needs a unique idempotency_key (your receipt number works well). If the network drops, retry with the same key: Nuqta returns the original result instead of posting twice. Reusing a key with a different payload returns 409 IDEMPOTENCY_KEY_REUSED.

Errors & limits

Every error from the POS endpoints has the same shape:

{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "…", "details": { "available_points": 18 } } }
CodeHTTPMeaning
VALIDATION_FAILED422details lists field errors
UNAUTHENTICATED / FORBIDDEN401 / 403Missing or expired token, or outside the token's scope
TERMINAL_INACTIVE / TENANT_INACTIVE / CUSTOMER_INACTIVE423Credentials revoked, merchant paused, or card closed
CUSTOMER_NOT_FOUND / TRANSACTION_NOT_FOUND404Unknown card or transaction for this merchant
AMBIGUOUS_TRANSACTION409A void by receipt key that was used on more than one card: send the transaction id, or program
MULTIPLE_CARDS409The phone number has cards in several programs: pick one (error.details.cards)
INSUFFICIENT_BALANCE422Not enough points (also when voiding an earn already spent)
INVALID_POSTING422Below the minimum redemption, or a purchase too small to earn
TRANSACTION_NOT_VOIDABLE422Already voided, or not an earn or redemption
IDEMPOTENCY_KEY_REUSED409Same key, different payload
RATE_LIMITED429Default 600 requests per minute per credential; the token endpoint allows 30 per minute per IP

Go-live checklist