מתחילים כאן — ה-API של ReGenerate לרשתות

לאן קוראים, והמפתח שלכם. הדביקו אותו כשהוא מתבקש ולא בתוך שורת הפקודה, שם הוא היה נשאר בהיסטוריה של המעטפת.

# Once per shell. The sandbox: rg_test_ keys, no real money. For production change these two lines only.
BASE=https://api-sandbox.regenerate.co.il/v1
# Paste the rg_test_ key when asked; read -s keeps it off the screen and out of your history.
printf 'API key: '; read -rs KEY; echo

מחליפים את המפתח בטוקן. הוא תקף שעה; כשקריאה עונה 401 unauthenticated, קבלו טוקן חדש עם המפתח וחזרו על הקריאה.

# A token, valid for one hour. The key goes to this endpoint and no other.
ANSWER=$(curl -s -X POST "$BASE/auth/token" \
  -H 'content-type: application/json' \
  -d "{\"apiKey\":\"$KEY\"}")
TOKEN=$(echo "$ANSWER" | jq -r '.accessToken // empty')
# No token: the refusal says why, and section 7 says what to do about it.
if [ -n "$TOKEN" ]; then echo "token: ${TOKEN:0:12}..."; else echo "$ANSWER"; fi

הארנק שלכם.

# The wallet, in agorot: 200000 is ₪2,000.00.
curl -s "$BASE/balance" -H "authorization: Bearer $TOKEN"

הקטלוג, במחיר שלכם. כל SKU הוא קוד ציבורי: RG- ושישה תווים, ספרות ואותיות גדולות בלי 0, O, 1, I ו-L (‏RG-7KQ4MX). הוא קבוע, זהה ב-sandbox ובייצור, ואינו אומר דבר — אין בו ספק, מוצר או ערך, ולכן לעולם אל תפרקו אותו. כמה SKU יכולים לחלוק productName: מותג עם ערכים רבים הוא מוצר אחד עם SKU לכל ערך, ותמיד מזמינים לפי SKU. לכרטיס בסכום חופשי pricingMode: "range": שולחים requestedAmount בתוך minAmount…maxAmount, בכפולות של stepAmount, במטבע של הכרטיס (faceCurrency). חלק מהכרטיסים בסכום חופשי מוצעים גם בערכים מוכנים — אלה SKU קבועים רגילים, ומזמינים אותם כמו כל אחד אחר. price תמיד באגורות; faceValue במטבע הכרטיס, ו-faceValueInIls נותן אותו באגורות לפי אותו שער. cardNote היא ההערה של המוצר, זהה בכל ה-SKU שלו; valueNote היא הערה ל-SKU הזה בלבד — הציגו את שתיהן במקום שבו הלקוח שלכם בוחר כרטיס. המחירים זזים עם שער החליפין: קראו את הקטלוג כל כמה דקות, לא פעם ביום.

# The catalogue at your price. One entry per SKU.
curl -s "$BASE/catalog" -H "authorization: Bearer $TOKEN" | jq '.items[0]'

# The cheapest fixed-value card you can buy now:
SKU=$(curl -s "$BASE/catalog" -H "authorization: Bearer $TOKEN" \
  | jq -r '[.items[] | select(.available and .pricingMode == "fixed")] | sort_by(.price) | .[0].sku')
echo "sku: $SKU"

לפני הזמנה גדולה: האם ה-SKU נמכר עכשיו, ו-maxQuantityPerOrder. כרטיס ששוויו מעל 200 דולר נמכר אחד בהזמנה, אלא אם מנהל הלקוח הגדיל זאת עבורכם; כאן רואים את המספר.

# Whether it sells now, and how many you may order at once.
curl -s "$BASE/catalog/$SKU/availability" -H "authorization: Bearer $TOKEN"

יוצרים הזמנה. reference שלכם: 8 עד 128 אותיות, ספרות ו-. _ : -, ייחודית לכל הזמנה. התשובה מיידית וההזמנה במצב created, לפני שהספק מסר. הזמינו כל כמות שהחשבון מתיר — גודל המנות של הספקים הוא עניין שלנו.

# Your reference is the idempotency key: unique per order, the same on every retry.
REF="TILL-0001-$(date -u +%Y%m%d%H%M%S)"
curl -s -X POST "$BASE/orders" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d "{\"sku\":\"$SKU\",\"quantity\":1,\"reference\":\"$REF\"}"

שלחו את אותה אסמכתא שוב — אחרי timeout, למשל — ותקבלו את ההזמנה הראשונה עם 200, אף פעם לא חיוב שני. האסמכתא קובעת: בקשה שנייה עם אותה אסמכתא וגוף אחר עדיין מחזירה את ההזמנה הראשונה, ולכן השוו את sku ואת quantity בתשובה אם הקוד שלכם עלול לשלוח הזמנות שונות תחת אסמכתא אחת.

# The same request again is the same order, not a second one: 200 instead of 201.
curl -s -o /dev/null -w '%{http_code}\n' -X POST "$BASE/orders" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d "{\"sku\":\"$SKU\",\"quantity\":1,\"reference\":\"$REF\"}"

ממתינים כל עוד המצב created או processing. ‏delivered אומר שהקודים מוכנים. ‏failed ו-refunded סופיים, והארנק כבר זוכה. Webhook ‏(POST /webhooks, בתיאור ה-Endpoints) מודיע במקום שתשאלו.

# Poll until the order is final (or register a webhook and be told).
until curl -s "$BASE/orders/$REF" -H "authorization: Bearer $TOKEN" \
  | jq -e '.status == "delivered" or .status == "failed" or .status == "refunded"' > /dev/null
do sleep 3; done
curl -s "$BASE/orders/$REF" -H "authorization: Bearer $TOKEN" | jq '{status, codesAvailable}'

קוראים את הקודים של הזמנה שנמסרה: מספר כרטיס, PIN כשיש לכרטיס, קישור למימוש כשהספק נותן, תוקף. כל שליפה נספרת ונרשמת.

# The codes. Store them: this is a retrieval endpoint, not a vault.
curl -s "$BASE/orders/$REF/codes" -H "authorization: Bearer $TOKEN" | jq '.codes'

ההזמנות של יום, החדשות קודם, לכל היותר 50 בעמוד; total סופר את כל ההזמנות המתאימות.

# A day of orders, for reconciliation (dates are calendar days in Israel time).
curl -s "$BASE/orders?from=$(date -u +%Y-%m-%d)&to=$(date -u +%Y-%m-%d)&pageSize=50" \
  -H "authorization: Bearer $TOKEN" | jq '{total, first: .items[0].reference}'