# שליחת אירוע

שליחת אירוע ל-API של Pristo עם POST /v1/events/send כדי להפעיל הפצה מבוססת אירועים עבור איש קשר, כולל דוגמאות לבקשה ולתשובה.

הבקשה `POST https://api.pristo.io/v1/events/send` מדווחת ל-Pristo CX על אירוע של איש קשר, למשל רכישה. בעקבות הבקשה, Pristo CX מוסיפה את איש הקשר לאוכלוסייה של התוכנית שאליה שייך מפתח ה-API או מעדכנת אותו שם, והפצות פעילות מבוססות אירועים שבוחרות בסוג האירוע הזה שולחות את השאלון שלהן ב-SMS או באימייל.

## לפני שמתחילים

- מפתח API: מפתח של התוכנית. ראו [אימות באמצעות מפתח API](https://docs.pristo.io/he/cx/api/authentication).
- חבילה: גישה ל-API דורשת את החבילה הסטנדרטית או את חבילת פרימיום. המערכת מציגה את הדף **הפצות**, שבו מגדירים הפצות מבוססות אירועים, רק בחבילת פרימיום.
- אוכלוסייה: לתוכנית יש אוכלוסייה. אם בלשונית **אוכלוסיה** מופיעה ההודעה **עדיין אין אוכלוסיה לתוכנית הזו**, ה-API מחזיר `404`. ראו [סקירה כללית של אוכלוסיות](https://docs.pristo.io/he/cx/populations/overview).
- סוג אירוע: בלשונית **אוכלוסיה**, פתחו את התפריט **פעולות** > **מאפייני אירועים** > **סוגי אירועים**. הערך בשדה **מזהה יחודי** של סוג האירוע הוא הערך שאתם שולחים ב-`type`.
- הפצה: הפצה פעילה מבוססת אירועים בוחרת בסוג האירוע הזה. ראו [שליחת סקרים אחרי אירוע](https://docs.pristo.io/he/cx/distributions/event-based).

## שלבים

1. בנו את גוף ה-JSON עם `type` ו-`contact.id`. הוסיפו `contact.email` או `contact.phone` כדי שאיש הקשר יוכל לקבל את הסקר.

2. שלחו את הגוף לכתובת `https://api.pristo.io/v1/events/send` עם הכותרות `X-API-Key` ו-`Content-Type: application/json`.

3. שמרו את ה-`eventId` מהתשובה.

4. בדקו את האירוע ב-Pristo CX: פתחו את איש הקשר בלשונית **אוכלוסיה**. האירוע מופיע בקטע **אירועים**, עם הסטטוס שלו.

```bash
curl -X POST "https://api.pristo.io/v1/events/send" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "contact": {
      "id": "CUST-1042",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "name": "Dana",
      "lastName": "Example",
      "language": "en",
      "customFields": { "tier": "gold" }
    },
    "customFields": { "branch": "example_branch", "amount": "120" }
  }'
```

## גוף הבקשה

| שדה | סוג | חובה | מה הוא עושה |
|---|---|---|---|
| `type` | string | כן | הערך בשדה **מזהה יחודי** של סוג האירוע. 1 עד 50 תווים |
| `contact` | object | כן | איש הקשר שהאירוע קרה לו |
| `contact.id` | string | כן | המזהה שלכם לאיש הקשר, 1 עד 50 תווים. לפי המזהה הזה Pristo CX מאתרת איש קשר קיים, בלי הבחנה בין אותיות גדולות לקטנות, או יוצרת איש קשר חדש |
| `contact.email` | string | לא | כתובת האימייל של איש הקשר. המערכת מתעלמת מכתובת לא תקינה |
| `contact.phone` | string | לא | מספר נייד ישראלי, למשל `+972501234567` או `0501234567`. מספרים אחרים נשמרים, אבל אי אפשר לשלוח אליהם SMS |
| `contact.name`, `contact.lastName` | string | לא | שם פרטי ושם משפחה. ערכים ארוכים יותר נחתכים ל-50 תווים |
| `contact.language` | string | לא | קוד בן שתי אותיות, למשל `he` או `en`. אם לא שולחים אותו, איש הקשר מקבל את שפת ברירת המחדל של האוכלוסייה |
| `contact.customFields` | object | לא | ערכים של מאפייני איש הקשר. המפתח של כל ערך הוא הערך בשדה **מזהה יחודי** של המאפיין, בחלון **מאפייני אנשי קשר**. המערכת מתעלמת ממפתחות לא מוכרים ומערכים שלא מתאימים למאפיין |
| `customFields` | object | לא | ערכים של מאפייני האירוע. המפתח של כל ערך הוא הערך בשדה **מזהה יחודי** של מאפיין האירוע, בלשונית **מאפיינים**. מסנני ההפצה קוראים כל ערך לפי הסוג של מאפיין האירוע, וערך שאי אפשר לקרוא כך לא עומד בתנאי של המסנן |

חוץ מ-`contact.language`, שדות שלא שולחים שומרים על הערכים שכבר שמורים אצל איש הקשר. ה-API מתעלם משדות שהוא לא מכיר, כמו `occurredAt`: זמן האירוע הוא הזמן שבו Pristo CX מקבלת אותו.

## התוצאה

ה-API עונה `200 OK` עם המזהה של האירוע:

```json
{
  "eventId": "AbCdEfGhIjKlMnOpQrStUv"
}
```

התשובה `200` אומרת שהאירוע נשמר ב-Pristo CX. לאחר מכן Pristo CX מעדכנת את איש הקשר ומתזמנת את הסקר, ולכן הם מופיעים זמן קצר אחרי שהקריאה מסתיימת, לא בזמן שהיא רצה.

הנתיב הישן `POST /v1/events/send/{popId}` עדיין עובד ועושה אותו דבר. המערכת מתעלמת מה-`popId` שלו: האוכלוסייה נקבעת תמיד לפי התוכנית של מפתח ה-API. בקוד חדש השתמשו ב-`/v1/events/send`.

## מגבלות

- גוף הבקשה יכול להיות עד 10,000 בייטים. רק השדות שה-API מכיר נספרים במגבלה, וכל תו שאינו ASCII, למשל אות בעברית, נספר כ-6 בייטים.
- `type` ו-`contact.id`: 1 עד 50 תווים כל אחד.
- כללי המרווח של ההפצה קובעים באיזו תדירות איש קשר יכול לקבל את הסקר. גם במרווח של 0 ימים נשמרות לפחות 10 דקות בין שני סקרים לאותו איש קשר, כולל סקרים שתוזמנו ועדיין לא נשלחו.

## פתרון בעיות

**ה-API החזיר `200`, אבל לא נשלח סקר.** בדקו ש-`type` תואם לסוג אירוע שהפצה פעילה מבוססת אירועים בוחרת בו, ושלאיש הקשר יש כתובת אימייל להפצה באימייל או מספר נייד ישראלי להפצה ב-SMS. איש קשר שהוסר מרשימת התפוצה, או שלא תואם למסננים של ההפצה, לא מקבל כלום. גם ההשהיה וחלונות השליחה של ההפצה יכולים לדחות את השליחה למועד מאוחר יותר.

**ה-API החזיר `404` עם `no population is associated with this api key`.** לתוכנית של מפתח ה-API אין אוכלוסייה. צרו קודם את האוכלוסייה, או השתמשו במפתח של תוכנית שיש לה אוכלוסייה.

**השפה של איש הקשר השתנתה.** כש-`contact.language` חסר, Pristo CX מגדירה לאיש הקשר את שפת ברירת המחדל של האוכלוסייה. שלחו את `contact.language` בכל אירוע.

**ה-API החזיר `400` או `401`.** ברוב תשובות ה-`400` הגוף מתאר את הבעיה בטקסט פשוט. תשובת `401` פירושה שמפתח ה-API חסר או לא פעיל. ראו [שגיאות API](https://docs.pristo.io/he/cx/api/errors).

## ראו גם

- [שליחת סקרים אחרי אירוע](https://docs.pristo.io/he/cx/distributions/event-based)
- [סקירה כללית של אוכלוסיות](https://docs.pristo.io/he/cx/populations/overview)
- [ייבוא פעילויות](https://docs.pristo.io/he/cx/populations/import-activities)
- [אימות באמצעות מפתח API](https://docs.pristo.io/he/cx/api/authentication)
- [שגיאות API](https://docs.pristo.io/he/cx/api/errors)
- [תיעוד ה-API: שליחת אירוע (באנגלית)](https://docs.pristo.io/cx/api/reference/operations/sendevent)