BigCommerce

כל הזמנה ששולמה בחנות BigCommerce הופכת אוטומטית לחשבונית מס קבלה (או למסמך אחר לבחירתכם).

התקנה (5 דקות)#

1. ב-BigCommerce פתחו Settings → API → Store-level API accounts → Create API account. תנו הרשאת Orders במצב Read-only. שמרו את ה-Access token.

2. במערכת: חשבוניות → חיבורים → BigCommerce. הדביקו את ה-Access token ואת ה-Store hash (החלק שבכתובת ה-API: api.bigcommerce.com/stores/<store_hash>/).

3. הגדירו אסימון אימות: מחרוזת אקראית ארוכה (לפחות 32 תווים) והדביקו אותה בשדה הסוד.

4. צרו Webhook ב-API של BigCommerce. כתובת ה-destination מוצגת במסך החיבור, וה-headers מכילים את האסימון:

   bashהעתקה

   curl -X POST "https://api.bigcommerce.com/stores/<store_hash>/v3/hooks" \
     -H "X-Auth-Token: <ACCESS_TOKEN>" -H "Content-Type: application/json" \
     -d '{
       "scope": "store/order/statusUpdated",
       "destination": "https://invoice.slk.co.il/api/billing/ecommerce/bigcommerce/<hookId>",
       "is_active": true,
       "headers": { "x-slk-token": "<האסימון שהגדרתם>" }
     }'

5. בחרו סוג מסמך ולחצו על שליחת הזמנת בדיקה. מסמך יופק להזמנות במצב Awaiting Fulfillment, Shipped או Completed שהתשלום בהן נקלט.

Developer reference#

Mode: hook, pull. Category: store. Refunds: not supported (see below).

Event. store/order/statusUpdated (and optionally store/order/created). BigCommerce sends only ids:

{ "store_id": "1025646", "producer": "stores/abc123xyz", "scope": "store/order/statusUpdated",
  "data": { "type": "order", "id": 173331 }, "hash": "3f9ea4..." }

Auth. BigCommerce does not sign webhook bodies. It does send custom headers supplied at webhook creation, so the receiver uses { kind: "token", header: "x-slk-token" }: the header value must equal the secret stored in SLK (constant-time compare). No secret configured means 401. Treat the token like a password; rotate it by re-creating the webhook.

Pull. After auth and classification the receiver calls, with X-Auth-Token: <access_token>:

• GET https://api.bigcommerce.com/stores/{store_hash}/v2/orders/{id}
• GET .../v2/orders/{id}/products?limit=250
• GET .../v2/orders/{id}/shipping_addresses

A 404 answers 200 skipped. A network failure, 5xx or 401/403 answers 502 so BigCommerce retries. Missing credentials answer 502 with חסרים פרטי חיבור.

Which orders issue. status_id in {2 Shipped, 3 Partially Shipped, 8 Awaiting Pickup, 9 Awaiting Shipment, 10 Completed, 11 Awaiting Fulfillment} and payment_status in {paid, captured}. Anything else (Incomplete, Awaiting Payment, pending, empty) is acknowledged with 200 and no row; a later statusUpdated delivery re-evaluates it. Issuing is idempotent by (bigcommerce, order id).

Mapping.

The payment row is computed from the document lines so the engine's "payments equal total" rule always holds; it can differ from BigCommerce's total_inc_tax by an agora of rounding.

Refunds. BigCommerce documents no refund webhook scope (only order scopes), so refunds are ignored. Issue a credit note manually in SLK.

Limits. Destination must be HTTPS on port 443 with a valid certificate and answer 200. Body cap 512 KB; rate limits per IP and per hook.

Test with curl (against your own hookId; the token configured as the secret):

curl -i -X POST "https://invoice.slk.co.il/api/billing/ecommerce/bigcommerce/<hookId>" \
  -H "content-type: application/json" -H "x-slk-token: <TOKEN>" \
  -d '{"store_id":"1025646","producer":"stores/abc123xyz","scope":"store/order/statusUpdated","data":{"type":"order","id":999000001},"hash":"x"}'

Order id 999000001 is the built-in sample: it is answered from a fixture with no API call, so it works before credentials are set. Expected: {"ok":true,"status":"issued","documentId":"..."}.

Sources: webhooks, orders, order products, statuses.

Troubleshooting#

• 401 — הכותרת x-slk-token חסרה או שונה מהסוד ששמרתם כאן. צרו את ה-Webhook מחדש עם הערך הנכון.
• 404 — ה-hookId בכתובת שגוי. העתיקו שוב את הכתובת ממסך החיבור.
• 502 "חסרים פרטי חיבור" — מלאו Store hash ו-Access token במסך החיבור. BigCommerce ינסה שוב לבד.
• 502 "פרטי החיבור נדחו" — ל-API account אין הרשאת Orders, או שהאסימון הוחלף.
• ההזמנה לא הפיקה מסמך — בדקו שהיא במצב Awaiting Fulfillment, Shipped או Completed ושהתשלום נקלט (payment_status הוא paid או captured). הזמנה במצב Awaiting Payment מקבלת מסמך רק כשהסטטוס משתנה.
• "blocked" — חבילת המנוי או מכסת המסמכים החודשית. "dormant" — מודול החיוב כבוי; הפעילו אותו ולחצו "הפק מסמך ידנית" ביומן ההזמנות.