תיעוד ה-API

אימות

צרו מפתח תחת מפתחות API באפליקציה (מוצג פעם אחת) ושלחו אותו כ-bearer token. מפתחות עובדים גם בענן וגם בהתקנה עצמית.

Authorization: Bearer ak_…

דרישות מהתמונה

• מסמך אחד לכל תמונה או עמוד PDF; מ-PDF נקרא רק העמוד הראשון. תעודה עם הספח שלה על A4 אחד, או צ'ק משני צדדיו בסריקה אחת, נחשבים מסמך אחד.
• פורמטים: JPEG, PNG, WebP או PDF, עד 30 MB.
• רזולוציה: 150 dpi ומעלה. מתחת ל-150 dpi איכות הקריאה אינה מובטחת.
• המסמך כולו בתוך הפריים, שטוח ומואר באופן אחיד, בלי בוהק; סריקה עדיפה על צילום.
• התשובה מדווחת על הרזולוציה המשוערת של כל מסמך ב-regions[].dpi ומוסיפה אזהרה מתחת ל-150 dpi.

נקודות קצה

ניהול מפתחות (/api/keys), הנתיבים של דף ההגדרות עצמו (/api/settings, כולל מפתח Anthropic) ומצב המאגרים (/api/registries) זמינים מהממשק בלבד: הם מקבלים את סשן הדפדפן ומחזירים 403 SESSION_REQUIRED למפתח bearer. מפתח קורא ומשנה את הגדרות בעליו דרך /api/v1/settings.

מגבלות

