Vai al contenuto
Sursa Developers

GET/v1/cards

Elencare le schede

list_cards

Restituisce le schede con filtri, ordinamento e paginazione. Con preview=1 (per la vista a riquadri) ogni scheda ha anche preview (i primi 200 caratteri del testo) e preview_tables (i fogli con il numero delle loro righe), entro i limiti del tuo profilo dati.

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di query

  • collectionstring | null
  • folderstring | null

    <folder ID> restituisce le schede della cartella e di tutte le sue sottocartelle. none restituisce le schede della raccolta che non sono in nessuna cartella e richiede collection (altrimenti 400 cards.invalid_folder_filter). Se la cartella non esiste o non è visibile per te, la richiesta restituisce 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valori ammessi: processingreadyerrorarchivedall

  • ownerstring | null

    me, none o l’ID di un utente.

  • owner_idinteger | null
  • verificationstring | null

    Valori ammessi: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table restituisce le schede con tabelle dei fatti, text quelle senza.

    Valori ammessi: tabletext

  • tagsstring | null

    Tag separati da virgole (una scheda deve averli tutti).

  • idsstring | null

    ID delle schede separati da virgole.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Predefinito: "created_at"

  • orderstring

    Valori ammessi: ascdesc

    Predefinito: "desc"

  • limitinteger

    Predefinito: 200

  • offsetinteger

    Predefinito: 0

  • previewboolean

    true aggiunge preview (i primi 200 caratteri) e preview_tables per la vista a riquadri.

    Predefinito: false

  • updated_sincestring (date-time)

    Solo le schede con updated_at uguale o successivo a questo momento (RFC 3339 con offset), per la sincronizzazione. Senza sort e order espliciti, l’elenco è ordinato per updated_at crescente, poi per id. Le schede eliminate non compaiono nell’elenco: le eliminazioni arrivano come eventi.

  • metadatamap of string

    Filtro per metadata: metadata[<key>]=<value> corrisponde in modo esatto. Fino a 3 condizioni, che devono essere soddisfatte tutte (?metadata[team]=support&metadata[crm_id]=A-1042). Più di 3 condizioni o una chiave non valida restituiscono 400 api.metadata_invalid.

  • collection_idinteger

    Raccolta per ID. Se viene passato anche collection, prevale collection_id. Una raccolta che non esiste nell’organizzazione o non è visibile restituisce 404 collections.not_found.

  • external_idstring

    Solo la scheda con questo external_id.

  • cursorstring

    Cursore della pagina successiva, preso da X-Next-Cursor o da next_cursor della risposta precedente con gli stessi filtri; contiene la dimensione della pagina. Insieme a offset: 422 validation.failed; un cursore di un altro elenco, con altri filtri o malformato: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Oggetti correlati da includere nella risposta (dalla 1.62.0): un percorso dell’elenco x-expandable dell’operazione. Ripeti il parametro fino a 10 volte. Un percorso ha fino a 2 segmenti separati da un punto (collection.default_owner). In un elenco, il percorso inizia con data. e si applica a ogni elemento della pagina (expand[]=data.owner). Un oggetto espanso va nell’oggetto expanded dell’elemento, e il campo con l’ID resta. Un oggetto che chi effettua la chiamata non può vedere secondo i controlli della sua operazione di lettura viene espanso come null. Un percorso sconosciuto, più di 10 percorsi o un percorso con più di 2 segmenti restituiscono 400 api.expand_invalid.

    items ≤ 10

Parametri di intestazione

  • X-View-Asstring

    Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

  • kb_view_asstring

    Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Risposte

200Risposta riuscita

