Pain001 — מדריך טכני: CLI, Python API ו-REST

מדריך זה מתעד את ממשק שורת הפקודה, את ה-Python API, את מיקרו-שירות ה-REST ואת צינור האימות של pain001 v0.0.57. כל דגל, כל נקודת קצה וכל התנהגות המפורטים כאן נלקחו מהקוד שנשלח בפועל, ולא משאיפות.

Pain001 תומכת ב11 הגדרות הודעה של ISO 20022: מ-pain.001.001.03 ועד pain.001.001.12 (Customer Credit Transfer Initiation, עשר גרסאות) ו-pain.008.001.02 (Customer Direct Debit Initiation).

1. ממשק שורת הפקודה#

קובץ ההרצה pain001 מארגן את הפונקציונליות שלו בתת-פקודות. הרצה עם דגלי יצירה בלבד מפעילה את generate באופן משתמע, כך שאוטומציות קיימות ממשיכות לפעול.

תת-פקודה	מטרה
`generate`	המרת קובץ נתונים ל-XML של ISO 20022 מאומת מול סכימה (פקודת ברירת המחדל).
`validate`	אימות נתוני הקלט ללא כתיבת XML.
`versions [--json]`	הצגת כל 11 הגדרות ההודעה הנתמכות.
`inspect [--json]`	הצגת השדות הנדרשים והאופציונליים עבור סוג הודעה.
`init [-o DIR]`	יצירת תבנית CSV התחלתית עבור סוג הודעה.
`serve [--host] [--port] [--reload]`	הפעלת מיקרו-שירות ה-REST מבוסס FastAPI (מחייב את התוספת `api`).
`mcp`	הפעלת שרת Model Context Protocol המובנה (5 כלים; השרת המלא בעל 17 הכלים נשלח כ-`pain001-mcp`).
`plugins list / show / disable`	בדיקה וניהול של תוספי טעינה, אימות, מסלולים וכתיבה שאותרו.

אפשרויות `generate`

