Πίνακας περιεχομένων

  1. Εισαγωγή

  2. Τι είναι το Stancer και γιατί να το ενσωματώσω;

  3. Στόχοι της Ενότητας

  4. Κατανόηση της αρχιτεκτονικής της μονάδας Dolibarr

  5. Ρύθμιση περιβάλλοντος ανάπτυξης

  6. Έλεγχος ταυτότητας και πρόσβαση στο Stancer API

  7. Κατασκευή της Μονάδας Stancer

    • Δομή αρχείου

    • Αρχεία Βασικών Ρυθμίσεων

    • Ενσωμάτωση αγκίστρου πληρωμής

  8. Χειρισμός Συναλλαγών: Πληρωμές και Webhooks

  9. Δοκιμή και εντοπισμός σφαλμάτων ενσωμάτωσης Stancer

  10. Ζητήματα διεπαφής χρήστη και εμπειρίας χρήστη

  11. Προκλήσεις και διδάγματα ολοκλήρωσης στον πραγματικό κόσμο

  12. Ασφάλεια και συμμόρφωση σε ενότητες πληρωμών

  13. Συμβουλές για ανάπτυξη και συντήρηση

  14. Συνεισφορά Κοινότητας και Μελλοντικές Βελτιώσεις

  15. Συμπέρασμα

1. Εισαγωγή

Το Dolibarr ERP/CRM είναι μια ισχυρή πλατφόρμα ανοιχτού κώδικα που χρησιμοποιείται από επιχειρήσεις για τη διαχείριση πωλήσεων, λογιστικής, έργων και άλλων. Καθώς οι ηλεκτρονικές συναλλαγές γίνονται ο κανόνας, η ενσωμάτωση αξιόπιστων και σύγχρονων πυλών πληρωμών είναι απαραίτητη. Μια τέτοια πύλη είναι Στάνσερ, μια υπηρεσία πληρωμών σχεδιασμένη για απλότητα, διαφάνεια και φιλικά προς τους προγραμματιστές API. Αυτό το άρθρο περιγράφει λεπτομερώς την πορεία ανάπτυξης και ενσωμάτωσης μιας μονάδας πληρωμών Stancer στο Dolibarr, συμπεριλαμβανομένων των επιλογών σχεδιασμού, των τεχνικών εμποδίων και των βέλτιστων πρακτικών.

2. Τι είναι το Stancer και γιατί να το ενσωματώσω;

Στάνσερ είναι μια γαλλική εταιρεία επεξεργασίας πληρωμών που προσφέρει ανταγωνιστικές χρεώσεις συναλλαγών, ένα απλό API και υπηρεσίες όπως πληρωμές με κάρτα, άμεσες χρεώσεις SEPA και επαναλαμβανόμενες χρεώσεις. Οι βασικοί λόγοι για την επιλογή της Stancer περιλαμβάνουν:

  • Διαφανής τιμολόγηση

  • API RESTful με επίκεντρο τον προγραμματιστή

  • Συμμόρφωση με τους ευρωπαϊκούς κανονισμούς (PSD2, 3DSecure)

  • Υποστήριξη τόσο για μεμονωμένες όσο και για επαναλαμβανόμενες πληρωμές

Η ενσωμάτωση του Stancer στο Dolibarr ανοίγει την πόρτα στους χρήστες να διαχειρίζονται πληρωμές απευθείας από το σύστημα ERP τους, να αυτοματοποιούν την χρέωση των πελατών και να μειώνουν τη χειροκίνητη επεξεργασία.

3. Στόχοι της Ενότητας

Οι κύριοι στόχοι κατά τον σχεδιασμό της μονάδας Stancer για το Dolibarr ήταν:

  • Απρόσκοπτη ενσωμάτωση στις ροές εργασίας τιμολογίων και πληρωμών της Dolibarr

  • Επεξεργασία συναλλαγών σε πραγματικό χρόνο και ενημερώσεις κατάστασης

  • Υποστήριξη για εφάπαξ και επαναλαμβανόμενες πληρωμές

  • Ασφαλής διαχείριση ευαίσθητων δεδομένων πληρωμών

  • Εύκολη εγκατάσταση και διαμόρφωση για μη τεχνικούς χρήστες

