Πώς να ρυθμίσετε ειδοποιήσεις ολοκλήρωσης παραγγελιών API

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

Πρώτα καθορίστε ποια κατάσταση στο API σημαίνει την πραγματική ολοκλήρωση της παραγγελίας. Σε διαφορετικούς παρόχους αυτές μπορεί να είναι εκτελεσμένη, παραδομένη, ακυρωμένη, απορριφθείσα, επιστραφείσα ή μερικώς εκτελεσμένη παραγγελία. Μην συνδέετε τον αυτοματισμό μόνο με τη λέξη «επιτυχία»: η παραγγελία μπορεί να περάσει από πολλές ενδιάμεσες καταστάσεις και στη συνέχεια να σταματήσει λόγω ορίου, ελέγχου ή ακύρωσης.

Δεν πρέπει να επεξεργάζεστε μόνο το θετικό αποτέλεσμα. Αν η υπηρεσία στέλνει ειδοποίηση για σφάλμα, ακύρωση, επιστροφή ή μερική εκτέλεση, θα πρέπει επίσης να την καταγράφετε στο εσωτερικό σύστημα. Διαφορετικά, στον πίνακα, στο CRM ή στο bot η παραγγελία θα παραμείνει σε αναμονή, παρόλο που η περαιτέρω εκτέλεση δεν θα πραγματοποιηθεί.

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

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

• pending, created, queued — νέα παραγγελία ή παραγγελία σε αναμονή επεξεργασίας.
• processing, in_progress, running — η παραγγελία εκτελείται.
• completed, delivered, success — εκτελεσμένη παραγγελία.
• partial, partially_completed — μερικώς εκτελεσμένη παραγγελία.
• cancelled, rejected, failed — ακυρωμένη παραγγελία ή παραγγελία που ολοκληρώθηκε με σφάλμα.
• refunded, returned — η παραγγελία απαιτεί επιστροφή χρημάτων ή διόρθωση.
• Άγνωστη κατάσταση — δεν αλλάζει αυτόματα την κάρτα και αποστέλλεται για έλεγχο.

Τα ονόματα παραπάνω δίνονται ως παράδειγμα σχήματος. Ο τελικός πίνακας πρέπει να βασίζεται στις καταστάσεις του συγκεκριμένου API. Το μειονέκτημα της χειροκίνητης αντιστοίχισης είναι ότι μετά την ενημέρωση του API πρέπει να τη συντηρείτε: μια νέα κατάσταση μπορεί να φτάσει στον handler πριν δημιουργηθεί κανόνας γι' αυτήν.

Επιλέξτε webhooks, polling API ή και τα δύο σχήματα

Το webhook είναι ένα αίτημα από την υπηρεσία προς το URL σας όταν αλλάζει η κατάσταση της παραγγελίας. Το polling API λειτουργεί αντίστροφα: το σύστημά σας ζητά πληροφορίες για την παραγγελία ανά τακτά διαστήματα. Για ειδοποιήσεις ολοκλήρωσης συνήθως είναι πιο βολικά τα webhooks, επειδή η ενημέρωση φτάνει χωρίς συνεχή αιτήματα στη μέθοδο ελέγχου κατάστασης.

• Τα webhooks είναι κατάλληλα για γρήγορη αντίδραση: ενημέρωση κάρτας, έναρξη επόμενου σταδίου ή αποστολή μηνύματος στον υπεύθυνο.
• Το polling είναι κατάλληλο αν ο πάροχος δεν υποστηρίζει ειδοποιήσεις callback ή ο διακομιστής δεν δέχεται εξωτερικά αιτήματα.
• Το συνδυασμένο σχήμα χρησιμοποιεί τα webhooks ως κύριο κανάλι και το polling για τον εντοπισμό χαμένων ή κολλημένων παραγγελιών.

Το μειονέκτημα του polling είναι η καθυστέρηση και το περιττό φορτίο στο API. Το μειονέκτημα των webhooks είναι ότι πρέπει να προστατεύσετε το endpoint, να λαμβάνετε υπόψη τα διπλότυπα και να μην βασίζεστε στη σειρά παράδοσης των συμβάντων.

Ρυθμίστε το endpoint για τη λήψη συμβάντων

Για τις ειδοποιήσεις χρειάζεστε μια δημόσια διεύθυνση HTTPS, προσβάσιμη από την πλευρά της υπηρεσίας API. Στις ρυθμίσεις της ενσωμάτωσης συνήθως καθορίζονται το URL του handler, το μυστικό υπογραφής και η λίστα συμβάντων: αλλαγή κατάστασης, ολοκλήρωση, ακύρωση, σφάλμα ή μερική εκτέλεση.

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

