הפקת מסמכים מכל מערכת

ה-API של חשבונית בצ'ט מאפשר לאתר, לחנות, ל-CRM או לכל מערכת אחרת להפיק בשם העסק מסמכים חשבונאיים תקינים — הצעות מחיר, חשבוניות, קבלות וזיכויים — עם מספור רציף, PDF חתום דיגיטלית, מספר הקצאה מרשות המסים כשצריך, ושליחה ללקוח לפי הגדרות העסק.

01התחלה מהירה

1. יוצרים מפתח באפליקציה: הגדרות ← חיבורים ← חיבור API ← "צור מפתח". המפתח מוצג פעם אחת — שומרים אותו בצד השרת בלבד.
2. בודקים את החיבור ורואים מה מותר לעסק:

   curl https://api.chat-invoice.co.il/v1/me -H "Authorization: Bearer $CHATINVOICE_API_KEY"

3. מפיקים הצעת מחיר ללקוח חדש:

curl -X POST https://api.chat-invoice.co.il/v1/documents \
  -H "Authorization: Bearer $CHATINVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-8812" \
  -d '{"type":"quote","customer":{"name":"ישראל ישראלי בע\"מ","tax_id":"515123456","email":"billing@example.co.il","phone":"0501234567"},"items":[{"description":"הובלת דירה 4 חדרים","quantity":1,"unit_price":2500},{"description":"אריזה","quantity":10,"unit_price":45}],"title":"הצעה למעבר דירה","notes":"תוקף ההצעה 14 יום","external_ref":"crm-8812"}'

const res = await fetch("https://api.chat-invoice.co.il/v1/documents", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.CHATINVOICE_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "crm-8812",
  },
  body: JSON.stringify({
    "type": "quote",
    "customer": {
      "name": "ישראל ישראלי בע\"מ",
      "tax_id": "515123456",
      "email": "billing@example.co.il",
      "phone": "0501234567"
    },
    "items": [
      {
        "description": "הובלת דירה 4 חדרים",
        "quantity": 1,
        "unit_price": 2500
      },
      {
        "description": "אריזה",
        "quantity": 10,
        "unit_price": 45
      }
    ],
    "title": "הצעה למעבר דירה",
    "notes": "תוקף ההצעה 14 יום",
    "external_ref": "crm-8812"
  }),
});
const doc = await res.json();
if (!res.ok) throw new Error(doc.error.code + ": " + doc.error.message);
console.log(doc.number, doc.view_url, doc.pdf_url);

import os, requests

r = requests.post(
    "https://api.chat-invoice.co.il/v1/documents",
    headers={
        "Authorization": f"Bearer {os.environ['CHATINVOICE_API_KEY']}",
        "Idempotency-Key": "crm-8812",
    },
    json={
        "type": "quote",
        "customer": {
            "name": "ישראל ישראלי בע\"מ",
            "tax_id": "515123456",
            "email": "billing@example.co.il",
            "phone": "0501234567"
        },
        "items": [
            {
                "description": "הובלת דירה 4 חדרים",
                "quantity": 1,
                "unit_price": 2500
            },
            {
                "description": "אריזה",
                "quantity": 10,
                "unit_price": 45
            }
        ],
        "title": "הצעה למעבר דירה",
        "notes": "תוקף ההצעה 14 יום",
        "external_ref": "crm-8812"
    },
    timeout=90,
)
doc = r.json()
if not r.ok:
    raise RuntimeError(f"{doc['error']['code']}: {doc['error']['message']}")
print(doc["number"], doc["view_url"], doc["pdf_url"])

$ch = curl_init("https://api.chat-invoice.co.il/v1/documents");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("CHATINVOICE_API_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: crm-8812",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "type" => "quote",
    "customer" => [
      "name" => "ישראל ישראלי בע\"מ",
      "tax_id" => "515123456",
      "email" => "billing@example.co.il",
      "phone" => "0501234567"
    ],
    "items" => [
      [
        "description" => "הובלת דירה 4 חדרים",
        "quantity" => 1,
        "unit_price" => 2500
      ],
      [
        "description" => "אריזה",
        "quantity" => 10,
        "unit_price" => 45
      ]
    ],
    "title" => "הצעה למעבר דירה",
    "notes" => "תוקף ההצעה 14 יום",
    "external_ref" => "crm-8812"
  ], JSON_UNESCAPED_UNICODE),
]);
$doc = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) { throw new Exception($doc["error"]["code"]); }
echo $doc["number"], " ", $doc["view_url"];