4. Κατανόηση της αρχιτεκτονικής της ενότητας Dolibarr

Πριν από την ανάπτυξη οποιασδήποτε ενότητας, η κατανόηση της δομής των ενοτήτων του Dolibarr είναι ζωτικής σημασίας. Τα βασικά στοιχεία περιλαμβάνουν:

  • Αρχεία περιγραφής ενότητας (modStancer.class.php)

  • άγκιστραΧρησιμοποιείται για την αλληλεπίδραση με συμβάντα Dolibarr, όπως η επικύρωση τιμολογίων, η δημιουργία από τρίτους ή η υποβολή πληρωμής.

  • ωθήσεις: Ακροατές συμβάντων (π.χ., trigger.inc.php) που αντιδρούν σε αλλαγές σε επίπεδο βάσης δεδομένων.

  • Μενού και δικαιώματα: Ορίζεται στον περιγραφέα της ενότητας.

Το Dolibarr επιτρέπει στις ενότητες να επεκτείνουν υπάρχουσες οντότητες (όπως τιμολόγια ή τρίτα μέρη), να προσθέτουν καρτέλες ή να παρακάμπτουν βασικές συμπεριφορές.

5. Ρύθμιση Περιβάλλοντος Ανάπτυξης

Για να κατασκευάσουμε την ενότητα Stancer, χρησιμοποιήσαμε:

  • Το Dolibarr v15+ είναι εγκατεστημένο σε τοπικό περιβάλλον ανάπτυξης (Apache + MySQL)

  • Σύνθεση για διαχείριση εξαρτήσεων (για HTTP clients)

  • Git για έλεγχο έκδοσης

  • Ένας δοκιμαστικός λογαριασμός Stancer για πρόσβαση στον πίνακα ελέγχου προγραμματιστή και στα κλειδιά API

Βεβαιωθείτε MAIN_MODULE_STANCER δηλώνεται στο αρχείο conf του Dolibarr κατά την ανάπτυξη.

6. Έλεγχος ταυτότητας και πρόσβαση στο Stancer API

Το Stancer χρησιμοποιεί βασικό έλεγχο ταυτότητας HTTP:

Authorization: Basic base64(YourPrivateKey:)

Χρησιμοποιήσαμε το Guzzle (ένα πρόγραμμα-πελάτης HTTP PHP) για να υποβάλουμε αιτήματα με έλεγχο ταυτότητας. Όλες οι κλήσεις API—είτε πρόκειται για δημιουργία πληρωμής, ανάκτηση συναλλαγής είτε για ρύθμιση επαναλαμβανόμενης χρέωσης—απαιτούν τη χρήση ενός ασφαλούς ιδιωτικού κλειδιού που εκδίδεται από την Stancer.

Για να αποθηκεύσετε και να χρησιμοποιήσετε με ασφάλεια αυτό το κλειδί:

  • Χρησιμοποιήστε το Dolibarr's conf αντικείμενο ($conf->global->STANCER_API_KEY)

  • Αποκρύψτε την τιμή στις διεπαφές διαμόρφωσης

  • Επικυρώστε το κατά τη διάρκεια της ρύθμισης της ενότητας

7. Κατασκευή της Μονάδας Stancer

Δομή αρχείου

/custom/stancer/
├── class/
│   └── api_stancer.class.php
├── core/
│   └── modules/
│       └── modStancer.class.php
├── hook/
│   └── interface_99_modstancer_common.php
├── stancer.php
└── README.md

Αρχεία Βασικών Ρυθμίσεων

  • modStancer.class.phpΟρίζει τις ιδιότητες της ενότητας και τη συμπεριφορά εγκατάστασης

  • api_stancer.class.php: Κλάση πυρήνα για τη διαχείριση αιτημάτων API

  • hook/interface_99_modstancer_common.php: Γαντζώνει σε μορφές Dolibarr

