API — ERP Tamit

סקירה

ה-API מסביב https://erp.tamit.co.il/v1/. כל קריאה מחזירה JSON, כל POST תומך ב-Idempotency-Key, כל פעולה רגישה נכנסת ל-audit log אוטומטית.

הספרייה היא REST קלאסי — אין GraphQL, אין RPC. בכל endpoint יש דוגמת cURL ב-Scalar (erp.tamit.co.il/docs) שאפשר להקליק "Try it" וקיבלים תגובה חיה.

Base URL

https://erp.tamit.co.il/v1/

Content-Type

כל בקשה ותגובה הן application/json; charset=utf-8. אין צורך לציין במפורש — ברירת המחדל.

אימות

כל קריאה ל-API חייבת לכלול header Authorization: Bearer <TOKEN>. שני סוגי טוקנים:

JWT (משתמש)

נוצר מ-POST /v1/auth/login עם אימייל וסיסמה. תקף 15 דקות (access) + 30 יום (refresh). מתאים לדפדפן/אפליקציית-משתמש.

API Key (שירות)

נוצר במסך הגדרות › מפתחות API. מתחיל ב-tk_. תקף ללא תפוגה עד שמבטלים. מתאים ל-server-to-server.

POST /v1/auth/login
Content-Type: application/json

{
"email": "[email protected]",
"password": "********"
}

שגיאות

תגובת שגיאה תמיד מחזירה JSON עם code, message, ולעיתים details (מערך שגיאות שדה).

{
  "error": {
    "code": "validation_failed",
    "message": "doctype חסר",
    "details": [
      { "field": "doctype", "issue": "required" }
    ]
  }
}

קודי HTTP: 400 ולידציה, 401 אימות, 403 הרשאה, 404 לא נמצא, 409 קונפליקט (למשל מסמך כבר סגור), 422 חוסר עקביות עסקית, 429 rate limit, 500 שרת.

Rate limit

כל תגובה כוללת headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. כאשר חורגים — 429 + header Retry-After.

Idempotency

שלח כל POST עם header Idempotency-Key: <uuid>. ניסיון חוזר עם אותו key תוך 24 שעות יחזיר את התגובה המקורית בלי ליצור משאב כפול.

1. יצירת טיוטת חשבונית

טיוטה ניתנת לעריכה חופשית. כשמסיימים — קוראים ל-promote בדוגמה 2.

POST /v1/documents/drafts

curl -X POST "https://erp.tamit.co.il/v1/documents/drafts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "doctype": "invoice",
    "account_id": 42,
    "lines": [
      { "item_id": 101, "qty": 2, "price": 350.00 }
    ]
  }'

2. סגירת מסמך (promote)

הופך טיוטה למסמך סגור — מקצה מספר רץ, חותם דיגיטלית, מזיז יומן ראשי. אטומי, לא ניתן לחזרה.

POST /v1/documents/drafts/:id/promote

curl -X POST "https://erp.tamit.co.il/v1/documents/drafts/8821/promote" \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: $(uuidgen)"

תגובה: המסמך הסגור עם number (6 ספרות), issued_at, ו-signature (חתימה דיגיטלית, base64).

3. שליפת מסמך

שליפה לפי id (מספר פנימי) או לפי number (מספר רץ של 6 ספרות).

GET /v1/documents/:id

curl "https://erp.tamit.co.il/v1/documents/8821" \
-H "Authorization: Bearer $TOKEN"

GET /v1/documents/by-number?doctype=invoice&number=100118

curl -G "https://erp.tamit.co.il/v1/documents/by-number" \
  --data-urlencode "doctype=invoice" \
  --data-urlencode "number=100118" \
  -H "Authorization: Bearer $TOKEN"

4. שליחת מסמך במייל

שולח PDF + לינק תשלום (אם הוגדר) לכתובת המייל של כרטיס הלקוח, או למייל מפורש.

POST /v1/documents/:id/email

curl -X POST "https://erp.tamit.co.il/v1/documents/8821/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "include_payment_link": true,
    "note": "מצורף לפנייתך"
  }'

5. שליחה במכה

שלח עד 100 מסמכים בקריאה אחת. תגובה כוללת רשימת מצליחים ונכשלים.

POST /v1/documents/bulk-email

curl -X POST "https://erp.tamit.co.il/v1/documents/bulk-email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": [8821, 8822, 8823, 8824],
    "include_payment_link": true
  }'

6. רשימת לקוחות

חיפוש בלקוחות לפי שם/ח.פ./טלפון. תומך pagination דרך page ו-per_page.

GET /v1/accounts/search/customers?q=ערמונים

curl -G "https://erp.tamit.co.il/v1/accounts/search/customers" \
  --data-urlencode "q=ערמונים" \
  --data-urlencode "per_page=20" \
  -H "Authorization: Bearer $TOKEN"

7. יצירת פריט חדש

פריט פשוט. למוצר עם אצוות/סיריאלים — שלח tracking_mode.

POST /v1/items

curl -X POST "https://erp.tamit.co.il/v1/items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name_he": "ספר ‏‎JavaScript",
    "sku": "BK-JS-001",
    "unit_price": 95.00,
    "vat_rate": 17,
    "unit_of_measure": "unit"
  }'

8. הורדת מבנה אחיד (BKMV)

חבילה מלאה: BKMVDATA.TXT + INI.TXT + summary. מתאים להגשה לפקיד שומה.

GET /v1/uniform-export/bundle?from=2025-01-01&to=2025-12-31

curl -G "https://erp.tamit.co.il/v1/uniform-export/bundle" \
  --data-urlencode "from=2025-01-01" \
  --data-urlencode "to=2025-12-31" \
  -H "Authorization: Bearer $TOKEN" \
  -o bkmv-2025.zip

9. רשימת מסמכים

תומך filters: doctype, account_id, from, to, status.

GET /v1/documents?doctype=invoice&from=2025-01-01

curl -G "https://erp.tamit.co.il/v1/documents" \
  --data-urlencode "doctype=invoice" \
  --data-urlencode "from=2025-01-01" \
  --data-urlencode "per_page=50" \
  -H "Authorization: Bearer $TOKEN"

10. חיפוש פריט (lookup)

חיפוש חכם בפריטים — לפי שם, מק"ט, או ברקוד. אופטימלי לאוטוקומפליט במסך מסמך.

GET /v1/items/lookup?q=mac+air

curl -G "https://erp.tamit.co.il/v1/items/lookup" \
  --data-urlencode "q=mac air" \
  --data-urlencode "limit=10" \
  -H "Authorization: Bearer $TOKEN"

הצעד הבא

הדוקומנטציה המלאה — כל 165 ה-endpoints, סכימות, ודוגמאות בכל שפה — חיה ב-Scalar:

פתח Scalar Reference openapi.json (גלם) מדריך קצר במרכז העזרה

API שעובד כמו שאתה חושב.