Pain001

מדריך עזר

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

כל דגל, כל נקודת קצה וכל התנהגות של pain001 v0.0.71, מתוך הקוד שנשלח בפועל, לא מתוך שאיפות.

5 דק' קריאהנבדק לאחרונה

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

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

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

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

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

אפשרויות generate

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

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

In the next release

These features are in development for the next pain001 release. They are not in pain001 0.0.71, the version this reference documents, and their names may change before they ship.

דגל תיאור
--envelop-bah Wrap generated payment XML into an ISO 20022 Business Application Header (head.001.001.03) and BizData (head.003.001.01) envelope.
--bah-sender <BIC/ID> Sender financial institution BIC or organisation identifier for BAH <Fr>.
--bah-receiver <BIC/ID> Receiver financial institution BIC or organisation identifier for BAH <To>.
--bah-msg-id <ID> Business Message Identifier for BAH <BizMsgIdr> (defaults to generated UUID).
--xml-sign-key <FILE> PEM RSA private key for W3C XML Digital Signature (XML-DSig RSA-SHA256).
--xml-sign-cert <FILE> Optional PEM X.509 certificate to embed in XML-DSig <ds:KeyInfo>.
--xml-sign-passphrase-env <VAR> Environment variable holding passphrase to decrypt the RSA private key.

The Python API gains the matching process_files parameters: envelop_bah, xml_sign_key and xml_sign_cert.

Input normalisation gains formula injection shielding: cells starting with a formula trigger (=, +, -, @, tab, carriage return or line feed) are escaped with a leading single quote, preventing CSV injection (CWE-1236) when a file is opened in a spreadsheet.

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",
)

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

  1. אימות קלט: כל רשומה נבדקת מול ה-JSON Schema של סוג ההודעה, עם נרמול כינויי שדות ובדיקות תחביר של IBAN/BIC.
  2. ספר כללי מסלול (אופציונלי): כללי SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B או העברת זיכוי חוצת גבולות.
  3. אימות 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 או אל מילון מונחי התשלומים.