Anar al contingut
Sursa Developers

GET/v1/cards

Llistar les entrades

list_cards

Retorna entrades amb filtres, ordenació i paginació. Amb preview=1 (per a la vista de mosaic), cada entrada també té preview (els primers 200 caràcters del text) i preview_tables (els fulls amb el seu nombre de files), dins del vostre perfil de dades.

Autenticació

Envieu una clau d’API a la capçalera Authorization: Authorization: Bearer <clau>.

Paràmetres de consulta

  • collectionstring | null
  • folderstring | null

    <folder ID> retorna les entrades de la carpeta i de totes les seves subcarpetes. none retorna les entrades de la col·lecció que no són a cap carpeta i requereix collection (si no, 400 cards.invalid_folder_filter). Si la carpeta no existeix o no és visible per a vós, la sol·licitud retorna 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valors permesos: processingreadyerrorarchivedall

  • ownerstring | null

    me, none o l’ID d’un usuari.

  • owner_idinteger | null
  • verificationstring | null

    Valors permesos: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table retorna les entrades amb taules de fets; text, les que no en tenen.

    Valors permesos: tabletext

  • tagsstring | null

    Etiquetes separades per comes (una entrada les ha de tenir totes).

  • idsstring | null

    ID d’entrades separats per comes.

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

    Per defecte: "created_at"

  • orderstring

    Valors permesos: ascdesc

    Per defecte: "desc"

  • limitinteger

    Per defecte: 200

  • offsetinteger

    Per defecte: 0

  • previewboolean

    true afegeix preview (els primers 200 caràcters) i preview_tables per a la vista de mosaic.

    Per defecte: false

  • updated_sincestring (date-time)

    Només les entrades amb updated_at igual o posterior a aquest moment (RFC 3339 amb desplaçament horari), per a la sincronització. Sense sort i order explícits, la llista s’ordena per updated_at en ordre ascendent i després per id. Les entrades eliminades no es llisten: les eliminacions arriben com a esdeveniments.

  • metadatamap of string

    Filtre per metadata: metadata[<key>]=<value> coincideix exactament. Fins a 3 condicions, i s’han de complir totes (?metadata[team]=support&metadata[crm_id]=A-1042). Més de 3 condicions o una clau no vàlida retornen 400 api.metadata_invalid.

  • collection_idinteger

    Col·lecció per ID. Quan també es passa collection, preval collection_id. Una col·lecció que no existeix a l’organització o que no és visible retorna 404 collections.not_found.

  • external_idstring

    Només l’entrada amb aquest external_id.

  • cursorstring

    Cursor de la pàgina següent, de X-Next-Cursor o del next_cursor de la resposta anterior amb els mateixos filtres; porta la mida de pàgina. Juntament amb offset: 422 validation.failed; un cursor d’una altra llista, d’altres filtres o mal format: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Objectes relacionats que s’inclouen a la resposta (des de la versió 1.62.0): un camí de la llista x-expandable de l’operació. Repetiu el paràmetre fins a 10 vegades. Un camí té fins a 2 segments separats per un punt (collection.default_owner). En una llista, el camí comença amb data. i s’aplica a cada element de la pàgina (expand[]=data.owner). Un objecte expandit va a l’objecte expanded de l’element, i el camp d’ID es manté. Un objecte que qui fa la crida no pot veure segons les comprovacions de la seva pròpia operació de lectura s’expandeix com a null. Un camí desconegut, més de 10 camins o un camí de més de 2 segments retorna 400 api.expand_invalid.

    items ≤ 10

Paràmetres de capçalera

  • X-View-Asstring

    Només per a claus d’API amb el rol admin. Fa la sol·licitud com el perfil de dades <profile>[:viewer|verifier|editor], per exemple employee:viewer. La clau d’instal·lació no pot fer servir aquesta capçalera (403).

Paràmetres de galeta

  • kb_view_asstring

    Galeta del mode «View as» per a una sessió. POST /auth/view-as l’estableix i DELETE /auth/view-as l’esborra.

Respostes

200Resposta correcta

