BuyPost API — מדריך למפתחים

חיבור

• כתובת אחת: https://ai.buypost.co.il/functions/customerApi, בקשות POST עם גוף JSON שכולל action.
• המפתח נשלח בכותרת Authorization: Bearer bp_live_… בלבד — לא בכתובת ולא בגוף. השתמשו בו רק מהשרת שלכם.
• תשובה מוצלחת: { "ok": true, "data": … } (בפעולות שליחה יש גם message בעברית). שגיאה: { "ok": false, "error": { "code", "message", "hint", "details" } } — hint אומר מה לעשות.
• סכומים בשקלים. *_before_vat — לפני מע"מ (כמו הקרדיטים); *_incl_vat — כולל מע"מ (תשלום בכרטיס). המחיר תמיד מחושב אצלנו.

curl -X POST https://ai.buypost.co.il/functions/customerApi \
  -H "Authorization: Bearer bp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"price_list","limit":20}'

מגבלות שימוש

• עד 10 בקשות בדקה ו-300 בקשות ביום לחשבון (כל המפתחות יחד). כל בקשה נספרת, גם ping. כמה נשאר היום — ב-meta.requests_left_today בכל תשובה.
• מכסת כתבות ביום (ברירת מחדל 30) ומספר הזמנות שמחכות לתשלום בבת אחת (ברירת מחדל 5). המגבלות של החשבון מוחזרות ב-balance; אפשר לבקש להגדיל.
• 20 ניסיונות עם מפתח שגוי מאותה כתובת בתוך 10 דקות — חסימה ל-10 דקות.
• בלי בדיקות חוזרות: הגדירו webhook. כשצריך לבדוק — list_items עם updated_since (רק מה שהשתנה) או get_items (עד 50 כתבות בבקשה אחת), ולא בקשה נפרדת לכל כתבה.
• תשובות קריאה עשויות להגיע מזיכרון קצר (meta.cached). כל שינוי שלכם, כל שינוי סטטוס של כתבה וכל קניית קרדיטים מרעננים אותו מיד.

פעולות

{ "action": "ping" }

{ "action": "balance" }

{ "action": "price_list", "search": "חדשות", "min_dr": 30, "sort": "price_asc", "limit": 50 }

{ "action": "quote", "items": [ ... ] }

{
  "action": "create_order",
  "idempotency_key": "crm-order-10457",
  "items": [
    {
      "website_id": "<id מתוך price_list>",
      "content": { "type": "ai" },
      "article_topic": "איך בוחרים צלם לחתונה בקיץ",
      "writing_style": "seo_with_brand",
      "brand_name": "סטודיו אור",
      "keywords": "צילום חתונות",
      "target_link": "https://example.co.il/weddings",
      "scheduled_date": "2026-10-20",
      "notes": "בלי להזכיר מחירים"
    },
    {
      "website_id": "<id>",
      "content": { "type": "html", "html": "<h1>כותרת</h1><p>הכתבה המוכנה שלכם...</p>" },
      "keywords": "עורך דין גירושין",
      "target_link": "https://example.co.il"
    }
  ]
}

{ "action": "get_order", "order_id": "<id>" }

{ "action": "list_orders", "payment_status": "paid", "created_from": "2026-09-01" }

{ "action": "list_items", "updated_since": "2026-10-02T08:00:00Z" }

{ "action": "get_items", "item_ids": ["<id1>", "<id2>"] }

{ "action": "list_redeemable" }

{ "action": "get_item", "item_id": "<id>" }

{ "action": "approve", "item_id": "<id>" }

{ "action": "request_fix", "item_id": "<id>", "note": "להוסיף פסקה על..." }

{ "action": "submit_edit", "item_id": "<id>", "content_html": "<p>...</p>", "keep_for_review": true }

{ "action": "ai_fix", "item_id": "<id>", "instructions": "לקצר את הפתיח ולהוסיף פסקה על שעות הפתיחה" }

{ "action": "replace_file", "item_id": "<id>", "filename": "article.docx", "file_base64": "..." }

{ "action": "reject_content", "item_id": "<id>", "reason": "הטון לא מתאים למותג" }

{ "action": "cancel", "item_id": "<id>", "reason": "..." }

{ "action": "update_item", "item_id": "<id>", "changes": { "scheduled_date": "2026-11-01" } }

{ "action": "redeem", "item_id": "<id>", "changes": { "article_topic": "איך בוחרים צלם לחתונה", "keywords": "צלם חתונות", "target_link": "https://example.co.il", "writing_style": "professional" } }

נעשה רק באתר (מחזיר site_only): תשלום, קניית קרדיטים והגדרת webhook. ביטול ושינוי פרטים בשלב שגם האתר לא מאפשר מחזירים not_cancellable / not_editable עם הסבר.

שדות של כתבה

