תיעוד API

ה-API מאפשר לשלוח מסמכים לחתימה ממערכות אחרות (CRM, אתר, אוטומציות) ולקבל עדכונים כשהם נחתמים. בסיס הכתובות: /api/v1. כל התשובות ב-JSON.

אימות

יוצרים מפתח בהגדרות ← מפתחות API ושולחים אותו בכל בקשה. שמרו את המפתח בכספת סודות או במשתני סביבה, לא בקוד. מגבלה: 120 בקשות לדקה למפתח.

Authorization: Bearer xlx_...

שליחת PDF לחתימה

הקובץ יכול להיות PDF או מסמך Word/RTF/ODT (יומר ל-PDF; מסמך עם שינויים במעקב, מאקרו או סיסמה יידחה). שדות ממוקמים לפי שברים של העמוד (0–1, מהפינה השמאלית העליונה). recipient הוא האינדקס ברשימת הנמענים.

curl -X POST https://xlex.co.il/api/v1/envelopes \
  -H "Authorization: Bearer $XLEX_API_KEY" \
  -F file=@contract.pdf \
  -F 'data={
    "title": "הסכם שירות",
    "external_id": "crm-1234",
    "send": true,
    "recipients": [
      {"name": "דנה לוי", "email": "dana@example.com", "auth": "email_otp"},
      {"name": "יוסי כהן", "email": "yossi@example.com", "phone": "+972501234567", "auth": "sms_otp", "order": 2}
    ],
    "fields": [
      {"recipient": 0, "type": "signature", "page": 1, "x": 0.55, "y": 0.80, "w": 0.25, "h": 0.06},
      {"recipient": 1, "type": "signature", "page": 1, "x": 0.15, "y": 0.80, "w": 0.25, "h": 0.06},
      {"recipient": 1, "type": "id_number", "page": 1, "x": 0.15, "y": 0.88, "w": 0.2,  "h": 0.035}
    ]
  }'

סוגי שדות: signature, initials, name, date, text, id_number, checkbox. תפקידים: signer, approver, viewer, cc. אימות: link, email_otp, sms_otp.

שליחה מתבנית

curl -X POST https://xlex.co.il/api/v1/envelopes \
  -H "Authorization: Bearer $XLEX_API_KEY" -H "Content-Type: application/json" \
  -d '{"template_id": "tpl_...", "send": true,
       "recipients": [{"name": "דנה לוי", "email": "dana@example.com"}]}'

רשימת התבניות ותפקידיהן: GET /api/v1/templates. הנמען ה-n ממלא את התפקיד ה-n.

פעולות נוספות

GET  /api/v1/envelopes?status=completed&external_id=crm-1234
GET  /api/v1/envelopes/{id}
GET  /api/v1/envelopes/{id}/document     # PDF (החתום, כשהושלם)
POST /api/v1/envelopes/{id}/send         # שליחת טיוטה
POST /api/v1/envelopes/{id}/remind       # תזכורת לנמענים שתורם
POST /api/v1/envelopes/{id}/cancel

Webhooks

מגדירים בהגדרות ← Webhooks. כל אירוע נשלח כ-POST עם הכותרות x-xlex-event, x-xlex-delivery ו-x-xlex-signature בפורמט t=TIMESTAMP,v1=HMAC. ה-HMAC מחושב ב-SHA-256 על `${t}.${body}` עם הסוד שקיבלתם. תשובה שאינה 2xx נשלחת שוב (עד 7 ניסיונות, במרווחים הולכים וגדלים).

import crypto from "node:crypto";
function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5 min replay window
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

אירועים: envelope.sent, envelope.opened, recipient.signed, envelope.completed, envelope.rejected, envelope.cancelled, envelope.expired.

שגיאות

{ "error": { "code": "validation_error", "message": "recipients.0.email: Invalid email" } }