# יצירת קישור לסקר

יצירת קישור חד פעמי או רב פעמי לשאלון באמצעות ה-API של Pristo, הגדרת מועד התפוגה שלו וצירוף שדות מותאמים אישית למשוב.

הבקשה `POST https://api.pristo.io/v1/links/generate/{prjId}` יוצרת קישור אישי לשאלון אחד ב-Pristo CX ומחזירה את כתובת ה-URL שלו. אתם שולחים את הכתובת למשיב בערוץ שלכם, למשל בצ'אט או בקבלה, והתשובות מגיעות יחד עם שאר המשובים של השאלון.

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

- מפתח API: מפתח של התוכנית, בחבילה הסטנדרטית או בחבילת פרימיום. ראו [אימות באמצעות מפתח API](https://docs.pristo.io/he/cx/api/authentication).
- שאלון: השאלון פורסם, ובלשונית **שיתוף** שלו מוגדר המצב **פעיל**. ראו [שיתוף שאלון](https://docs.pristo.io/he/cx/questionnaires/share-a-questionnaire).
- מזהה שאלון: ה-`prjId` של השאלון, מזהה מקוצר בן 22 תווים.

## שלבים

1. לחצו על הלשונית **ניהול** > **שאלונים** ופתחו את השאלון.

2. לחצו על הלשונית **שיתוף**.

3. בקטע **API למפתחים**, העתיקו את מזהה השאלון. אותו מזהה מופיע בשורת הכתובת של הדפדפן, אחרי `/manage/projects/`.

4. שלחו בקשת `POST` לכתובת `https://api.pristo.io/v1/links/generate/` ואחריה המזהה, עם הכותרות `X-API-Key` ו-`Content-Type: application/json` ועם גוף JSON. כדי להשתמש בכל ערכי ברירת המחדל, שלחו `{}`.

5. שלחו למשיב את ה-`url` מהתשובה.

```bash
curl -X POST "https://api.pristo.io/v1/links/generate/QUESTIONNAIRE_ID" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInMinutes": 10080,
    "language": "en",
    "isReusable": false,
    "title": "Order 1042",
    "customFields": { "order_id": "1042", "channel": "chat" }
  }'
```

## גוף הבקשה

כל השדות אופציונליים, אבל הגוף עצמו חובה.

| שדה | סוג | ברירת מחדל | מה הוא עושה |
|---|---|---|---|
| `expiresInMinutes` | integer | ללא תפוגה | מספר הדקות עד שתוקף הקישור פג, מ-1 עד 1,576,800 (3 שנים) |
| `isReusable` | boolean | `false` | `false` יוצר קישור חד פעמי. `true` מאפשר לקישור לאסוף משוב חדש בכל פעם שמישהו פותח אותו |
| `language` | string | `he` | קוד בן שתי אותיות לפי ISO 639-1. הקוד נשמר ב-Pristo CX יחד עם הקישור, מופיע במשוב, וקובע את השפה של הדף שהמשיב רואה כשתוקף הקישור פג או כשכבר השתמשו בו |
| `title` | string | אין | תווית לקישור, עד 50 תווים |
| `customFields` | object | אין | ערכים משלכם, למשל מספר הזמנה. המפתחות והערכים הם מחרוזות של עד 50 תווים |

> **הערה**
>
> השאלון נפתח בשפת ברירת המחדל שלו, בלי קשר לערך של `language`. כדי להציע למשיבים שפות נוספות, ראו [תרגום שאלון](https://docs.pristo.io/he/cx/form-builder/translate-a-questionnaire).

## התוצאה

ה-API עונה `200 OK`:

```json
{
  "linkId": "11111111-2222-3333-4444-555555555555",
  "url": "https://go.pristo.io/l/AbCdEfGhIjKlMnOpQrStUv"
}
```

השדה `linkId` הוא UUID. הכתובת ב-`url` פותחת את השאלון. הקישור לא משויך לאיש קשר באוכלוסייה.

- קישור חד פעמי שייך למשוב אחד. פתיחה חוזרת שלו ממשיכה את אותו משוב. אחרי שהמשיב שולח את התשובות, הקישור פותח דף תודה במקום השאלון.
- קישור רב פעמי מתחיל משוב חדש בכל פעם שפותחים אותו, עד שתוקפו פג.
- אחרי שעובר מספר הדקות שב-`expiresInMinutes`, הקישור פותח דף שאומר שתוקף הסקר פג.

מנהלי חשבון ומנהלי תוכנית רואים את ה-`title`, את ה-`language` ואת כל השדות המותאמים אישית בפרטי המשוב, תחת **פרטי קישור**. קישורים שנוצרו דרך ה-API לא מופיעים ברשימת הקישורים בלשונית **שיתוף**.

## מגבלות

- `expiresInMinutes`: 1 עד 1,576,800.
- `language`: בדיוק 2 אותיות, וקוד ISO 639-1 קיים.
- `title`: עד 50 תווים.
- `customFields`: ערכים מסוג מחרוזת בלבד, ומפתחות וערכים של עד 50 תווים כל אחד.
- גוף הבקשה יכול להיות עד 10,000 בייטים.

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

**ה-API החזיר `400` עם `provided surveyId is not valid`.** הנתיב לא מסתיים במזהה השאלון בן 22 התווים. UUID מלא לא עובד. העתיקו את המזהה מהקטע **API למפתחים**.

**ה-API החזיר `404` עם `project with id … not found`.** בחשבון של מפתח ה-API אין שאלון עם המזהה הזה, או שהשאלון נמחק.

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

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

## ראו גם

- [שיתוף שאלון](https://docs.pristo.io/he/cx/questionnaires/share-a-questionnaire)
- [צפייה במשובים](https://docs.pristo.io/he/cx/responses/view-responses)
- [אימות באמצעות מפתח 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/generatesurveylink)