• content.type: ai — אנחנו כותבים (חובה article_topic של 3 מילים לפחות ו-writing_style); html — כתבה מוכנה כטקסט HTML (300 תווים לפחות, בלי script/iframe); docx — קובץ Word: filename ו-file_base64 (עד 8MB).
• writing_style: professional, marketing, seo_no_brand, seo_with_brand, ai_engines. ל-seo_with_brand חובה brand_name. באתר "SEO בלבד" רק seo_no_brand.
• keywords + target_link — חובה בכתבה שאנחנו כותבים (מילת מפתח אחת, בלי פסיקים). keywords_2 + target_link_2 — רק יחד, ולא באתרים שמתירים קישור אחד.
• scheduled_date (YYYY-MM-DD, לא בעבר, ראשון–חמישי) — פרסום מתוזמן. image: { "option": "auto_select" } — ברירת מחדל, אנחנו בוחרים תמונה.
• client_label — שם הלקוח שלכם (לסוכנויות), notes — הערות לכותב, team_notes — הערות לצוות BuyPost בלבד.
• shared_with ("בשיתוף עם") — חובה באתרים שמסומנים במחירון requires_shared_fields. shared_company_id (ח.פ) — רשות.
• image עם תמונות שלכם: { "option": "upload", "images": [{ "url": "https://…", "credit": "יח"צ" }] } — עד 2 תמונות, קישור או קובץ (file_base64 + filename, jpg/png/webp עד 5MB), וקרדיט צילום חובה לכל תמונה. קישור לתמונה מוכנה: { "option": "stock", "url": "https://…" }.
• pixel — פיקסל מעקב, רק באתרים שמציעים (pixel_option): { "url": "https://…" } או קובץ. פיקסל בתשלום מתווסף למחיר.
• redeem_later: true (+ quantity עד 20) — מימוש עתידי: קונים עכשיו עם website_id בלבד, ושולחים פרטים אחרי התשלום ב-redeem.
• תאריך פרסום — ראשון עד חמישי בלבד. כתבה מוכנה (html/docx) — מילת מפתח וקישור רשות, אבל תמיד יחד.
• המחירון והצעת המחיר מחזירים לכל אתר את כללי הכתיבה והפרסום שלו (writing_notes, publishing_restrictions) — הכותב שלנו פועל לפיהם. כל מחיר מסביר מאיפה הוא: מבצע / מחיר מיוחד / מחירון, וההנחה הקבועה שלכם.
• קופונים: הקופונים האישיים שלכם מוחלים אוטומטית, באותם כללים כמו בסל באתר. לקוד מסוים — coupon_code; בלי קופונים אוטומטיים — apply_coupons: false. הצעת המחיר מראה אילו קופונים חלו וכמה הם חוסכים. הקופון מנוצל רק כשההזמנה משולמת; אם נוצל בינתיים במקום אחר, הסכום מתעדכן לפני התשלום.
• בשגיאת פרטים ההודעה מפרטת מה חסר בכל כתבה, ו-details[].errors[].field אומר איזה שדה לתקן.
• אין לפרסם תכנים בנושאי הימורים, טבק/עישון, תכנים מיניים או שירותי ליווי.

סטטוסים

מצב התשלום של כל כתבה: payment_status = awaiting_payment / paid / cancelled. הזמנה שלא שולמה לא נכתבת, לא נשלחת לאתר ולא מתפרסמת. awaiting_redemption: true = נקנתה ושולמה ומחכה לפרטים שלכם (redeem). waiting_for_you: true = ממתינה לאישור שלכם (ונשלחת הודעת article.waiting_for_approval); השדה available_actions אומר אילו פעולות אפשריות עכשיו — טיוטה באתר המפרסם מאשרים באתר BuyPost. לכל כתבה יש progress: שלב, תיאור בעברית, על מי היא ממתינה ומה הצעד הבא; כתבה שפורסמה — published_url ו-published_at.

עדכונים לשרת שלכם (webhook)

מגדירים כתובת בעמוד API באזור האישי. בכל שינוי סטטוס של כתבה נשלחת בקשת POST. סוגים: article.waiting_for_approval, article.published, article.rejected, article.status_changed, order.paid (הזמנת API שולמה באתר והכתבות נכנסו לעבודה), credits.added (נוספו קרדיטים — קראו list_redeemable). כל הודעה חתומה — ודאו את החתימה:

// Node.js — אימות הודעת webhook
import crypto from 'node:crypto';

function isFromBuyPost(rawBody, headers, secret) {
  const ts = headers['x-buypost-timestamp'];
  const sig = (headers['x-buypost-signature'] || '').replace('sha256=', '');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

ענו בקוד 2xx תוך 5 שניות. הודעה שלא התקבלה נשלחת פעם נוספת; כל המשלוחים מופיעים ביומן בעמוד API.

שגיאות