Πριν από την εκκίνηση ελέγξτε τη μέθοδο αιτήματος και τη μορφή του σώματος σύμφωνα με την τεκμηρίωση. Τις περισσότερες φορές είναι POST με JSON, αλλά υπάρχουν form-data, query-παράμετροι ή δικό τους σχήμα σειριοποίησης. Το σφάλμα ανάλυσης πρέπει να καταγράφεται στο αρχείο καταγραφής, διαφορετικά θα είναι δύσκολο να διακρίνετε ένα λανθασμένο payload από μια βλάβη της εφαρμογής.

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

Κατά τη δημιουργία παραγγελίας μέσω API, αποθηκεύετε το αναγνωριστικό που επέστρεψε ο πάροχος. Δίπλα αποθηκεύετε τον εσωτερικό αριθμό παραγγελίας, τον τύπο υπηρεσίας, την αρχική κατάσταση, την ώρα τελευταίας αλλαγής και την αρχική απόκριση API σε ασφαλή μορφή. Αντιστοιχίζετε το εισερχόμενο webhook με βάση το ID του παρόχου, όχι με βάση τον σύνδεσμο του καναλιού, το όνομα της υπηρεσίας ή το όνομα του πελάτη.

Αν το API επιτρέπει τη μεταβίβαση εξωτερικού αναγνωριστικού κατά τη δημιουργία, προσθέστε τον δικό σας αριθμό παραγγελίας σε ένα πεδίο όπως external_id ή client_reference. Αυτό διευκολύνει την αναζήτηση στα logs και την ανάλυση αμφισβητούμενων περιπτώσεων. Αλλά μην κάνετε τον εξωτερικό αριθμό το μοναδικό κλειδί: ορισμένοι πάροχοι δεν τον επιστρέφουν σε κάθε ειδοποίηση.

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

Χρησιμοποιήστε μια σαφή δομή payload

Τα ακριβή ονόματα πεδίων εξαρτώνται από το API. Παρακάτω δεν είναι το συμβόλαιο συγκεκριμένης υπηρεσίας, αλλά ένα παράδειγμα συμβάντος JSON στο οποίο μπορείτε να βασιστείτε κατά τον σχεδιασμό του εσωτερικού handler. Σημαντικά είναι το αναγνωριστικό συμβάντος, το ID παραγγελίας στον πάροχο, η κατάσταση, η ώρα αλλαγής και τα δεδομένα για διάγνωση.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Μην χρησιμοποιείτε την ποσότητα εκτελεσμένων μονάδων ως ένδειξη ολοκλήρωσης χωρίς κατάσταση. Η παραγγελία μπορεί να έχει εκτελεστεί μερικώς, και ο αριθμός στο payload μπορεί να είναι στρογγυλοποιημένος, να έχει ενημερωθεί με καθυστέρηση ή να μην έχει μεταβιβαστεί καθόλου. Το μειονέκτημα της αποθήκευσης ολόκληρου του σώματος του συμβάντος είναι ότι μπορεί να περιέχει προσωπικά δεδομένα ή υπηρεσιακά πεδία, γι' αυτό τέτοιες εγγραφές πρέπει να μασκάρουνται και να περιορίζονται ως προς τον χρόνο αποθήκευσης.

Επαληθεύετε την υπογραφή με βάση το αρχικό σώμα του αιτήματος

Το ανοιχτό URL του handler μπορεί να λάβει αίτημα όχι μόνο από την υπηρεσία API. Αν ο πάροχος μεταβιβάζει υπογραφή, μυστικό ή token, επαληθεύετέ τα πριν αλλάξετε την παραγγελία. Ένα συνηθισμένο σχήμα είναι το HMAC-SHA256: ο πάροχος υπολογίζει την υπογραφή από τα byte του σώματος του αιτήματος και ένα κοινό μυστικό και στη συνέχεια μεταβιβάζει το αποτέλεσμα σε HTTP-header.

Η αρχή του υπολογισμού είναι η εξής: λαμβάνεται το αρχικό σώμα του αιτήματος, για παράδειγμα τα byte του JSON χωρίς αλλαγές, και το μυστικό της ενσωμάτωσης. Στη συνέχεια υπολογίζεται το HMAC-SHA256. Αν το αποτέλεσμα σε δεκαεξαδική μορφή συμπίπτει με την τιμή του header, το σώμα δεν άλλαξε μετά την υπογραφή και το αίτημα πιθανότατα στάλθηκε από πλευρά που γνωρίζει το μυστικό.