Intestazioni della risposta

  • Link

    Indirizzo della pagina successiva, <…>; rel="next". Se l’intestazione manca, questa è l’ultima pagina.

  • X-Next-Cursor

    Cursore della pagina successiva per il parametro cursor. Se l’intestazione manca, questa è l’ultima pagina.

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Valori ammessi: wholepartial

  • access_contactstring

    Chi contattare per l’accesso (solo quando access=partial).

  • aclobject
    Campi
    • verifybooleanobbligatorio
    • writebooleanobbligatorio
  • categorystringobbligatorio
  • category_confidencenumber | nullobbligatorio
  • category_lockedbooleanobbligatorio
  • category_reviewbooleanobbligatorio
  • category_sourceCategorySource | nullobbligatorio
  • collectionstringobbligatorio
  • collection_idintegerobbligatorio
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Contenuto dell’editor dell’ultima versione pubblicata. Il campo può essere assente; in tal caso, ottieni il contenuto dell’editor da una bozza (POST /v1/drafts con card_id).

  • editing_lockEditingLock | null

    Blocco di modifica attivo. Il campo può essere assente; in tal caso, l’editor scopre chi detiene il blocco dalla risposta 409 cards.locked di POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obbligatorio
  • days_since_verifiedintegerobbligatorio
  • errorstring | nullobbligatorio
  • eventsarray of CardEvent
  • feedback_negintegerobbligatorio
  • feedback_posintegerobbligatorio
  • foldersarray of CardFolderRef

    Solo nell’elenco delle schede: le cartelle che contengono la scheda (quelle visibili all’utente), con i loro percorsi dalla radice della raccolta. Un elenco vuoto indica che la scheda non è in nessuna cartella.

  • has_tablesboolean

    Solo nell’elenco delle schede.

  • hidden_partsboolean
  • idstringobbligatorio
  • jobJob | null
  • kindCardKindobbligatorio
  • org_idintegerobbligatorio
  • owner_activeboolean | null
  • owner_idinteger | nullobbligatorio
  • owner_namestring | nullobbligatorio
  • pagesinteger | nullobbligatorio
  • parserstring | nullobbligatorio

    Metodo di analisi del documento come codice neutro: document (struttura completa: pagine, titoli, tabelle, pagine scansionate), pdf (il livello di testo del PDF), docx, xlsx, csv, markdown, html, text. L’elenco può crescere.

  • partsarray of CardPartobbligatorio
  • sensitivebooleanobbligatorio
  • sha256string | nullobbligatorio
  • sizeintegerobbligatorio
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobbligatorio
  • source_pathstring | nullobbligatorio
  • source_urlstring | nullobbligatorio
  • statusstringobbligatorio

    Valori ammessi: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobbligatorio
  • titlestringobbligatorio
  • trustnumberobbligatorio
  • trust_if_verifiednumber
  • trust_partsTrustPartsobbligatorio
  • updated_atstring (date-time)obbligatorio
  • verificationVerificationobbligatorio
  • verified_atstring (date-time) | nullobbligatorio
  • verified_byinteger | nullobbligatorio
  • verified_by_namestring | null
  • verifier_idsarray of integerobbligatorio
  • verifiersarray of object
    Campi
    • activebooleanobbligatorio
    • idintegerobbligatorio
    • namestringobbligatorio
  • verify_interval_daysintegerobbligatorio
  • versionintegerobbligatorio
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Impostazioni manuali dell’analisi del documento (anteprima).

  • doc_kindDocKind | null

    Tipo di documento. null se il tipo non è determinato (ad esempio, per le schede indicizzate prima dell’introduzione dei tipi di documento).

  • doc_kind_confidencenumber | null

    Livello di confidenza nel tipo di documento, da 0 a 1.

  • doc_kind_sourcestring | null

    Che cosa ha determinato il tipo: regole (rules), un utente (manual) o la classificazione automatica. L’elenco può crescere: tratta un valore sconosciuto come classificazione automatica.

    Valori ammessi: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Campi di una fattura, nota di credito o ricevuta (solo per questi tipi, e solo nella scheda, non nell’elenco). null se non hai accesso all’intero documento, perché i campi vengono estratti dall’intero documento.

  • warningsarray of ReviewWarning

    Avvisi dell’analisi del documento (ReviewWarning; solo nella scheda, non nell’elenco).

  • enrichmentCardEnrichmentStatus | null

    Stato dell’arricchimento (solo nella scheda, non nell’elenco). Il tipo di documento, i campi della fattura e i dati finanziari vengono aggiunti in background dopo l’indicizzazione e possono essere ricalcolati in seguito; compaiono nella scheda quando sono pronti. null indica che non è disponibile alcuno stato (la scheda è stata indicizzata senza arricchimento in background).

  • external_idstring | null

    ID della scheda nel sistema dell’integratore. È univoco nell’organizzazione tra le schede che non provengono da fonti; null indica che non è impostato. /v1/cards-by-external-id/{external_id} legge e sostituisce la scheda tramite questo ID.

    length ≤ 512

  • metadataMetadata
400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

  • Retry-After

    Numero di secondi da attendere prima di ripetere la richiesta.

  • RateLimit-Policy

    Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.

  • RateLimit

    Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).

  • X-RateLimit-Remaining

    Richieste rimanenti nel limite più restrittivo.

  • X-RateLimit-Reset

    Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← cards · Riferimento API