GET/v1/cards
Λίστα καρτών
list_cards
Επιστρέφει κάρτες με φίλτρα, ταξινόμηση και σελιδοποίηση. Με preview=1 (για την προβολή πλακιδίων) κάθε κάρτα έχει επίσης preview (τους πρώτους 200 χαρακτήρες του κειμένου) και preview_tables (φύλλα με τον αριθμό γραμμών τους), εντός του προφίλ δεδομένων σας.
Έλεγχος ταυτότητας
Στείλτε ένα κλειδί API στην κεφαλίδα Authorization: Authorization: Bearer <κλειδί>.
Παράμετροι ερωτήματος
collectionstring | nullfolderstring | nullΤο
<folder ID>επιστρέφει τις κάρτες του φακέλου και όλων των υποφακέλων του. Τοnoneεπιστρέφει τις κάρτες της συλλογής που δεν βρίσκονται σε κανέναν φάκελο και απαιτείcollection(διαφορετικά400 cards.invalid_folder_filter). Αν ο φάκελος δεν υπάρχει ή δεν είναι ορατός σε εσάς, το αίτημα επιστρέφει404 folders.not_found.length ≤ 64
statusstring | nullΕπιτρεπόμενες τιμές:
processingreadyerrorarchivedallownerstring | nullme,noneή ID χρήστη.owner_idinteger | nullverificationstring | nullΕπιτρεπόμενες τιμές:
verifiedneeds_verificationstalekindCardKindtypestring | nullΤο
tableεπιστρέφει κάρτες με πίνακες γεγονότων, τοtext– κάρτες χωρίς αυτούς.Επιτρεπόμενες τιμές:
tabletexttagsstring | nullΕτικέτες χωρισμένες με κόμμα (η κάρτα πρέπει να τις έχει όλες).
idsstring | nullID καρτών χωρισμένα με κόμμα.
searchstring | nullcategorystring | nullsensitiveboolean | nullsortCardSortΠροεπιλογή: "created_at"
orderstringΕπιτρεπόμενες τιμές:
ascdescΠροεπιλογή: "desc"
limitintegerΠροεπιλογή: 200
offsetintegerΠροεπιλογή: 0
previewbooleanΤο
trueπροσθέτειpreview(τους πρώτους 200 χαρακτήρες) καιpreview_tablesγια την προβολή πλακιδίων.Προεπιλογή: false
updated_sincestring (date-time)Μόνο κάρτες με
updated_atίσο ή μεταγενέστερο από αυτή τη στιγμή (RFC 3339 με μετατόπιση ζώνης ώρας), για συγχρονισμό. Χωρίς ρητάsortκαιorder, η λίστα ταξινομείται κατάupdated_atσε αύξουσα σειρά και στη συνέχεια κατάid. Οι διαγραμμένες κάρτες δεν εμφανίζονται στη λίστα: οι διαγραφές έρχονται ως συμβάντα.metadatamap of stringΦιλτράρισμα κατά
metadata: τοmetadata[<key>]=<value>ταιριάζει ακριβώς. Έως 3 συνθήκες, και πρέπει να ταιριάζουν όλες (?metadata[team]=support&metadata[crm_id]=A-1042). Περισσότερες από 3 συνθήκες ή μη έγκυρο κλειδί επιστρέφουν400 api.metadata_invalid.collection_idintegerΣυλλογή με βάση το ID. Όταν δίνεται και το
collection, υπερισχύει τοcollection_id. Συλλογή που δεν υπάρχει στον οργανισμό ή δεν είναι ορατή επιστρέφει404 collections.not_found.external_idstringΜόνο η κάρτα με αυτό το
external_id.cursorstringΔρομέας της επόμενης σελίδας από το
X-Next-Cursorή τοnext_cursorτης προηγούμενης απόκρισης με τα ίδια φίλτρα· μεταφέρει το μέγεθος σελίδας. Μαζί μεoffset:422 validation.failed· δρομέας άλλης λίστας, με άλλα φίλτρα ή με λανθασμένη μορφή:400 api.cursor_invalid.length ≤ 512
expand[]array of stringΣυσχετισμένα αντικείμενα που θα συμπεριληφθούν στην απόκριση (από την 1.62.0): μια διαδρομή από τη λίστα
x-expandableτης λειτουργίας. Επαναλάβετε την παράμετρο έως 10 φορές. Μια διαδρομή έχει έως 2 τμήματα που χωρίζονται με τελεία (collection.default_owner). Σε μια λίστα, η διαδρομή αρχίζει μεdata.και ισχύει για κάθε στοιχείο της σελίδας (expand[]=data.owner). Ένα αναπτυγμένο αντικείμενο μπαίνει στο αντικείμενοexpandedτου στοιχείου και το πεδίο ID παραμένει. Ένα αντικείμενο που ο πελάτης που καλεί το API δεν επιτρέπεται να δει σύμφωνα με τους ελέγχους της δικής του λειτουργίας ανάγνωσης αναπτύσσεται ωςnull. Μια άγνωστη διαδρομή, περισσότερες από 10 διαδρομές ή μια διαδρομή βαθύτερη από 2 τμήματα επιστρέφει400 api.expand_invalid.items ≤ 10
Παράμετροι κεφαλίδας
X-View-AsstringΜόνο για κλειδιά API με τον ρόλο
admin. Εκτελεί το αίτημα ως το προφίλ δεδομένων<profile>[:viewer|verifier|editor], για παράδειγμαemployee:viewer. Το κλειδί εγκατάστασης δεν μπορεί να χρησιμοποιήσει αυτή την κεφαλίδα (403).
Παράμετροι cookie
kb_view_asstringCookie της λειτουργίας «View as» για μια συνεδρία. Το
POST /auth/view-asτο ορίζει και τοDELETE /auth/view-asτο καταργεί.
Αποκρίσεις
200Επιτυχής απόκριση
Κεφαλίδες απόκρισης
LinkΔιεύθυνση της επόμενης σελίδας,
<…>; rel="next". Η απουσία της κεφαλίδας σημαίνει ότι αυτή είναι η τελευταία σελίδα.X-Next-CursorΔρομέας της επόμενης σελίδας για την παράμετρο
cursor. Η απουσία της κεφαλίδας σημαίνει ότι αυτή είναι η τελευταία σελίδα.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
expandedCardExpandedpermissionsObjectPermissionListaccessstringΕπιτρεπόμενες τιμές:
wholepartialaccess_contactstringΣε ποιον να απευθυνθείτε για πρόσβαση (μόνο όταν
access=partial).aclobjectΠεδία
verifybooleanυποχρεωτικόwritebooleanυποχρεωτικό
categorystringυποχρεωτικόcategory_confidencenumber | nullυποχρεωτικόcategory_lockedbooleanυποχρεωτικόcategory_reviewbooleanυποχρεωτικόcollectionstringυποχρεωτικόcollection_idintegerυποχρεωτικόcollection_titlestringcommentsarray of CardCommentcontent_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 CardEventfeedback_negintegerυποχρεωτικόfeedback_posintegerυποχρεωτικόfoldersarray of CardFolderRefΜόνο στη λίστα καρτών: οι φάκελοι που περιέχουν την κάρτα (όσοι είναι ορατοί στον χρήστη), με τις διαδρομές τους από τη ρίζα της συλλογής. Μια κενή λίστα σημαίνει ότι η κάρτα δεν βρίσκεται σε κανέναν φάκελο.
has_tablesbooleanΜόνο στη λίστα καρτών.
hidden_partsbooleanidstringυποχρεωτικόjobJob | nullorg_idintegerυποχρεωτικόowner_activeboolean | nullowner_idinteger | nullυποχρεωτικόowner_namestring | nullυποχρεωτικόpagesinteger | nullυποχρεωτικόparserstring | nullυποχρεωτικόΑναλυτής εγγράφων ως ουδέτερος κωδικός:
document(πλήρης δομή: σελίδες, τίτλοι, πίνακες, σαρωμένες σελίδες),pdf(το επίπεδο κειμένου του PDF),docx,xlsx,csv,markdown,html,text. Η λίστα μπορεί να επεκταθεί.sensitivebooleanυποχρεωτικόsha256string | nullυποχρεωτικόsizeintegerυποχρεωτικόsnoozed_atstring (date-time) | nullsnoozed_byinteger | nullsnoozed_untilstring | nullsource_changedbooleanυποχρεωτικόsource_pathstring | nullυποχρεωτικόsource_urlstring | nullυποχρεωτικόstatusstringυποχρεωτικόΕπιτρεπόμενες τιμές:
processingreadyerrorarchivedtablesarray of CardTabletagsarray of stringυποχρεωτικόtitlestringυποχρεωτικόtrustnumberυποχρεωτικόtrust_if_verifiednumberupdated_atstring (date-time)υποχρεωτικόverified_atstring (date-time) | nullυποχρεωτικόverified_byinteger | nullυποχρεωτικόverified_by_namestring | nullverifier_idsarray of integerυποχρεωτικόverifiersarray of objectΠεδία
activebooleanυποχρεωτικόidintegerυποχρεωτικόnamestringυποχρεωτικό
verify_interval_daysintegerυποχρεωτικόversionintegerυποχρεωτικόversionsarray of CardVersionsource_archiveArchiveSourcecreated_byinteger | nullmanual_optionsobjectΧειροκίνητες ρυθμίσεις ανάλυσης εγγράφου (προεπισκόπηση).
doc_kindDocKind | nullΤύπος εγγράφου.
null, αν ο τύπος δεν έχει προσδιοριστεί (για παράδειγμα, για κάρτες που ευρετηριάστηκαν πριν από την εισαγωγή των τύπων εγγράφων).doc_kind_confidencenumber | nullΒαθμός βεβαιότητας για τον τύπο του εγγράφου, από 0 έως 1.
doc_kind_sourcestring | nullΤι προσδιόρισε τον τύπο: κανόνες (
rules), ένας χρήστης (manual) ή αυτόματη ταξινόμηση. Η λίστα μπορεί να επεκταθεί: θεωρήστε μια άγνωστη τιμή αυτόματη ταξινόμηση.Επιτρεπόμενες τιμές:
rulesmanualnullinvoiceDocInvoiceExtraction | nullΠεδία τιμολογίου, πιστωτικού τιμολογίου ή απόδειξης (μόνο για αυτούς τους τύπους και μόνο στην κάρτα, όχι στη λίστα).
null, αν δεν έχετε πρόσβαση σε ολόκληρο το έγγραφο, επειδή τα πεδία εξάγονται από ολόκληρο το έγγραφο.warningsarray of ReviewWarningΠροειδοποιήσεις της ανάλυσης του εγγράφου (
ReviewWarning· μόνο στην κάρτα, όχι στη λίστα).enrichmentCardEnrichmentStatus | nullΚατάσταση εμπλουτισμού (μόνο στην κάρτα, όχι στη λίστα). Ο τύπος του εγγράφου, τα πεδία του τιμολογίου και οι οικονομικές εγγραφές προστίθενται στο παρασκήνιο μετά την ευρετηρίαση και μπορούν να υπολογιστούν ξανά αργότερα· εμφανίζονται στην κάρτα, όταν είναι έτοιμα.
nullσημαίνει ότι δεν υπάρχει διαθέσιμη κατάσταση (η κάρτα ευρετηριάστηκε χωρίς εμπλουτισμό στο παρασκήνιο).external_idstring | nullID της κάρτας στο σύστημά σας. Είναι μοναδικό στον οργανισμό μεταξύ των καρτών που δεν προέρχονται από πηγές·
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
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
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
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
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
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.code, εκτός από τους γενικούς κωδικούς κάθε αιτήματος.
- 400api.expand_invalid
- 400api.metadata_invalid
- 401auth.not_authenticated
- 403auth.system_scope
- 400cards.invalid_folder_filter
- 400cards.invalid_kind_filter
- 400cards.invalid_order
- 400cards.invalid_owner_filter
- 400cards.invalid_sort
- 400cards.invalid_status_filter
- 400cards.invalid_type_filter
- 400cards.invalid_verification_filter
- 400categories.unknown
- 403collections.no_access
- 404collections.not_found
- 404folders.not_found
- 403org.deleted
- 403org.suspended
- 403view_as.read_only
Όρια ρυθμού
Οι αποκρίσεις περιέχουν τις κεφαλίδες RateLimit και RateLimit-Policy, καθώς και τις παλαιότερες X-RateLimit-Limit, X-RateLimit-Remaining και X-RateLimit-Reset. Μια απόκριση 429 έχει την κεφαλίδα Retry-After σε δευτερόλεπτα: περιμένετε και επαναλάβετε το αίτημα.