PATCH/v1/cards/{card_id}

Ενημέρωση κάρτας

update_card

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

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

Παράμετροι διαδρομής

card_idstringυποχρεωτικό

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

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

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

external_idstring | null
Ορίζει ή αλλάζει το external_id της κάρτας· το "" ή το null το αφαιρεί. Αν το χρησιμοποιεί άλλη κάρτα του οργανισμού, το αίτημα επιστρέφει 409 cards.external_id_taken. Το external_id μιας κάρτας πηγής δεν αλλάζει (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Αποκρίσεις

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

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

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Επιτρεπόμενες τιμές: wholepartial
access_contactstring
Σε ποιον να απευθυνθείτε για πρόσβαση (μόνο όταν access=partial).
aclobject
Πεδία
- verifybooleanυποχρεωτικό
- writebooleanυποχρεωτικό
categorystringυποχρεωτικό
category_confidencenumber | nullυποχρεωτικό
category_lockedbooleanυποχρεωτικό
category_reviewbooleanυποχρεωτικό
category_sourceCategorySource | nullυποχρεωτικό
collectionstringυποχρεωτικό
collection_idintegerυποχρεωτικό
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Περιεχόμενο επεξεργαστή της τελευταίας δημοσιευμένης έκδοσης. Το πεδίο μπορεί να λείπει· σε αυτή την περίπτωση πάρτε το περιεχόμενο επεξεργαστή από ένα προσχέδιο (POST /v1/drafts με card_id).
editing_lockEditingLock | null
Ενεργό κλείδωμα επεξεργασίας. Το πεδίο μπορεί να λείπει· σε αυτή την περίπτωση ο επεξεργαστής μαθαίνει ποιος έχει το κλείδωμα από το 409 cards.locked στο POST /v1/cards/{card_id}/lock.
created_atstring (date-time)υποχρεωτικό
days_since_verifiedintegerυποχρεωτικό
errorstring | nullυποχρεωτικό
eventsarray of CardEvent
feedback_negintegerυποχρεωτικό
feedback_posintegerυποχρεωτικό
foldersarray of CardFolderRef
Μόνο στη λίστα καρτών: οι φάκελοι που περιέχουν την κάρτα (όσοι είναι ορατοί στον χρήστη), με τις διαδρομές τους από τη ρίζα της συλλογής. Μια κενή λίστα σημαίνει ότι η κάρτα δεν βρίσκεται σε κανέναν φάκελο.
has_tablesboolean
Μόνο στη λίστα καρτών.
hidden_partsboolean
idstringυποχρεωτικό
jobJob | null
kindCardKindυποχρεωτικό
org_idintegerυποχρεωτικό
owner_activeboolean | null
owner_idinteger | nullυποχρεωτικό
owner_namestring | nullυποχρεωτικό
pagesinteger | nullυποχρεωτικό
parserstring | nullυποχρεωτικό
Αναλυτής εγγράφων ως ουδέτερος κωδικός: document (πλήρης δομή: σελίδες, τίτλοι, πίνακες, σαρωμένες σελίδες), pdf (το επίπεδο κειμένου του PDF), docx, xlsx, csv, markdown, html, text. Η λίστα μπορεί να επεκταθεί.
partsarray of CardPartυποχρεωτικό
sensitivebooleanυποχρεωτικό
sha256string | nullυποχρεωτικό
sizeintegerυποχρεωτικό
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanυποχρεωτικό
source_pathstring | nullυποχρεωτικό
source_urlstring | nullυποχρεωτικό
statusstringυποχρεωτικό
Επιτρεπόμενες τιμές: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringυποχρεωτικό
titlestringυποχρεωτικό
trustnumberυποχρεωτικό
trust_if_verifiednumber
trust_partsTrustPartsυποχρεωτικό
updated_atstring (date-time)υποχρεωτικό
verificationVerificationυποχρεωτικό
verified_atstring (date-time) | nullυποχρεωτικό
verified_byinteger | nullυποχρεωτικό
verified_by_namestring | null
verifier_idsarray of integerυποχρεωτικό
verifiersarray of object
Πεδία
- activebooleanυποχρεωτικό
- idintegerυποχρεωτικό
- namestringυποχρεωτικό
verify_interval_daysintegerυποχρεωτικό
versionintegerυποχρεωτικό
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Χειροκίνητες ρυθμίσεις ανάλυσης εγγράφου (προεπισκόπηση).
doc_kindDocKind | null
Τύπος εγγράφου. null, αν ο τύπος δεν έχει προσδιοριστεί (για παράδειγμα, για κάρτες που ευρετηριάστηκαν πριν από την εισαγωγή των τύπων εγγράφων).
doc_kind_confidencenumber | null
Βαθμός βεβαιότητας για τον τύπο του εγγράφου, από 0 έως 1.
doc_kind_sourcestring | null
Τι προσδιόρισε τον τύπο: κανόνες (rules), ένας χρήστης (manual) ή αυτόματη ταξινόμηση. Η λίστα μπορεί να επεκταθεί: θεωρήστε μια άγνωστη τιμή αυτόματη ταξινόμηση.
Επιτρεπόμενες τιμές: rulesmanualnull
invoiceDocInvoiceExtraction | null
Πεδία τιμολογίου, πιστωτικού τιμολογίου ή απόδειξης (μόνο για αυτούς τους τύπους και μόνο στην κάρτα, όχι στη λίστα). null, αν δεν έχετε πρόσβαση σε ολόκληρο το έγγραφο, επειδή τα πεδία εξάγονται από ολόκληρο το έγγραφο.
warningsarray of ReviewWarning
Προειδοποιήσεις της ανάλυσης του εγγράφου (ReviewWarning· μόνο στην κάρτα, όχι στη λίστα).
enrichmentCardEnrichmentStatus | null
Κατάσταση εμπλουτισμού (μόνο στην κάρτα, όχι στη λίστα). Ο τύπος του εγγράφου, τα πεδία του τιμολογίου και οι οικονομικές εγγραφές προστίθενται στο παρασκήνιο μετά την ευρετηρίαση και μπορούν να υπολογιστούν ξανά αργότερα· εμφανίζονται στην κάρτα, όταν είναι έτοιμα. null σημαίνει ότι δεν υπάρχει διαθέσιμη κατάσταση (η κάρτα ευρετηριάστηκε χωρίς εμπλουτισμό στο παρασκήνιο).
external_idstring | null
ID της κάρτας στο σύστημά σας. Είναι μοναδικό στον οργανισμό μεταξύ των καρτών που δεν προέρχονται από πηγές· null σημαίνει ότι δεν έχει οριστεί. Το /v1/cards-by-external-id/{external_id} διαβάζει και αντικαθιστά την κάρτα με βάση αυτό.
length ≤ 512
metadataMetadata

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 PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Δοκιμάστε το

Κλειδί API

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

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

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

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

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