Ενσωμάτωση αγκίστρου πληρωμής

Χρησιμοποιώντας addMoreActionsButtons() Εισάγουμε ένα κουμπί «Πληρωμή με Stancer» απευθείας στις σελίδες προβολής τιμολογίων. Κάνοντας κλικ σε αυτό το κουμπί ενεργοποιείται μια ανακατεύθυνση σε μια ασφαλή φόρμα πληρωμής που φιλοξενείται στο Dolibarr ή μέσω ενσωμάτωσης iframe.

8. Χειρισμός Συναλλαγών: Πληρωμές και Webhooks

Πληρωμές σε πραγματικό χρόνο

Όταν ένας χρήστης ολοκληρώσει μια πληρωμή, εμείς αμέσως:

  • Καλέστε το Stancer's /payment καταληκτικό σημείο

  • Αποθηκεύστε το αναγνωριστικό συναλλαγής σε ένα προσαρμοσμένο πεδίο στο τιμολόγιο

  • Ενημέρωση των αρχείων πληρωμών του Dolibarr μέσω του API ή της ενεργοποίησης

Ενσωμάτωση Webhook

Το Stancer υποστηρίζει επανακλήσεις για εκδηλώσεις όπως:

  • Επιτυχία ή αποτυχία πληρωμής

  • Ανανεώσεις συνδρομών

Καταχωρήσαμε ένα webhook στον πίνακα ελέγχου του Stancer που δείχνει προς:

https://yourdomain.com/custom/stancer/webhook.php

Αυτό το σενάριο διαβάζει το εισερχόμενο JSON, το επικυρώνει και ενημερώνει την κατάσταση του τιμολογίου στο Dolibarr.

9. Δοκιμή και εντοπισμός σφαλμάτων ενσωμάτωσης Stancer

Δοκιμές που καλύπτονται:

  • Επιτυχείς πληρωμές (Visa/Mastercard)

  • Απορρίψεις πληρωμών (προσομοίωση με κάρτες δοκιμών Stancer)

  • Ανανεώσεις και ακυρώσεις συνδρομών

  • Περιπτώσεις σφάλματος (προβλήματα δικτύου, λανθασμένα μορφοποιημένα ωφέλιμα φορτία)

Καταγράψαμε όλες τις απαντήσεις API σε ένα ασφαλές αρχείο καταγραφής και χρησιμοποιήσαμε το Dolibarr's dol_syslog() για εσωτερική παρακολούθηση.

Συνήθη προβλήματα που περιλάμβαναν:

  • Σφάλματα κωδικοποίησης σε φορτία POST

  • Προσθήκη στη λίστα επιτρεπόμενων IP Webhook

  • Μη σύγχρονες ενημερώσεις σε επαναλαμβανόμενες πληρωμές

10. Ζητήματα διεπαφής χρήστη και εμπειρίας χρήστη

Η ενότητα μας παρέχει:

  • Μια σελίδα διαμόρφωσης στην ενότητα "Ρύθμιση τρίτου μέρους" για την εισαγωγή του κλειδιού API

  • Δείκτες κατάστασης πληρωμής στην προβολή τιμολογίου

  • Μηνύματα σφάλματος όταν μια συναλλαγή αποτυγχάνει

  • Ειδοποιήσεις μέσω email τόσο στον διαχειριστή όσο και στον πελάτη σχετικά με την κατάσταση πληρωμής

Αποφύγαμε τον επανασχεδιασμό του βασικού UI και αντ' αυτού επεκτείναμε τα υπάρχοντα πρότυπα όπου ήταν δυνατόν.

11. Προκλήσεις και διδάγματα ολοκλήρωσης στον πραγματικό κόσμο

1. Συμβατότητα έκδοσης Dolibarr

Αλλαγές σε βασικά αντικείμενα σε όλες τις εκδόσεις του Dolibarr (π.χ., Facture κλάση) προκάλεσε αρχικά σφάλματα. Λύση: αφηρημένη λογική σε κλάσεις υπηρεσιών και δοκιμή σε όλες τις εκδόσεις.

