שגיאות ועימוד (Pagination) #

דף זה מכסה שני דברים שכל אינטגרציה צריכה לדעת לטפל בהם: כיצד נראית בקשה שנכשלה, וכיצד לבצע עימוד (pagination) בנקודות קצה שמחזירות רשימות.

מעטפת השגיאה #

כאשר בקשה נכשלת, התגובה היא תמיד בפורמט JSON בעל אותו מבנה — דגל success המוגדר כ-false, הודעת error קריאה לבני אדם, וערך error_code מספרי התואם לקוד הסטטוס של ה-HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

מכיוון ש-success ו-error_code תמיד נוכחים, ניתן להסתמך עליהם לביצוע התניות מבלי לבדוק את קודי הסטטוס הגולמיים של ה-HTTP, אם תעדיפו זאת. תגובה מוצלחת תמיד תכיל success: true.

קודי סטטוס #

להלן כמה דוגמאות לאופן שבו זה נראה בפועל:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

{
  "success": false,
  "error": "A contact with this phone number already exists",
  "error_code": 409
}

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

טיפול נכון בשגיאות #

• בדוק את success (או את קוד הסטטוס) לפני קריאת הנתונים. אל תניח שגוף התגובה מכיל את השדה שאתה מצפה לו.
• נסה שוב עבור 429 ו-500 עם השהיה קצרה — המתן, ואז נסה שוב. אל תנסה שוב עבור 400, 401, 403, 404, או 409; אלו ימשיכו להיכשל עד שתשנה את הבקשה.
• קרא את הודעת ה-error. היא בדרך כלל מציינת בדיוק איזה שדה אינו תקין.

עימוד (Pagination) #

נקודות קצה של רשימות (כגון GET /contacts, GET /campaigns, ו-GET /tasks) מחזירות תוצאות בדפים, כך שקריאה בודדת לעולם לא תצטרך לטעון את כל החשבון שלך. העימוד משתמש בסמן (cursor) אטום.

שני פרמטרי שאילתה שולטים בכך:

כל דף כולל שדה next_cursor בתגובה:

• אם next_cursor הוא מחרוזת, ישנן תוצאות נוספות — העבר אותו כ-cursor בבקשה הבאה שלך.
• אם next_cursor הוא null, הגעת לעמוד האחרון. עצור.

עמוד בודד של אנשי קשר נראה כך:

{
  "success": true,
  "contacts": [
    { "id": "abc123", "first_name": "Jane", "phone_number": "+15551234567" },
    { "id": "def456", "first_name": "John", "phone_number": "+15557654321" }
  ],
  "next_cursor": "eyJsYXN0IjoiZGVmNDU2In0"
}

דפדוף בין כל אנשי הקשר #

כדי לאסוף רשימה מלאה, התחל ללא סמן והמשך לקרוא עד ש-next_cursor יחזור כ-null.

cURL

דוגמה זו עוברת ידנית על שני העמודים הראשונים. הרץ את הקריאה הראשונה, העתק את ה-next_cursor מהתגובה שלה לתוך CURSOR, ולאחר מכן הרץ את הקריאה השנייה. חזור על הפעולה עד ש-next_cursor יהיה null.

# First page
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100"

# Next page — paste the next_cursor from the previous response
CURSOR="eyJsYXN0IjoiZGVmNDU2In0"
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY&limit=100&cursor=$CURSOR"

JavaScript

async function getAllContacts() {
  const all = [];
  let cursor = null;

  do {
    const url = new URL("https://api.youraiconnector.com/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { "X-API-Key": "YOUR_API_KEY" },
    });
    const data = await res.json();

    if (!data.success) throw new Error(data.error);

    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);

  return all;
}

Python

import requests

def get_all_contacts():
    all_contacts = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        res = requests.get(
            "https://api.youraiconnector.com/v1/contacts",
            params=params,
            headers={"X-API-Key": "YOUR_API_KEY"},
        )
        data = res.json()

        if not data["success"]:
            raise Exception(data["error"])

        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]

        if not cursor:
            break

    return all_contacts

אותה לולאה עובדת עבור כל נקודת קצה עם דפדוף — פשוט שנה את הנתיב ואת השדה שאתה קורא מהתגובה (campaigns, tasks, וכן הלאה).

צעדים הבאים #

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