חשבוניות SLK
פתיחת חשבון

Ecwid

Ecwid — כולל חנויות Duda ו-Lightspeed eCom: הזמנה ששולמה מפיקה מסמך

חנויות אונלייןWebhook

מה צריך

אימות
אימות חתימה ייעודי לפלטפורמה
מה מדביקים
ה-Client secret של האפליקציה ב-Ecwid (לא ה-secret_ token)
פרטים נוספים
Store ID · Secret token (secret_...)
אירועים
order.createdorder.updated
החזרים
חשבונית זיכוי מפיקים ידנית
הזמנת בדיקה
כפתור אחד במסך החיבור שולח הזמנה חתומה לדוגמה
בעמוד הזה

חנויות Ecwid, כולל חנויות Duda ו-Lightspeed eCom: הזמנה ששולמה הופכת למסמך בלי עבודה ידנית.

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

  1. ב-Ecwid Control Panel: Apps → Custom apps → Create. תנו לאפליקציה הרשאת read_orders. שמרו את ה-Secret token (מתחיל ב-secret_) ואת ה-Client secret.
  2. במערכת: חשבוניות → חיבורים → Ecwid. הדביקו את ה-Store ID ואת ה-Secret token. את ה-Client secret הדביקו בשדה הסוד. שימו לב: זה לא אותו ערך כמו ה-Secret token.
  3. בהגדרות האפליקציה קבעו Webhook URL לכתובת שמוצגת במסך החיבור. Ecwid שולח order.created ו-order.updated לכל שינוי בהזמנה.
  4. בחרו סוג מסמך ולחצו על שליחת הזמנת בדיקה. מסמך יופק כשסטטוס התשלום עובר ל-PAID.

חנות Duda או Lightspeed eCom (Ecwid) שרצה על אותו מנוע מוגדרת באותה דרך.

Developer reference#

Mode: hook, pull. Category: store. Refunds: not mapped.

Event.

json
{ "eventId": "80aece08-40e8-4145-8764-6c2f0d386781", "eventCreated": 1789897200, "storeId": 1003,
  "entityId": 103, "eventType": "order.updated",
  "data": { "oldPaymentStatus": "AWAITING_PAYMENT", "newPaymentStatus": "PAID" } }

Auth. X-Ecwid-Webhook-Signature = base64(HMAC-SHA256("<eventCreated>.<eventId>", client_secret)). Implemented as { kind: "custom" }: the body is parsed inside verify (it receives the raw body), constant-time compare. The secret is the app's Client secret, not the secret_... access token.

Caveat: the signed string does not include the body. A valid signature proves the delivery came from Ecwid, not that the body is unmodified. Defence in depth: the body is used only for the order number, the order itself is always pulled from Ecwid with the store token, and a delivery whose storeId differs from the configured Store ID is dropped without a fetch.

Classify. order.created / order.updated with data.newPaymentStatus === "PAID" only. Everything else answers 200 event ignored.

Pull. GET https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber} with Authorization: Bearer <secret_token>. The order must itself say paymentStatus: "PAID". 404 answers 200 skipped; network error, 5xx, 401/403 answer 502 (Ecwid retries for 24 hours); missing credentials answer 502 חסרים פרטי חיבור.

Mapping.

Ecwid fieldDocument field
orderNumberexternalId; apiIdentifier = ecwid-<orderNumber>
items[].nameline name
items[].quantityline quantityMilli
items[].priceline unitPriceAgorot; if pricesIncludeTax is false the prices are grossed up by tax / base so the document is tax-included
taxvatBp (derived from tax over the net amount, snapped to 1800 within 80bp)
shippingOption.shippingRate + handlingFee.valueline "משלוח"
discountdocument discountValue (fixed)
emailcustomerEmail
billingPerson.name (or companyName)customerName
billingPerson.street/city/postalCode/countryCodecustomerAddress
paymentMethodpayment type (cash / transfer / PayPal / check, else card)
createDateissueDate (date part)
sum of lines minus discountsingle payment row

Refunds. The webhook carries statuses (REFUNDED, PARTIALLY_REFUNDED), not an amount, so no credit note is created. Issue one manually.

Limits. Ecwid needs HTTP 200/201/202/204/209 within 10 seconds. Body cap 512 KB.

Test with curl (sample order 999000001 is answered from a fixture, no credentials needed):

bash
SECRET='<client_secret>'; ID='80aece08-40e8-4145-8764-6c2f0d386781'; CREATED=1789897200
SIG=$(printf '%s.%s' "$CREATED" "$ID" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64)
curl -i -X POST "https://invoice.slk.co.il/api/billing/ecommerce/ecwid/<hookId>" \
  -H "content-type: application/json" -H "X-Ecwid-Webhook-Signature: $SIG" \
  -d '{"eventId":"'$ID'","eventCreated":'$CREATED',"storeId":1003,"entityId":999000001,"eventType":"order.updated","data":{"oldPaymentStatus":"AWAITING_PAYMENT","newPaymentStatus":"PAID"}}'

Sources: webhooks, processing webhooks, get order.

Troubleshooting#

  • 401 — הסוד שגוי. צריך להדביק את ה-Client secret של האפליקציה, לא את ה-Secret token שמתחיל ב-secret_.
  • 404 — ה-hookId בכתובת שגוי. העתיקו שוב ממסך החיבור.
  • 502 "חסרים פרטי חיבור" — מלאו Store ID ו-Secret token. Ecwid ינסה שוב עד 24 שעות.
  • 502 "פרטי החיבור נדחו" — לאפליקציה אין הרשאת read_orders, או שה-Secret token שגוי.
  • אין מסמך להזמנה — המסמך נוצר רק כשהתשלום עובר ל-PAID. הזמנה שממתינה לתשלום תופק בעדכון הבא.
  • "blocked" — מכסת המסמכים החודשית או חבילת המנוי. "dormant" — מודול החיוב כבוי.
  • Ecwid חסם את ה-Webhook — אחרי שבועיים ללא מענה Ecwid חוסם משלוחים. אחרי שהכתובת חזרה לעבוד, שמרו מחדש את ה-Webhook URL באפליקציה.

פותחים חשבון בדקה, ואז מדביקים את הכתובת.

חברו את Ecwid
חיבור Ecwid לחשבוניות SLK — הוראות התקנה | פורטל המפתחים