Capçaleres de la resposta

  • Link

    Adreça de la pàgina següent, <…>; rel="next". Si no hi ha capçalera, aquesta és l’última pàgina.

  • X-Next-Cursor

    Cursor de la pàgina següent per al paràmetre cursor. Si no hi ha capçalera, aquesta és l’última pàgina.

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Valors permesos: wholepartial

  • access_contactstring

    Persona a qui cal adreçar-se per obtenir accés (només quan access=partial).

  • aclobject
    Camps
    • verifybooleanobligatori
    • writebooleanobligatori
  • categorystringobligatori
  • category_confidencenumber | nullobligatori
  • category_lockedbooleanobligatori
  • category_reviewbooleanobligatori
  • category_sourceCategorySource | nullobligatori
  • collectionstringobligatori
  • collection_idintegerobligatori
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Contingut de l’editor de l’última versió publicada. El camp pot no ser-hi; en aquest cas, obteniu el contingut de l’editor d’un esborrany (POST /v1/drafts amb card_id).

  • editing_lockEditingLock | null

    Bloqueig d’edició actiu. El camp pot no ser-hi; en aquest cas, l’editor sap qui té el bloqueig per la resposta 409 cards.locked de POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligatori
  • days_since_verifiedintegerobligatori
  • errorstring | nullobligatori
  • eventsarray of CardEvent
  • feedback_negintegerobligatori
  • feedback_posintegerobligatori
  • foldersarray of CardFolderRef

    Només a la llista d’entrades: les carpetes que contenen l’entrada (les que l’usuari pot veure), amb els seus camins des de l’arrel de la col·lecció. Una llista buida vol dir que l’entrada no és a cap carpeta.

  • has_tablesboolean

    Només a la llista d’entrades.

  • hidden_partsboolean
  • idstringobligatori
  • jobJob | null
  • kindCardKindobligatori
  • org_idintegerobligatori
  • owner_activeboolean | null
  • owner_idinteger | nullobligatori
  • owner_namestring | nullobligatori
  • pagesinteger | nullobligatori
  • parserstring | nullobligatori

    Analitzador del document com a codi neutre: document (estructura completa: pàgines, títols, taules, pàgines escanejades), pdf (la capa de text del PDF), docx, xlsx, csv, markdown, html, text. La llista pot créixer.

  • partsarray of CardPartobligatori
  • sensitivebooleanobligatori
  • sha256string | nullobligatori
  • sizeintegerobligatori
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligatori
  • source_pathstring | nullobligatori
  • source_urlstring | nullobligatori
  • statusstringobligatori

    Valors permesos: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligatori
  • titlestringobligatori
  • trustnumberobligatori
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligatori
  • updated_atstring (date-time)obligatori
  • verificationVerificationobligatori
  • verified_atstring (date-time) | nullobligatori
  • verified_byinteger | nullobligatori
  • verified_by_namestring | null
  • verifier_idsarray of integerobligatori
  • verifiersarray of object
    Camps
    • activebooleanobligatori
    • idintegerobligatori
    • namestringobligatori
  • verify_interval_daysintegerobligatori
  • versionintegerobligatori
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Configuració manual de l’anàlisi (previsualització).

  • doc_kindDocKind | null

    Tipus de document. null si el tipus no s’ha determinat (per exemple, en entrades indexades abans que s’introduïssin els tipus de document).

  • doc_kind_confidencenumber | null

    Grau de certesa del tipus de document, de 0 a 1.

  • doc_kind_sourcestring | null

    Què ha determinat el tipus: regles (rules), un usuari (manual) o la classificació automàtica. La llista pot créixer: tracteu un valor desconegut com a classificació automàtica.

    Valors permesos: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Camps d’una factura, una nota d’abonament o un rebut (només per a aquests tipus, i només a l’entrada, no a la llista). null si no teniu accés a tot el document, perquè els camps s’extreuen del document sencer.

  • warningsarray of ReviewWarning

    Avisos de l’anàlisi del document (ReviewWarning; només a l’entrada, no a la llista).

  • enrichmentCardEnrichmentStatus | null

    Estat de l’enriquiment (només a l’entrada, no a la llista). El tipus de document, els camps de la factura i els registres financers s’afegeixen en segon pla després de la indexació i es poden tornar a calcular més endavant; apareixen a l’entrada quan estan llestos. null vol dir que no hi ha cap estat disponible (l’entrada es va indexar sense enriquiment en segon pla).

  • external_idstring | null

    ID de l’entrada al sistema de l’integrador. És únic a l’organització entre les entrades que no provenen de fonts; null vol dir que no està definit. /v1/cards-by-external-id/{external_id} llegeix i substitueix l’entrada a partir d’aquest ID.

    length ≤ 512

  • metadataMetadata
400La sol·licitud no és vàlida: el valor d’un paràmetre o l’estat de l’objecte no permeten l’acció (`detail` és un missatge).

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

401No s’han enviat credencials (ni una galeta de sessió ni una clau d’API), o no s’ha trobat la clau.

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

403L’acció no està permesa: el rol és insuficient, no hi ha accés a la col·lecció o a l’entrada, la sol·licitud s’executa en mode «View as», o l’organització està suspesa o eliminada (`detail` és un objecte amb `code: org_suspended | org_deleted`).

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

404L’objecte no existeix o no està disponible per a vós. L’API no confirma que existeixi un objecte restringit.

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

422Error de validació: el cos o els paràmetres no coincideixen amb l’esquema (`detail` és una llista d’errors de validació), o el valor d’un paràmetre és fora de l’interval permès (`detail` és un missatge).

Capçaleres de la resposta

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

429Massa sol·licituds (`api.rate_limited`), s’ha esgotat la quota de l’organització per al minut, el dia o el mes (`api.quota_exceeded`; `error.details` conté `quota`, `limit` i `reset_at`), s’ha arribat al límit de l’organització o el servei de respostes està ocupat (`answers.engine_busy`). Espereu el temps que indica la capçalera `Retry-After`.

Capçaleres de la resposta

  • Retry-After

    Nombre de segons que cal esperar abans de reintentar la sol·licitud.

  • RateLimit-Policy

    Límits vigents, en el format de l’esborrany de l’IETF draft-ietf-httpapi-ratelimit-headers: elements separats per comes "<name>";q=<quota>;w=<window in seconds>. key és la freqüència de sol·licituds de la clau d’API (la quota és la ràfega, la finestra és el temps que triga a reomplir-se del tot; per a una sessió és user, sense credencials ip); minute, day i month són les quotes de l’organització per al minut, el dia i el mes naturals en UTC.

  • RateLimit

    El que queda de cada límit de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Límit de l’element més restrictiu de RateLimit-Policy (el que té menys sol·licituds restants).

  • X-RateLimit-Remaining

    Sol·licituds restants dins del límit més restrictiu.

  • X-RateLimit-Reset

    Segons que falten perquè es restableixi el límit més restrictiu.

application/json

Objecte: Error

Codis d’error

Codis que aquest punt final pot retornar a error.code, a més dels codis generals de totes les sol·licituds.

Límits de freqüència

Les respostes porten les capçaleres RateLimit i RateLimit-Policy i les anteriors X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta 429 té Retry-After en segons: espereu i torneu-ho a provar.

← cards · Referència de l’API