Υποθετικό παράδειγμα: HMAC_SHA256(μυστικό, raw_body) = υπογραφή από το header X-Signature. Το όνομα του header, ο αλγόριθμος και η μορφή του αποτελέσματος πρέπει να λαμβάνονται μόνο από την τεκμηρίωση του API. Ορισμένες υπηρεσίες προσθέτουν χρονική σήμανση ή ID συμβάντος στη συμβολοσειρά για υπογραφή. Σε αυτή την περίπτωση δεν μπορείτε να επαληθεύσετε μόνο το σώμα JSON.

Μην αλλάζετε το JSON πριν από την επαλήθευση της υπογραφής

Η υπογραφή επαληθεύεται με βάση τα αρχικά byte του αιτήματος, όχι με βάση το αντικείμενο JSON που η εφαρμογή έχει ήδη αναλύσει και επανασυναρμολογήσει. Κατά την εκ νέου σειριοποίηση μπορεί να αλλάξει η σειρά των πεδίων, τα κενά, η διαφυγή χαρακτήρων, η αλλαγή γραμμής ή η κωδικοποίηση. Για τον άνθρωπο το JSON θα παραμείνει το ίδιο, αλλά το σύνολο των byte θα αλλάξει και το HMAC δεν θα συμπίπτει πλέον.

Για να το αποφύγετε, πρώτα λάβετε το raw body ως bytes ή buffer, αποθηκεύστε το στη μνήμη, υπολογίστε την υπογραφή και μόνο μετά την επιτυχή επαλήθευση αναλύστε το JSON. Μην εφαρμόζετε στο σώμα trim, μετατροπή κωδικοποίησης, ταξινόμηση κλειδιών και μορφοποίηση. Στο middleware του framework ελέγξτε αν το JSON αναλύεται αυτόματα πριν από την πρόσβαση στο αρχικό σώμα.

Το μειονέκτημα αυτού του σχήματος είναι ότι ο handler γίνεται εξαρτημένος από τη σειρά του middleware. Με λανθασμένη ρύθμιση η εφαρμογή θα βλέπει μόνο το μετασχηματισμένο αντικείμενο και οι νόμιμες ειδοποιήσεις θα αρχίσουν να απορρίπτονται.

Παράδειγμα handler με επαλήθευση HMAC

Παρακάτω ένα υποθετικό παράδειγμα σε Python. Δείχνει τη σειρά ενεργειών, όχι μια έτοιμη ενσωμάτωση: τα headers, ο αλγόριθμος, η μορφή υπογραφής και τα πεδία payload πρέπει να αντικατασταθούν με τις τιμές από την τεκμηρίωση του παρόχου.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Για τη σύγκριση χρησιμοποιήστε μια συνάρτηση που δεν σταματά στον πρώτο χαρακτήρα που δεν συμπίπτει. Αυτό μειώνει τον κίνδυνο διαρροής δεδομένων για την υπογραφή μέσω του χρόνου απόκρισης. Μην μεταβιβάζετε το μυστικό σε κώδικα πελάτη, μην το προσθέτετε στο URL και μην το καταγράφετε ολόκληρο στα logs.

Κάντε την επεξεργασία συμβάντων idempotent

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

Idempotency σημαίνει ότι το ίδιο συμβάν αλλάζει το αποτέλεσμα μόνο μία φορά. Αν δεν λάβετε υπόψη αυτόν τον κανόνα, το διπλότυπο θα στείλει ξανά μήνυμα στον πελάτη, θα δημιουργήσει πολλές εργασίες στον διαχειριστή, θα χορηγήσει αποζημίωση ή θα ξεκινήσει ξανά μια λειτουργία.

Το καλύτερο είναι να χρησιμοποιείτε το event_id από το payload. Αποθηκεύετέ το σε ξεχωριστό πίνακα ή αρχείο καταγραφής επεξεργασμένων συμβάντων με μοναδικό περιορισμό. Αν δεν υπάρχει ξεχωριστό ID, σχηματίστε κλειδί από σταθερά πεδία: ID παραγγελίας παρόχου, τύπο συμβάντος, κατάσταση και ώρα αλλαγής. Αυτή η επιλογή είναι χειρότερη: με ανακριβείς χρονικές σημάνσεις διαφορετικά συμβάντα μπορεί να φαίνονται ίδια.

Αποθηκεύετε το συμβάν και την κατάσταση σε μία λειτουργία

Ο έλεγχος «έχει επεξεργαστεί το συμβάν» και η εγγραφή του αποτελέσματος πρέπει να εκτελούνται ατομικά. Διαφορετικά, δύο ίδια αιτήματα που φτάνουν ταυτόχρονα θα δουν και τα δύο την απουσία εγγραφής και θα ξεκινήσουν την ενέργεια δύο φορές. Μια πρακτική επιλογή είναι το μοναδικό ευρετήριο κατά event_id και μια συναλλαγή βάσης δεδομένων.