התשובה (201) מכילה את מספר המסמך, הסכומים כפי שחושבו, קישור צפייה וקישור PDF:

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "public_id": "RFayPUSCNKnD",
  "type": "quote",
  "number": 1328,
  "status": "open",
  "date": "2026-09-07",
  "due_date": null,
  "external_ref": "crm-8812",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60",
    "name": "ישראל ישראלי בע\"מ",
    "tax_id": "515123456"
  },
  "totals": {
    "subtotal": 2500,
    "discount": 0,
    "vat": 450,
    "vat_rate": 18,
    "total": 2950,
    "paid": 0,
    "currency": "ILS"
  },
  "allocation_number": null,
  "allocation": {
    "status": "not_required",
    "number": null,
    "reason": null
  },
  "delivery": {
    "status": "disabled",
    "channel": null,
    "scheduled_for": null
  },
  "view_url": "https://doc.chat-invoice.co.il/view/RFayPUSCNKnD",
  "pdf_url": "https://doc.chat-invoice.co.il/pdf/RFayPUSCNKnD",
  "based_on": null,
  "cancelled_at": null,
  "created_at": "2026-09-07T10:21:44.120Z"
}

ואותו דבר לחשבונית מס/קבלה על תשלום שהתקבל — הפעם ללקוח קיים לפי customer.id, עם אימות סכום:

{
  "type": "tax_invoice_receipt",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60"
  },
  "items": [
    {
      "description": "שירות חודשי — ספטמבר",
      "quantity": 1,
      "unit_price": 590
    }
  ],
  "payments": [
    {
      "method": "bank_transfer",
      "amount": 590,
      "reference": "778812"
    }
  ],
  "expected_total": 590,
  "external_ref": "order-10021"
}

02אימות ואבטחה

• כל בקשה נושאת Authorization: Bearer ci_live_…. המפתח מזהה את העסק — כל המסמכים והלקוחות שייכים לו בלבד.
• המפתח הוא סוד: לעולם לא בקוד צד-לקוח, באפליקציה או ב-git. אין CORS — ה-API מיועד לשרת בלבד.
• ביטול מפתח — מיידי, מאותו מסך באפליקציה. אפשר להחזיק כמה מפתחות (למשל אחד לכל מערכת).
• Idempotency-Key חובה בכל הפקה. זה מה שמונע חשבונית כפולה כשיש timeout ואתם מנסים שוב: אותו מפתח + אותו גוף → מקבלים את אותו המסמך (עם הכותרת Idempotent-Replayed: true). מפתח שכבר שימש עם גוף אחר → 409.
• כל תשובה מחזירה X-Request-Id — צרפו אותו לפנייה לתמיכה.

03מה מותר לעסק שלך