• בקשות: כל מפתח API מקבל 30 בקשות בדקה על פני /api/v1/* ומכסה נפרדת של 20 בדקה לחיפוש במאגרים. רצף עד המכסה עובר, ואחריו הבקשות מתחדשות אחת-אחת; מעבר לכך התשובה היא 429 RATE_LIMITED עם Retry-After בשניות. סשן דפדפן מחובר נספר לפי משתמש.
• בהתקנה עצמית קובעים אותן ב-API_RATE_LIMIT_PER_MIN וב-API_SEARCH_RATE_LIMIT_PER_MIN (0 = ללא מגבלה); המונים נשמרים בזיכרון השרת ומתאפסים כשהוא מופעל מחדש.
• העלאות: תמונה או PDF אחד לבקשה, עד 30 MB; מ-PDF נקרא רק העמוד הראשון.
• המתנה: חילוץ יכול להימשך עד 10 דקות כולל ההמתנה בתור של המנוע; תור מלא מחזיר 503 עם Retry-After.
• ניסיון: בענן חשבון חדש קורא מספר מוגבל של מסמכים על המפתח של השירות, ואז 402 TRIAL_EXHAUSTED — יש להוסיף מפתח Anthropic בהגדרות כדי להמשיך.
• חיפוש במאגרים: עד 50 שורות לכל מקור עם total אמיתי; חיפוש דורש מספר, חשבון או לפחות שתי אותיות של שם.
• תוצאות שמורות: תוצאה נשמרת רק כש-store_results פעיל; מפתח יכול לכבות אותו, ורק הממשק המחובר מפעיל אותו.

מבנה התשובה

• תאריכים בפורמט ISO בכל מקום; date_of_expiry של disability_card הוא חודש ISO (2031-03).
• validation.overall: verified / partial / unverified / mismatch. מסמכים ללא MRZ (תעודות למינציה ישנות, תעודת נכה) הם unverified במכוון.
• document_type: teudat_zehut, teudat_zehut_back, teudat_zehut_sefach, israeli_passport, foreign_passport, israeli_drivers_license, cheque, cheque_back, senior_citizen_card, disability_card, weapon_license, unreadable, not_a_document.
• foreign_passport נושא שמות בלטינית, מספר דרכון, אזרחות, מין ותאריכים — בלי שמות בעברית ובלי מספר זהות ישראלי. disability_card נושא שמות בשני הכתבים, id_number,‏ file_number ו-date_of_expiry.
• senior_citizen_card ו-weapon_license נקראים בסכימה הגנרית: מיטב המאמץ, עם אזהרה.
• not_a_document (HTTP 200, fields: {}): לא נמצא מסמך נתמך בעמוד; regions[] מפרט את מה שזוהה כ-skipped. הערך other מופיע ב-regions[] בלבד.
• כמה מסמכים בעמוד אחד: נקראים מסמך אחד ומלוויו (תעודה + ספח, חזית צ'ק + גב), והשאר skipped.
• regions[]: רשומה אחת לכל מסמך שזוהה — bbox_2d הוא [x1, y1, x2, y2] בטווח 0–1000 מרוחב העמוד ומגובהו (בקובץ PDF: מידות הרינדור של המנוע), ולצידו סוג האזור ורזולוציית המקור המשוערת (dpi).
• sefach נושא את הספח כשהעמוד כלל אותו (אחרת null), ו-usage[] את מספרי הטוקנים של כל קריאה למודל, כדי שאפשר יהיה לחשב עלות בצד הקורא.
• registries הוא null אלא אם שדה check_registries של הבקשה, או (כשהוא חסר) הגדרת בעל המפתח, הפעילו את הבדיקה. אז הוא מפרט כל מקור (id, loaded, data_date) ואת matches[]: level (alert או info), source, by (id, account או name), field ורשומת המאגר record.
• registries.checked מפרט את המפתחות שנבדקו מול מקור מורד אחד לפחות (id_number, spouse_id_number, child_id_number, drawer_id_number, guarantor_id_number, account, name_he, name_en). רשימה ריקה פירושה ששום דבר לא נבדק — לא תוצאה נקייה.
• התאמות שם הן התאמות של מילים שלמות מול רשימת הפעילים של המטה ללוחמה כלכלית בטרור — יש לאמת אותן. בדיקה שלא בוצעה מוחזרת כ־{"error": "REGISTRIES_UNAVAILABLE"} ואינה מכשילה את החילוץ.

{
  "document_type": "teudat_zehut",
  "fields": {
    "last_name_he": {
      "value": "ישראלי",
      "confidence": "high"
    },
    "first_name_he": {
      "value": "ישראל",
      "confidence": "high"
    },
    "id_number": {
      "value": "123456782",
      "confidence": "high"
    },
    "date_of_birth": {
      "value": "1990-01-31",
      "confidence": "high"
    },
    "date_of_issue": {
      "value": "2020-05-01",
      "confidence": "high"
    },
    "date_of_expiry": {
      "value": "2030-05-01",
      "confidence": "medium"
    }
  },
  "validation": {
    "mrz_present": false,
    "id_number_checksum_valid": true,
    "cross_checks": [],
    "overall": "unverified"
  },
  "warnings": [],
  "regions": [
    {
      "label": "document",
      "bbox_2d": [
        120,
        80,
        880,
        560
      ],
      "document_type": "teudat_zehut",
      "dpi": 300
    }
  ],
  "sefach": null,
  "registries": null,
  "model": "anthropic/claude-opus-5",
  "usage": [
    {
      "backend": "anthropic",
      "model": "claude-opus-5",
      "schema_name": "AnthropicPageExtraction",
      "input_tokens": 1583,
      "output_tokens": 214,
      "cache_read_tokens": 1201,
      "cache_write_tokens": 0
    }
  ],
  "meta": {
    "mode": "byok",
    "trial_remaining": null,
    "backend": "anthropic",
    "model": "claude-opus-5",
    "document_id": "0b1c…"
  }
}

נתוני עלות

עמודת העלות וסיכומי לוח הבקרה מחושבים מקומית מספירת הטוקנים של המנוע לכל קריאה, לפי מחירון Anthropic נכון ל-2026-06-24 (קלט, פלט, קריאה וכתיבה של מטמון, לפי מודל). זו הערכה בלבד: המחירים משתנים והטבלה מתעדכנת ידנית — החשבון האמיתי הוא דף השימוש בחשבון Anthropic שלכם. מסמך שעובד ב-Ollama אינו עולה דבר ומוצג בקו מפריד.

שגיאות

כל שגיאה נושאת קוד קריא למכונה; שדות נוספים תלויים בקוד.

{ "error": "TRIAL_EXHAUSTED", "detail": "…", "trial_docs": 5 }

דוגמאות

curl -s -X POST https://makor.pro/api/v1/extract \
  -H "Authorization: Bearer ak_…" \
  -F "file=@document.jpg" \
  -F "check_registries=true"

curl -s "https://makor.pro/api/v1/registries/search?id=510000003" \
  -H "Authorization: Bearer ak_…"

curl -s https://makor.pro/api/v1/settings -H "Authorization: Bearer ak_…"

curl -s -X PATCH https://makor.pro/api/v1/settings \
  -H "Authorization: Bearer ak_…" \
  -H "Content-Type: application/json" \
  -d '{"check_registries": true, "store_results": false}'