Η υποθετική συνέχεια του handler είναι η εξής:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

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

Λάβετε υπόψη την παραβίαση της σειράς συμβάντων

Τα webhooks δεν φτάνουν πάντα αυστηρά με τη σειρά της ώρας αλλαγής κατάστασης. Πρώτα μπορεί να φτάσει συμβάν ολοκλήρωσης και μετά μια καθυστερημένη ειδοποίηση για κατάσταση «σε εκτέλεση». Αν απλώς καταγράφετε την τελευταία ληφθείσα τιμή, η εκτελεσμένη παραγγελία θα γίνει ξανά ενεργή.

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

Αν το payload περιέχει ώρα αλλαγής της παραγγελίας, συγκρίνετε ακριβώς αυτήν, όχι την ώρα λήψης του webhook. Όταν το API δεν μεταβιβάζει τέτοια σήμανση, χρησιμοποιήστε προτεραιότητες καταστάσεων και επαλήθευση μέσω της μεθόδου λήψης παραγγελίας. Το μειονέκτημα των προτεραιοτήτων είναι ότι δεν αντικαθιστούν την πραγματική ακολουθία, ειδικά αν ο πάροχος επιτρέπει επιστροφή από τελική κατάσταση.

Επιβεβαιώνετε γρήγορα την παράδοση και μεταφέρετε τις ενέργειες σε ουρά

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

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

Το μειονέκτημα της ουράς είναι ότι εμφανίζεται ένα ξεχωριστό στοιχείο που πρέπει να ελέγχετε: σφάλματα εργασιών, καθυστερήσεις και επαναληπτικές εκτελέσεις. Ωστόσο, μια βλάβη στην ειδοποίηση του διαχειριστή δεν μπλοκάρει τη λήψη καταστάσεων παραγγελιών.

Ρυθμίστε ειδοποιήσεις για την ομάδα και τον πελάτη

Μετά την αλλαγή κατάστασης δεν χρειάζεται να ειδοποιείτε όλους με τον ίδιο τρόπο. Στον διαχειριστή συνήθως είναι σημαντικές οι ακυρώσεις, τα σφάλματα, η μερική εκτέλεση και οι παραγγελίες που δεν αλλάζουν για πολύ. Στον πελάτη τις περισσότερες φορές αρκεί ένα σαφές τελικό αποτέλεσμα: η παραγγελία εκτελέστηκε, ακυρώθηκε ή απαιτεί διευκρίνιση.

• Εκτελεσμένη παραγγελία — ενημέρωση στον προσωπικό λογαριασμό ή σύντομο μήνυμα στον πελάτη.
• Σφάλμα εκτέλεσης — ειδοποίηση στον υπεύθυνο με την αιτία που μεταβίβασε το API.
• Μερική εκτέλεση — εργασία για έλεγχο διόρθωσης, επιστροφής ή επόμενης ενέργειας.
• Άγνωστη κατάσταση — εγγραφή στο αρχείο καταγραφής και μήνυμα στον τεχνικό ειδικό.
• Άγνωστο ID παραγγελίας — ξεχωριστός έλεγχος της σύνδεσης μεταξύ του συστήματός σας και του παρόχου.

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

Τηρείτε αρχείο καταγραφής και επαληθεύετε τις μη ολοκληρωμένες παραγγελίες

Τα logs χρειάζονται για να καταλάβετε αν η υπηρεσία έστειλε συμβάν, ποιο σώμα έφτασε, γιατί δεν πέρασε η υπογραφή και σε ποιο στάδιο σταμάτησε η επεξεργασία. Αποθηκεύετε την ώρα λήψης, το ID συμβάντος, το ID παραγγελίας, τον τύπο συμβάντος, το αποτέλεσμα της επαλήθευσης υπογραφής, την εσωτερική κατάσταση και τον κωδικό απόκρισης. Μασκάρτε τα μυστικά, τα tokens και τα προσωπικά δεδομένα.

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

Επαληθεύετε περιοδικά τις παραγγελίες σε ενδιάμεσες καταστάσεις μέσω της μεθόδου λήψης δεδομένων του API. Αυτός ο έλεγχος δεν αντικαθιστά τα webhooks, αλλά βοηθά στον εντοπισμό χαμένου συμβάντος, βλάβης της ουράς ή περίπτωσης όπου η εξωτερική κατάσταση άλλαξε χωρίς σωστή ειδοποίηση.