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 (απαιτεί το extra `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 προτού γραφτεί έστω ένα byte στον δίσκο.

Τα χρηματικά ποσά αντιμετωπίζονται ως 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. Αρχιτεκτονική προσθέτων#

Η σουίτα είναι επεκτάσιμη μέσω τεσσάρων ομάδων entry point: 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 ή το γλωσσάρι πληρωμών.