wivly.

מפתחים

Wivly Infrastructure API

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

ה-API כלול מתוכנית Scale Up ומעלה.

אימות

כל בקשה נושאת מפתח API כ-bearer token. צרו מפתחות בהגדרות ← מפתחים; המפתח המלא מוצג פעם אחת, ביצירה, ונשמר אצלנו כגיבוב בלבד.

curl https://wivly.me/api/v1/passes \
  -H "Authorization: Bearer wivly_..." \
  -H "Content-Type: application/json" \
  -d '{"templateId":"tpl_123","customer":{"name":"Marco"}}'

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

הרשאות מפתח

לכל מפתח יש בדיוק הרשאה אחת. בחרו את הצרה ביותר שעושה את העבודה.

FULL

Everything below. Issue passes, stamp, redeem, notify, manage webhooks.

ISSUE_ONLY

Issue passes and read. Cannot stamp, redeem or notify — the right scope for a signup form on your own site.

READ_ONLY

GET requests only. The right scope for a reporting job or a dashboard you build yourself.

מגבלות קצב

60 בקשות לדקה לכל מפתח. מעבר לזה ה-API מחזיר 429 והבקשה אינה מעובדת — נסו שוב אחרי גבול הדקה הבא ולא מיד.

Endpoints

כל הנתיבים יחסיים ל-https://wivly.me/api/v1 ומחזירים JSON.

POST/passes

Issue a pass

Body: { templateId, customer?: { name?, email? } }. Returns serialNumber, appleUrl, googleSaveUrl. Venue-scoped keys can only issue on their own venues.

הרשאות: FULL, ISSUE_ONLY

GET/passes/{serial}

Read pass state

הרשאות: Any

PATCH/passes/{serial}

Stamp or redeem

Body: { action: "stamp" | "redeem", tier?: 0-2 }.

הרשאות: FULL

POST/passes/{serial}/notify

Send a lock-screen message

Body: { message: string, max 200 chars }. Subject to the org's frequency cap and quiet hours.

הרשאות: FULL

GET/events

Export analytics events

Query: since (ISO 8601), type. Paginated, 500 per page.

הרשאות: Any

GET/analytics/venues

Cross-venue rollups

Query: days (1-365, default 30). Per-venue members, visits, repeat rate, redemptions, revenue, plus cross-venue movement.

הרשאות: Any

GET/webhooks

List webhooks

Secrets are never returned.

הרשאות: Any

POST/webhooks

Register a webhook

Body: { url, events?: string[] }. The signing secret is shown once, on creation.

הרשאות: FULL

DELETE/webhooks/{id}

Delete a webhook

הרשאות: FULL

Webhooks

רשמו כתובת ו-Wivly תשלח אליה כשמשהו קורה. משלוחים נשלחים שוב במקרה של כישלון.

אירועים

pass.addedpass.removedpass.scannedreward.unlockedreward.redeemedprepaid.soldprepaid.debitedprepaid.low_balanceprepaid.spent

אימות משלוח

כל בקשה נושאת כותרת x-wivly-signature: HMAC-SHA256 של גוף הבקשה הגולמי, עם סוד ה-webhook כמפתח. השוו מול הבייטים הגולמיים לפני פענוח, והשתמשו בהשוואה בזמן קבוע.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const received = req.headers["x-wivly-signature"];
const ok =
  received.length === expected.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(received));

אידמפוטנטיות

לכל משלוח יש id יציב בגוף, לצד apiVersion ‏"2026-01-01". ניסיון חוזר משתמש באותו id, אז שמרו אותו והתעלמו ממזהים שכבר טיפלתם בהם.

שגיאות

שגיאות מחזירות גוף JSON עם הודעה, וקוד היכן שהוא מועיל.

401

מפתח API חסר או לא תקין.

403

התוכנית שלכם או ההרשאה של המפתח לא מאפשרות זאת. קוד: PLAN_LIMIT כשהתוכנית היא הסיבה.

404

אין כרטיס, תבנית או webhook כזה — או שהוא שייך לארגון אחר.

429

יותר מ-60 בקשות לדקה למפתח הזה.

OpenAPI

המפרט הקריא-מכונה, ל-Postman, Swagger, Stoplight או יצירת קוד. ציבורי וללא אימות: הוא מתאר את המשטח, לא נתונים.

לפתוח את מפרט ה-OpenAPI ←

לקבל מפתח

פתחו חשבון, ואז מצאו מפתחות API בהגדרות ← מפתחים.

להתחיל בחינםScale Up

הפכו לקוחות קבועים להרגל.

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

להשיק את התוכנית בחינםלתאם דמו
מדריך API · Wivly