POST/v1/cards/bulk

Εκτέλεση μαζικής ενέργειας σε κάρτες

bulk_cards

Εκτελεί μια μαζική ενέργεια στις επιλεγμένες κάρτες. Τα δικαιώματα ελέγχονται για κάθε κάρτα: ο ρόλος στη συλλογή και το προφίλ δεδομένων (οι καταστροφικές ενέργειες απαιτούν πρόσβαση σε κάθε μέρος του εγγράφου). Οι κάρτες στις οποίες δεν μπορείτε να ενεργήσετε παραλείπονται με αιτιολογία. Κάθε αλλαγή καταγράφεται στο αρχείο ελέγχου της κάρτας, συν μία εγγραφή cards.bulk με το αποτέλεσμα.

Ενέργειες φακέλων:
- Το folder_move με params.folder_id (υποχρεωτικό) τοποθετεί την κάρτα στον φάκελο και, αν δοθεί το params.from_folder_id, την αφαιρεί από εκείνον τον φάκελο (μετακίνηση έξω από τον ανοιχτό φάκελο).
- Το folder_remove με params.folder_id αφαιρεί την κάρτα από τον φάκελο· η κάρτα παραμένει στη συλλογή.

Οι φάκελοι ελέγχονται μία φορά ανά αίτημα: φάκελος που λείπει ή δεν είναι ορατός επιστρέφει 404 folders.not_found, η έλλειψη του δικαιώματος COLLECTION_EDIT_CARDS στον φάκελο επιστρέφει 403 authz.forbidden, και η απουσία του folder_id ή ένα from_folder_id από άλλη συλλογή επιστρέφει 400 cards.bulk_invalid. Για κάθε κάρτα: χωρίς CARD_EDIT η κάρτα παραλείπεται ως no_write· κάρτα από άλλη συλλογή από εκείνη του φακέλου παραλείπεται ως collection_mismatch· κάρτα που βρίσκεται ήδη στη θέση της αναφέρεται ως unchanged.

Έλεγχος ταυτότητας

Στείλτε ένα κλειδί API στην κεφαλίδα Authorization: Authorization: Bearer <κλειδί>.

Παράμετροι κεφαλίδας

Idempotency-Keystring
Κλειδί για ασφαλή επανάληψη μιας εγγραφής δεδομένων: 1 έως 255 εκτυπώσιμοι χαρακτήρες ASCII· συνιστάται ένα UUID v4 ανά λογική λειτουργία. Επανάληψη με το ίδιο κλειδί εντός 24 ωρών δεν εκτελεί ξανά τη λειτουργία: επιστρέφει την αποθηκευμένη απόκριση (κατάσταση, κεφαλίδες και σώμα) με την κεφαλίδα Idempotency-Replayed: true. Το ίδιο κλειδί με διαφορετική μέθοδο, διαδρομή, Content-Type ή σώμα επιστρέφει 409 api.idempotency_mismatch· όσο το πρώτο αίτημα εκτελείται ακόμη – 409 api.idempotency_in_progress με Retry-After: 1. Μετά από απόκριση 5xx ή 429 το κλειδί αποδεσμεύεται, και η επανάληψη εκτελεί ξανά τη λειτουργία. Το κλειδί ισχύει στο πλαίσιο του οργανισμού και του πελάτη που καλεί το API (κλειδί API, χρήστης ή κλειδί προσαρμοσμένης πηγής).
length ≥ 1, length ≤ 255
X-View-Asstring
Μόνο για κλειδιά API με τον ρόλο admin. Εκτελεί το αίτημα ως το προφίλ δεδομένων <profile>[:viewer|verifier|editor], για παράδειγμα employee:viewer. Το κλειδί εγκατάστασης δεν μπορεί να χρησιμοποιήσει αυτή την κεφαλίδα (403).

Παράμετροι cookie

kb_view_asstring
Cookie της λειτουργίας «View as» για μια συνεδρία. Το POST /auth/view-as το ορίζει και το DELETE /auth/view-as το καταργεί.

Σώμα αιτήματος

application/json

Αντικείμενο: BulkRequest

idsarray of stringυποχρεωτικό
items ≥ 1, items ≤ 500
actionBulkActionυποχρεωτικό
paramsobject

Αποκρίσεις

200Επιτυχής απόκριση

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.
Idempotency-Replayed
Το true σημαίνει ότι η απόκριση επαναλήφθηκε από την αποθηκευμένη για αυτό το Idempotency-Key: η λειτουργία δεν εκτελέστηκε ξανά.

application/json

Αντικείμενο: BulkResult

countsobjectυποχρεωτικό
Πεδία
- doneintegerυποχρεωτικό
- reasonsobjectυποχρεωτικό
  Πεδία
  - admin_onlynumber
  - collection_mismatchinteger
  - connectornumber
  - failedinteger
  - needs_usernumber
  - no_verifynumber
  - no_writenumber
  - not_foundnumber
  - partial_accessnumber
  - processinginteger
  - same_collectionnumber
  - sensitive_lowernumber
  - target_needs_reindexnumber
  - unchangedinteger
