Ταυτοδύναμα αιτήματα

Ένα αίτημα μπορεί να αποτύχει αφού η Sursa έχει ήδη κάνει την εργασία: η σύνδεση διακόπτεται ή η διεργασία σας επανεκκινείται πριν φτάσει η απόκριση. Αν στείλετε ξανά το ίδιο POST, μπορεί να δημιουργήσετε δεύτερη κάρτα ή δεύτερο webhook. Ένα κλειδί ταυτοδυναμίας το αποτρέπει αυτό.

Στέλνετε μια κεφαλίδα Idempotency-Key με κάθε POST και PATCH. Αν η Sursa έχει ήδη δει ένα αίτημα με αυτό το κλειδί, δεν εκτελεί ξανά τη λειτουργία: επιστρέφει την απόκριση που αποθήκευσε την πρώτη φορά.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Ένα επαναλαμβανόμενο αίτημα λαμβάνει την ίδια κατάσταση και το ίδιο σώμα με το πρώτο, με μια επιπλέον κεφαλίδα:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Το επαναλαμβανόμενο αίτημα έχει το δικό του X-Request-Id.

Επιλογή κλειδιού

Χρησιμοποιείτε μια νέα τυχαία τιμή, όπως ένα UUID v4, για κάθε λογική λειτουργία: «δημιουργία αυτής της κάρτας», «καταχώριση αυτού του webhook». Χρησιμοποιείτε την ίδια τιμή σε κάθε επανάληψη αυτής της λειτουργίας και ποτέ σε άλλη.
Ένα καλό κλειδί προκύπτει από τα δικά σας δεδομένα, όταν υπάρχουν, για παράδειγμα sync-2026-10-24-record-1042. Τότε ακόμη και μια εργασία που επανεκκινήθηκε και έχασε τη μνήμη της στέλνει ξανά το ίδιο κλειδί.
Το κλειδί έχει από 1 έως 255 εκτυπώσιμους χαρακτήρες ASCII. Οτιδήποτε άλλο επιστρέφει 400 με τον κωδικό api.idempotency_key_invalid.

Τι κάνει η Sursa με το κλειδί

Περίπτωση	Απόκριση
Πρώτο αίτημα με αυτό το κλειδί	Η λειτουργία εκτελείται κανονικά.
Ίδιο κλειδί, ίδιο αίτημα, το πρώτο ολοκληρώθηκε με `2xx` ή `4xx`	Η αποθηκευμένη απόκριση, με `Idempotency-Replayed: true`. Η λειτουργία δεν εκτελείται ξανά.
Ίδιο κλειδί, το πρώτο αίτημα εκτελείται ακόμη	`409` `api.idempotency_in_progress` με `Retry-After: 1`. Περιμένετε και επαναλάβετε.
Ίδιο κλειδί, διαφορετική μέθοδος, διαδρομή, `Content-Type` ή σώμα	`409` `api.idempotency_mismatch`. Το κλειδί χρησιμοποιείται ήδη από άλλο αίτημα.
Το πρώτο αίτημα ολοκληρώθηκε με `5xx` ή `429`	Το κλειδί αποδεσμεύεται: το επόμενο αίτημα με αυτό εκτελεί ξανά τη λειτουργία.

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

Ποια αιτήματα το χρειάζονται

Μέθοδος	Idempotency-Key
`POST`, `PATCH`	Στείλτε το. Κάθε τελικό σημείο που αποθηκεύει την απόκρισή του για επανάληψη αναφέρει την κεφαλίδα στην αναφορά API.
`GET`, `PUT`, `DELETE`	Δεν χρειάζεται: αυτές οι μέθοδοι επαναλαμβάνονται με ασφάλεια από τη φύση τους. Η κεφαλίδα γίνεται δεκτή και δεν έχει καμία επίδραση.
`POST` που μόνο διαβάζει, όπως η αναζήτηση, οι οικονομικές αναφορές και το `POST /v1/catalog/resolve`	Γίνεται δεκτό, αλλά τίποτα δεν αποθηκεύεται: το αίτημα απλώς εκτελείται ξανά.

Ορισμένες λειτουργίες επαναλαμβάνονται με ασφάλεια ακόμη και χωρίς την κεφαλίδα:

Το PUT /v1/cards-by-external-id/{external_id} δημιουργεί ή αντικαθιστά την κάρτα με το δικό σας αναγνωριστικό· μια επανάληψη με το ίδιο περιεχόμενο δεν αλλάζει τίποτα.
Τα έγγραφα μιας προσαρμοσμένης πηγής ταυτοποιούνται με το δικό σας external_id· η εκ νέου αποστολή του ίδιου εγγράφου επιστρέφει unchanged.
Μια απάντηση σε ροή του POST /v1/chat χρησιμοποιεί το πεδίο request_id του σώματος αντί για την κεφαλίδα. Δείτε τον οδηγό Δημιουργία bot ερωτήσεων και απαντήσεων.

Ασφαλείς επαναλήψεις

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