ממשק משיכת מסמכים — מדריך הטמעה

משיכת מסמכים ממאגר TAG-IT בממשק HTTP פשוט (JSON). גרסה בסיסית — רשימת מסמכים עם מטא-דאטה, דפדוף, סינון לפי תאריך, ומשיכת קובץ ה-PDF של מסמך.

1. אימות

כל בקשה מחייבת מפתח גישה שנמסר לכם. שולחים אותו בכותרת X-API-Key (או בפרמטר ?api_key= אם אינכם יכולים לשלוח כותרות):

curl "https://tag-it.biz/api/public/rulings/documents?scope=SCOPE_ID&size=5" \
  -H "X-API-Key: YOUR_API_KEY"

המפתח מוגבל למרחב-התוכן (scope) שהוקצה לכם. בקשה ללא מפתח או עם מפתח שגוי מחזירה 401.

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

GET /api/public/rulings/documents

פרמטר	חובה	הסבר
scope	כן	מזהה מרחב-התוכן שנמסר לכם (מספר)
page	לא	מספר עמוד, מ-1 (ברירת מחדל 1)
size	לא	מסמכים בעמוד, עד 100 (ברירת מחדל 20)
date_from / date_to	לא	טווח תאריכי מסמך, YYYY-MM-DD

התוצאות מוחזרות מהחדש לישן (לפי תאריך המסמך).

דוגמה — 20 המסמכים החדשים ביותר:

GET https://tag-it.biz/api/public/rulings/documents?scope=SCOPE_ID&page=1&size=20

תשובה:

{
  "total": 1234,
  "page": 1,
  "size": 20,
  "items": [
    {
      "id": 12345,
      "filename": "example.pdf",
      "scope_id": SCOPE_ID,
      "ai_analysis": {
        "כותרת_המסמך": "…",
        "תאריך_המסמך": "2026-05-01",
        "תקציר": "…"
      }
    }
  ]
}

שדות ai_analysis משתנים לפי סוג המסמך; לרשימת השדות המלאה למרחב שלכם: GET /api/public/rulings/schema?scope=SCOPE_ID.

3. סנכרון תקופתי (מה חדש)

למשיכה יומית של מסמכים חדשים — סינון לפי תאריך + דפדוף עד שמסיימים:

GET /api/public/rulings/documents?scope=SCOPE_ID&date_from=2026-07-01&page=1&size=100
GET /api/public/rulings/documents?scope=SCOPE_ID&date_from=2026-07-01&page=2&size=100
…עד ש-items ריק או page*size ≥ total

4. מסמך בודד — קובץ PDF מקורי

הורדת ה-PDF של מסמך לפי ה-id שלו מהרשימה:

GET /api/public/rulings/documents/{id}/file

ה-PDF המקורי (סטרימינג)

curl -o doc.pdf "https://tag-it.biz/api/public/rulings/documents/12345/file" \
  -H "X-API-Key: YOUR_API_KEY"

גם קישור זה מחייב את הכותרת X-API-Key. לקישור לחיץ ישיר בדפדפן אפשר ?api_key=…, אך אז המפתח חשוף ב-URL — עדיף שהשרת שלכם ימשוך עם הכותרת ויגיש ללקוח.

5. קודי שגיאה

401	מפתח חסר או שגוי
400	פרמטר שגוי (למשל scope שאינו מוקצה למפתח — ההודעה מפרטת את המרחבים המותרים)
404	מסמך לא קיים או מחוץ למרחב המוקצה
410	הקובץ המקורי אינו זמין עוד

6. דוגמת הטמעה מלאה (Python)

import requests

BASE = "https://tag-it.biz/api/public/rulings"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}
SCOPE = SCOPE_ID

# כל המסמכים מאז 1.7.2026
page, items = 1, []
while True:
    r = requests.get(f"{BASE}/documents", headers=HEADERS, params={
        "scope": SCOPE, "date_from": "2026-07-01",
        "page": page, "size": 100,
    })
    r.raise_for_status()
    data = r.json()
    items += data["items"]
    if page * 100 >= data["total"] or not data["items"]:
        break
    page += 1

print(len(items), "documents")

# מטא-דאטה + הורדת ה-PDF של המסמך הראשון
first = items[0]
meta = first["ai_analysis"]          # שם_התיק, בית_משפט, מספר_הליך, תאריך_המסמך …
pdf = requests.get(f"{BASE}/documents/{first['id']}/file", headers=HEADERS)
open("doc.pdf", "wb").write(pdf.content)

הערות: קצב סביר — עד מספר בקשות בשנייה. לשאלות: guy@z-g.co.il