- skippedintegerυποχρεωτικό
donearray of stringυποχρεωτικό
fileAttachment
jobsarray of integer
skippedarray of BulkSkippedυποχρεωτικό

400Το αίτημα δεν είναι έγκυρο: η τιμή μιας παραμέτρου ή η κατάσταση του αντικειμένου δεν επιτρέπει την ενέργεια (το `detail` είναι μήνυμα).

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

401Δεν στάλθηκαν διαπιστευτήρια (ούτε cookie συνεδρίας ούτε κλειδί API) ή το κλειδί δεν βρέθηκε.

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

403Η ενέργεια δεν επιτρέπεται: ο ρόλος δεν επαρκεί, δεν υπάρχει πρόσβαση στη συλλογή ή στην κάρτα, το αίτημα εκτελείται στη λειτουργία «View as» ή ο οργανισμός έχει ανασταλεί ή διαγραφεί (το `detail` είναι αντικείμενο με `code: org_suspended | org_deleted`).

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

404Το αντικείμενο δεν υπάρχει ή δεν είναι διαθέσιμο σε εσάς. Το API δεν επιβεβαιώνει ότι υπάρχει ένα αντικείμενο περιορισμένης πρόσβασης.

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

422Σφάλμα επικύρωσης: το σώμα ή οι παράμετροι δεν αντιστοιχούν στο σχήμα (το `detail` είναι λίστα σφαλμάτων επικύρωσης) ή η τιμή μιας παραμέτρου είναι εκτός εύρους (το `detail` είναι μήνυμα).

Κεφαλίδες απόκρισης

RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

429Πάρα πολλά αιτήματα (`api.rate_limited`), η ποσόστωση του οργανισμού για το λεπτό, την ημέρα ή τον μήνα εξαντλήθηκε (`api.quota_exceeded`· το `error.details` περιέχει τα `quota`, `limit` και `reset_at`), ο οργανισμός έφτασε στο όριό του ή η υπηρεσία απαντήσεων είναι απασχολημένη (`answers.engine_busy`). Περιμένετε τον χρόνο που δίνει η κεφαλίδα `Retry-After`.

Κεφαλίδες απόκρισης

Retry-After
Αριθμός δευτερολέπτων αναμονής πριν επαναλάβετε το αίτημα.
RateLimit-Policy
Τα όρια σε ισχύ, στη μορφή του προσχεδίου IETF draft-ietf-httpapi-ratelimit-headers: στοιχεία χωρισμένα με κόμμα "<name>";q=<quota>;w=<window in seconds>. Το key είναι ο ρυθμός αιτημάτων του κλειδιού API (η ποσόστωση είναι η ριπή, το παράθυρο είναι ο χρόνος για την πλήρη αναπλήρωσή της· για μια συνεδρία είναι user, χωρίς διαπιστευτήρια ip)· τα minute, day και month είναι οι ποσοστώσεις του οργανισμού για το ημερολογιακό λεπτό, την ημέρα και τον μήνα σε UTC.
RateLimit
Τι απομένει από κάθε όριο του RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Όριο της αυστηρότερης εγγραφής του RateLimit-Policy (εκείνης με τα λιγότερα εναπομείναντα αιτήματα).
X-RateLimit-Remaining
Αιτήματα που απομένουν στο αυστηρότερο όριο.
X-RateLimit-Reset
Δευτερόλεπτα έως τον μηδενισμό του αυστηρότερου ορίου.

application/json

Αντικείμενο: Error

Κωδικοί σφαλμάτων

Κωδικοί που μπορεί να επιστρέψει αυτό το τελικό σημείο στο error.code, εκτός από τους γενικούς κωδικούς κάθε αιτήματος.

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

Στείλτε μια κεφαλίδα Idempotency-Key (για παράδειγμα ένα UUID) με κάθε POST και PATCH. Μια επανάληψη με το ίδιο κλειδί εντός 24 ωρών επιστρέφει την αποθηκευμένη απόκριση αντί να εκτελέσει ξανά το αίτημα.

Όρια ρυθμού

Οι αποκρίσεις περιέχουν τις κεφαλίδες RateLimit και RateLimit-Policy, καθώς και τις παλαιότερες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απόκριση 429 έχει την κεφαλίδα Retry-After σε δευτερόλεπτα: περιμένετε και επαναλάβετε το αίτημα.

← cards · Αναφορά API

curl -X POST 'https://api.sursa.com/v1/cards/bulk' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"ids":["string"],"action":"verify"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Δοκιμάστε το

Κλειδί API

Το κλειδί μένει στη μνήμη αυτής της καρτέλας και αποστέλλεται μόνο στο https://api.sursa.com.

Τα αιτήματα επηρεάζουν τα πραγματικά δεδομένα του οργανισμού σας.

Idempotency-Key header

X-View-As header

Idempotency-Key

Αν το πεδίο μείνει κενό, δημιουργείται νέο κλειδί για κάθε αίτημα.

Σώμα αιτήματος (JSON)