2. Ασφαλής αποθήκευση διακριτικών

Αρχικά αποθηκεύσαμε το κλειδί API σε απλό κείμενο. Μεταφέρθηκε σε κρυπτογραφημένο χώρο αποθήκευσης χρησιμοποιώντας τις ενσωματωμένες μεθόδους απόκρυψης του Dolibarr.

3. Χρονισμός Επιβεβαίωσης Πληρωμής

Η ασύγχρονη επιβεβαίωση webhook μερικές φορές συγκρούονταν με τις μη αυτόματες εισόδους πληρωμής. Προσθέσαμε μια λογική καθυστέρησης και διπλού ελέγχου.

12. Ασφάλεια και συμμόρφωση στις ενότητες πληρωμών

Η ασφάλεια είναι ύψιστης σημασίας στις ενσωματώσεις πληρωμών:

  • Το HTTPS είναι υποχρεωτικό για όλες τις επικοινωνίες

  • Το τελικό σημείο webhook πρέπει να επαληθεύει τις υπογραφές HMAC (εάν υπάρχουν)

  • Ευαίσθητα δεδομένα, όπως οι αριθμοί καρτών, δεν αποθηκεύονται ποτέ — μόνο διακριτικά ή αναγνωριστικά συναλλαγών

  • Τα αρχεία καταγραφής ελέγχου αποθηκεύονται με ασφάλεια και ελέγχονται περιοδικά

Επίσης, εξετάσαμε τη συμμόρφωση με τον ΓΚΠΔ και ενημερώσαμε τους χρήστες σχετικά με την επεξεργασία δεδομένων κατά τη διάρκεια της εγκατάστασης.

13. Συμβουλές για την ανάπτυξη και τη συντήρηση

  • Χρησιμοποιήστε ένα περιβάλλον προετοιμασίας για ενημερώσεις

  • Καταγράψτε όλα τα προσαρμοσμένα άγκιστρα και τις παρακάμψεις

  • Προγραμματίστε τακτικές εναλλαγές κλειδιών API

  • Παρακολούθηση αρχείων καταγραφής για αποτυχημένες συναλλαγές ή προσπάθειες webhook

  • Ρύθμιση παραμέτρων δημιουργίας αντιγράφων ασφαλείας πριν από την αναβάθμιση του Dolibarr

14. Συνεισφορά Κοινότητας και Μελλοντικές Βελτιώσεις

Σχεδιάζουμε να:

  • Προσθήκη εγγενούς υποστήριξης για άμεσες χρεώσεις SEPA

  • Δημοσιεύστε την ενότητα στο Dolistore με τεκμηρίωση στα Αγγλικά και τα Γαλλικά

  • Υλοποίηση υποστήριξης πολλαπλών νομισμάτων

  • Προσθήκη συμβατότητας με τη λειτουργία επαναλαμβανόμενου τιμολογίου του Dolibarr

Ενθαρρύνουμε τις συνεισφορές μέσω του GitHub και διατηρούμε έναν ανοιχτό οδικό χάρτη.

15. Σύναψη

Η ανάπτυξη της ενότητας Stancer για το Dolibarr αποδείχθηκε μια ικανοποιητική πρόκληση. Απαιτούσε βαθιά γνώση τόσο των εσωτερικών λειτουργιών του Dolibarr όσο και των σύγχρονων αρχών ανάπτυξης API. Με προσεκτικό σχεδιασμό, ασφαλή κωδικοποίηση και σχόλια από την κοινότητα, δημιουργήσαμε μια ευέλικτη και έτοιμη για παραγωγή λύση πληρωμών.

Για οποιονδήποτε χρήστη του Dolibarr που επιθυμεί να εκσυγχρονίσει τη ροή εργασίας πληρωμών του, αυτή η ενσωμάτωση αποτελεί μια επεκτάσιμη και φιλική προς το χρήστη επιλογή. Καθώς η τεχνολογία πληρωμών εξελίσσεται, θα συνεχίσουμε να βελτιώνουμε την ενότητα και να υποστηρίζουμε την κοινότητα.