סוג העוסק קובע אילו מסמכים חוקי להפיק. עוסק פטור (וגם עמותה/מלכ"ר) לא מפיק חשבונית מס — הוא מפיק קבלה על תשלום וחשבונית עסקה כדרישת-תשלום. הבקשה תיענה ב-422 legal_type_forbidden ושום מספר לא יישרף. GET /v1/document-types מחזיר מראש רק מה שמותר לעסק.

• תאריך (date) — ברירת מחדל היום. לא עתידי, ולא מוקדם מהמסמך האחרון מאותו סוג (רצף מספור↔תאריך לפי הוראות ניהול ספרים). שגיאה: 422 date_before_last_document עם התאריך המותר.
• לקוח — או customer.id של לקוח קיים (מ-GET /v1/customers), או customer.name + פרטים. שם שכבר קיים בכרטסת נצמד לכרטיס הקיים; פרטים חדשים ממלאים רק שדות ריקים ולא דורסים. ח.פ שרשום על לקוח אחר בשם אחר → 409 customer_identity_conflict כדי לא לשייך מסמך ללקוח הלא-נכון.
• מסמך מקור (based_on) — קבלה על חשבונית מס סוגרת אותה אוטומטית; חשבונית זיכוי חייבת מסמך מקור.

04סכומים, מע"מ ותשלומים

• שולחים פריטים (description, quantity, unit_price) ואופציונלית הנחה למסמך. אנחנו מחשבים סה"כ, מע"מ ועיגול — באותו מנוע של הצ'אט והאפליקציה.
• prices_include_vat אומר אם המחיר ששלחתם כולל מע"מ. ברירת המחדל היא הגדרת העסק (רואים אותה ב-/v1/me). שיעור המע"מ מגיע מהגדרות העסק (עוסק פטור ואילת — 0).
• expected_total — רשת ביטחון: אם הסה"כ שלנו שונה מהצפוי בלמעלה מאגורה, המסמך לא מופק (422 total_mismatch עם הסכום שחישבנו).
• תשלומים — חובה בקבלה / חשבונית מס-קבלה / קבלה על תרומה, ואסורים בשאר. סכום התשלומים חייב להיות שווה לסה"כ.

05מספר הקצאה (חשבונית ישראל)

חשבונית מס / חשבונית מס-קבלה / חשבונית זיכוי מעל 5,000 ₪ לפני מע"מ דורשת מספר הקצאה מרשות המסים כדי שהלקוח יוכל לקזז מע"מ. אם העסק מחובר לרשות המסים (tax_authority_connected ב-/v1/me) — אנחנו מבקשים את המספר אוטומטית אחרי ההפקה ומטביעים אותו ב-PDF.

• לשם כך צריך את ח.פ / ע.מ של הלקוח — שלחו customer.tax_id (או שהוא כבר בכרטיס הלקוח).
• המסמך תמיד מופק. אם חסר ח.פ, העסק לא מחובר, או שהרשות לא ענתה — המסמך יוצא בלי מספר הקצאה, והתשובה אומרת בדיוק למה ב-allocation.status: issued · not_required · skipped_customer_tax_id_missing · skipped_business_tax_id_missing · failed.
• השלמה בדיעבד — בעל העסק כותב בצ'אט "תשלים מספר הקצאה לחשבונית 500012".

06שליחה ללקוח

אם לעסק מופעלת שליחה אוטומטית (הגדרות ← אוטומציה), כל מסמך שמופק דרך ה-API נשלח ללקוח בערוץ שנבחר — וואטסאפ, מייל או שניהם — בדיוק כמו מסמך מהצ'אט, כולל שעות שקט (מסמך שמופק בלילה יוצא בבוקר). התשובה מדווחת ב-delivery.status: queued · deferred_quiet_hours (+scheduled_for) · no_recipient (אין טלפון/מייל בכרטיס) · disabled · suppressed · send_failed.

רוצים לשלוח בעצמכם? שלחו "send": false והשתמשו ב-view_url (עמוד צפייה) או pdf_url (קובץ). עותק לרו"ח נשלח לפי הגדרות העסק בלי קשר.

07ביטול וזיכוי

מסמך שהופק לא נמחק — המספר נשאר בפנקס.

• הצעת מחיר, הזמנה, תעודת משלוח, החזרה, חשבונית עסקה — POST /v1/documents/{id}/cancel מסמן "מבוטל".
• חשבונית מס, חשבונית מס-קבלה, קבלה — אין ביטול. מפיקים חשבונית זיכוי (type: credit_note, based_on: מזהה החשבונית) עם אותם פריטים. ניסיון לבטל מחזיר 422 use_credit_note עם דוגמה מוכנה.

{
  "type": "credit_note",
  "based_on": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "customer": {
    "id": "3f9c2a1e-6b7d-4c8e-9f0a-1b2c3d4e5f60"
  },
  "items": [
    {
      "description": "זיכוי — שירות חודשי ספטמבר",
      "quantity": 1,
      "unit_price": 590
    }
  ]
}

08מגבלות, מנוי וגרסאות

• 60 בקשות לדקה ו-300 מסמכים ביום לכל מפתח (כותרות RateLimit-*; 429 עם Retry-After). צריך יותר? דברו איתנו.
• ה-API זמין לעסקים עם מנוי פעיל. כשהמנוי לא פעיל מתקבל 402 subscription_required עם קישור לתשלום ב-details.payment_url.
• עסק שמפיק דרך תוכנה חיצונית (iCount, Green Invoice ועוד) — ה-API לא זמין (403).
• /v1 יציב. שדות חדשים בתשובות אינם שינוי שובר — התעלמו משדות לא מוכרים. שינוי שובר יקבל /v2. יומן שינויים.

09שגיאות

כל שגיאה חוזרת באותו מבנה, עם קוד יציב, הסבר, המלצה מה לעשות, ודגל retryable:

{
  "error": {
    "code": "legal_type_forbidden",
    "message": "This business type may not issue the requested document type.",
    "message_he": "סוג העוסק אינו רשאי להפיק מסמך מסוג זה.",
    "hint": "GET /v1/document-types lists what this business may issue. An exempt dealer (osek patur) issues receipts / proforma invoices instead of tax invoices.",
    "retryable": false,
    "doc_url": "https://api.chat-invoice.co.il/docs/errors#legal_type_forbidden"
  },
  "request_id": "5f1c9b2e-0d4a-4b1e-9d1c-2f7a1b3c4d5e"
}

הקטלוג המלא: /docs/errors · גם כ-JSON: GET /v1/errors.