דגל	תיאור
`-t, --xml-message-type`	הגדרת הודעה, לדוגמה `pain.001.001.09`.
`-d, --data`	נתוני קלט: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, או קובצי `.gpg` / `.asc` מוצפני PGP.
`-o, --output-dir`	התיקייה שאליה נכתב ה-XML שנוצר.
`-m, --template` / `-s, --schema`	דריסת תבנית ה-Jinja2 או סכימת ה-XSD המצורפות.
`-c, --config`	טעינת ברירות מחדל מפרופיל תצורה (`--profile`, `--show-config`).
`--dry-run` (כינוי חלופי: `--validate-only`)	אימות הקלט מול ה-JSON Schema, מול ה-XSD ומול ספר כללי המסלול, ללא כתיבת פלט.
`--scheme`	אכיפת ספר כללי מסלול: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b` או `xborder-ct`.
`--explain --scheme-format {text,json}`	דיווח על כל כלל מסלול שעבר או נכשל, בפורמט קריא לאדם או למכונה.
`--streaming` / `--chunk-size`	עיבוד במקטעים עם צריכת זיכרון חסומה עבור אצוות גדולות (ברירת מחדל 1,000 עסקאות למקטע; כל מקטע הופך לקובץ XML נפרד עם `NbOfTxs` ו-`CtrlSum` מחושבים מחדש).
`--emit-metrics`	פליטת מדדי ריצה קריאים למכונה עבור צינורות תצפיתיות.

קודי היציאה ידידותיים ל-CI: 0 הצלחה, 1 כשל אימות, 2 שגיאת שימוש.

2. Python API#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

כל מסמך שנוצר עובר שלוש שכבות לפני שהוא נכתב:

אימות קלט — כל רשומה נבדקת מול ה-JSON Schema של סוג ההודעה, עם נרמול כינויי שדות ובדיקות תחביר של IBAN/BIC.
ספר כללי מסלול (אופציונלי) — כללי SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B או העברת זיכוי חוצת גבולות.
אימות XSD — ה-XML שנוצר מאומת מול סכימת ISO 20022 הרשמית באמצעות xmlschema לפני שנכתב ולו בית אחד לדיסק.

סכומים כספיים מטופלים כ-decimal.Decimal במהלך יצירת ה-XML ואימות המסלול — לעולם לא כמספרי נקודה צפה לפי IEEE 754 — וסכומי הבקרה NbOfTxs / CtrlSum מחושבים מחדש מתוך הרשומות המאומתות במקום להסתמך על הקלט.

מעבר ליצירת pain.001, ספריית הליבה כוללת גם מנתח ומחולל דוחות סטטוס pain.002 (כדי שתוכלו לקרוא את תשובת האישור או הדחייה של הבנק) וכן מנתח ומחולל דפי חשבון camt.053 לצורכי התאמות בסוף היום, ולצדם VersionMapper הממיר רשומות בין גרסאות הודעה.

3. מיקרו-שירות REST#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

כל נקודות הקצה ממוקמות תחת /api/v1 (עם כינוי /api ללא גרסה):

מתודה ונתיב	מטרה
`GET /api/v1/health`	בדיקת חיות.
`POST /api/v1/validate`	אימות רשומות; מחזיר שגיאות ברמת השדה.
`POST /api/v1/generate`	יצירת XML סינכרונית.
`POST /api/v1/generate/async`	הכנסת אצווה גדולה לתור ליצירה ברקע.
`GET /api/v1/status/{job_id}`	תשאול משימה אסינכרונית.
`GET /api/v1/download/{job_id}`	הורדת ה-XML המוגמר.
`DELETE /api/v1/jobs/{job_id}`	ניקוי משימה שהושלמה.
`GET /metrics`	מדדי Prometheus.

תיעוד אינטראקטיבי מוגש בכתובות /api/docs (Swagger UI), /api/redoc ו-/api/reference (Scalar), ומסמך ה-OpenAPI זמין בכתובת /openapi.json.

4. נרמול קלט#

Pain001 מתאימה ייצוא נתונים מהעולם האמיתי לרשומות תקפות עוד לפני האימות:

כינויי שדות — שמות עמודות נפוצים ממערכות ERP ממופים לשדות קנוניים (לדוגמה amount → payment_amount).
נרמול IBAN / BIC — הסרת רווחים, איחוד אותיות רישיות ולאחר מכן בדיקה (mod-97 לפי ISO 13616 עבור IBAN, מבנה לפי ISO 9362 עבור BIC).
תאריכים — ניתוח לפי ISO 8601 בתבנית YYYY-MM-DD עבור תאריכי הביצוע.
סכומים — מנותבים דרך decimal.Decimal; סכומים פגומים נכשלים באימות במקום להתעגל בשקט.
ערכת תווים — פונקציות עזר לתעתיק מצמצמות את התוכן לערכת התווים הלטינית של ISO 20022 המתקבלת ב-SWIFT וב-SEPA.

5. ארכיטקטורת תוספים#

חבילת הכלים ניתנת להרחבה באמצעות ארבע קבוצות נקודות כניסה: pain001.loaders, pain001.validators, pain001.schemes ו-pain001.writers. pain001-loader-xlsx נרשם דרך המנגנון הזה ומאותר אוטומטית עם ההתקנה; pain001-loader-mt101 הוא ספריית ניתוח עצמאית הנצרכת ישירות (וגם על ידי הכלי convert_mt101 של שרת ה-MCP). מתג ניתוק — PAIN001_DISABLE_PLUGINS=1 — משבית לחלוטין איתור תוספים של צד שלישי בסביבות נעולות.

6. שערי איכות#

ספריית הליבה מפותחת מול שערים מחמירים וניתנים לאימות: 100% כיסוי שורות וגם הסתעפויות הנאכף ב-CI (--cov-fail-under=100), טיפוסיות mypy מחמירה, 100% כיסוי docstring ובדיקות אבטחה סטטיות (Bandit, pip-audit). עבור כל בניית גרסה נוצר SBOM בפורמט CycloneDX.

המשיכו אל מדריך ההתקנה, אל שרת ה-MCP לסוכני AI או אל מילון מונחי התשלומים.