חיבור Gumroad לחשבוניות SLK — הוראות התקנה

כל מכירה ב-Gumroad הופכת למסמך דרך ה-Ping של Gumroad.

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

Gumroad לא חותמת על ה-Ping. כדי שאף אחד אחר לא יוכל לשלוח מכירות מזויפות, כתובת ה-Ping כוללת אסימון סודי שאתם בוחרים.

בחרו אסימון ארוך ואקראי (לפחות 32 תווים) והדביקו אותו בשדה הסוד בחיבור.
ב-Gumroad: Settings → Advanced → Ping endpoint.
הדביקו את כתובת ה-Webhook שמוצגת אצלכם והוסיפו לסופה ?token= ואחריו האסימון. לדוגמה: https://<host>/api/billing/ecommerce/gumroad/<hookId>?token=<האסימון>.
לחצו Send test ping. מכירה עם test=true מופקת ומסומנת "(test)" בהערת המסמך.
בחרו סוג מסמך.

Gumroad לא שולחת החזרים כ-Ping, ולכן חשבונית זיכוי על החזר מפיקים ידנית. Ping של מכירה שכבר הוחזרה (refunded=true) מדולג.

Developer reference#

Endpoint: POST /api/billing/ecommerce/gumroad/<hookId>?token=<secret> with application/x-www-form-urlencoded (bodyFormats: ["form"]).

Auth: { kind: "token", header: "x-slk-token", query: "token" } — the secret is compared in constant time, from the token query parameter or the x-slk-token header (for a proxy that can add headers). There is no signature to verify, so keep the token secret and rotate it in the connector and in Gumroad together.

Sources: the Ping is documented under "Resource subscriptions" at https://gumroad.com/api (a client-rendered page). Independently confirmed from integration write-ups: form encoding, sale_id, email, product_name, and price in integer cents (https://dev.to/hayrullahkar/build-a-gumroad-lead-machine-in-google-sheets-ping-webhook-license-api-ai-upsell-33n9). quantity, currency, full_name, ip_country, refunded, test, sale_timestamp follow the Ping field list; verify them against a real Send test ping.

Ping field	Document
`sale_id`	`externalId`, `apiIdentifier = gumroad-<sale_id>`
`full_name`, `email`	customer (fallback `לקוח/ה`)
`product_name`, `quantity`	the line
`price` (integer cents = agorot for ILS, no scaling)	line gross and the payment row (credit card), `taxIncluded: true`
`currency`	uppercased; non-ILS needs an exchange rate (recorded as `error`)
`sale_timestamp`	issue date
`test = "true"`	mapped, labelled "(test)"
`refunded = "true"`	ignored

There is no tax breakdown in the Ping, so prices are treated as VAT-inclusive at the statutory rate. ip_country is a geolocation, not an address, and is not put on the document.

Test with curl:

bash

curl -i -X POST "https://<your-host>/api/billing/ecommerce/gumroad/<hookId>?token=<secret>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "sale_id=abc123==" --data-urlencode "[email protected]" \
  --data-urlencode "full_name=נועה בר" --data-urlencode "product_name=תבנית חשבונית" \
  --data-urlencode "price=4900" --data-urlencode "currency=ils" --data-urlencode "quantity=1" \
  --data-urlencode "refunded=false" --data-urlencode "test=true"

Troubleshooting#

401 invalid signature: האסימון בכתובת ה-Ping שונה מהסוד בחיבור, או שחסר ?token= בסוף הכתובת. שימו לב שתווים מיוחדים באסימון צריכים קידוד URL, ולכן עדיף אסימון של אותיות וספרות בלבד.
401 secret is not configured: עדיין לא הדבקתם אסימון בחיבור.
404 unknown hook: כתובת ה-Webhook לא הועתקה במלואה.
400 invalid body: ה-Ping נשלח כ-JSON או ריק. Gumroad שולחת טופס, ולכן בדקו שלא עובר proxy ששינה את הגוף.
הזמנה בסטטוס blocked או dormant: מגבלת החבילה או מודול החיוב כבוי. אפשר להפיק ידנית מיומן ההזמנות.

מה צריך

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

Developer reference#

Troubleshooting#