Ir al contenido
Sursa Developers

GET/v1/cards

Listar tarjetas

list_cards

Devuelve tarjetas con filtros, ordenación y paginación. Con preview=1 (para la vista de mosaico), cada tarjeta incluye además preview (los primeros 200 caracteres del texto) y preview_tables (hojas con su número de filas), dentro de su perfil de datos.

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de consulta

  • collectionstring | null
  • folderstring | null

    <folder ID> devuelve las tarjetas de la carpeta y de todas sus subcarpetas. none devuelve las tarjetas de la colección que no están en ninguna carpeta y requiere collection (de lo contrario, 400 cards.invalid_folder_filter). Si la carpeta no existe o no es visible para usted, la solicitud devuelve 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valores permitidos: processingreadyerrorarchivedall

  • ownerstring | null

    me, none o un ID de usuario.

  • owner_idinteger | null
  • verificationstring | null

    Valores permitidos: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table devuelve las tarjetas con tablas de hechos; text, las tarjetas sin ellas.

    Valores permitidos: tabletext

  • tagsstring | null

    Etiquetas separadas por comas (una tarjeta debe tenerlas todas).

  • idsstring | null

    ID de tarjeta separados por comas.

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

    Predeterminado: "created_at"

  • orderstring

    Valores permitidos: ascdesc

    Predeterminado: "desc"

  • limitinteger

    Predeterminado: 200

  • offsetinteger

    Predeterminado: 0

  • previewboolean

    true añade preview (los primeros 200 caracteres) y preview_tables para la vista de mosaico.

    Predeterminado: false

  • updated_sincestring (date-time)

    Solo las tarjetas con updated_at igual o posterior a este momento (RFC 3339 con desfase horario), para la sincronización. Sin sort y order explícitos, la lista se ordena por updated_at ascendente y después por id. Las tarjetas eliminadas no aparecen en la lista: las eliminaciones llegan como eventos.

  • metadatamap of string

    Filtro por metadata: metadata[<key>]=<value> busca una coincidencia exacta. Hasta 3 condiciones, y deben cumplirse todas (?metadata[team]=support&metadata[crm_id]=A-1042). Más de 3 condiciones o una clave no válida devuelven 400 api.metadata_invalid.

  • collection_idinteger

    Colección por ID. Si también se pasa collection, prevalece collection_id. Una colección que no existe en la organización o no es visible devuelve 404 collections.not_found.

  • external_idstring

    Solo la tarjeta con este external_id.

  • cursorstring

    Cursor de la página siguiente, tomado de X-Next-Cursor o de next_cursor de la respuesta anterior con los mismos filtros; incluye el tamaño de página. Junto con offset: 422 validation.failed; un cursor de otra lista, de otros filtros o mal formado: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Objetos relacionados que se incluyen en la respuesta (desde 1.62.0): una ruta de la lista x-expandable de la operación. Repita el parámetro hasta 10 veces. Una ruta tiene hasta 2 segmentos separados por un punto (collection.default_owner). En una lista, la ruta empieza por data. y se aplica a todos los elementos de la página (expand[]=data.owner). Un objeto expandido va al objeto expanded del elemento, y el campo de ID se mantiene. Un objeto que quien llama a la API no puede ver según las comprobaciones de su propia operación de lectura se expande como null. Una ruta desconocida, más de 10 rutas o una ruta con más de 2 segmentos devuelven 400 api.expand_invalid.

    items ≤ 10

Parámetros de encabezado

  • X-View-Asstring

    Solo para claves de API con el rol admin. Ejecuta la solicitud como el perfil de datos <profile>[:viewer|verifier|editor], por ejemplo employee:viewer. La clave de instalación no puede usar este encabezado (403).

Parámetros de cookie

  • kb_view_asstring

    Cookie del modo «View as» para una sesión. POST /auth/view-as la establece y DELETE /auth/view-as la elimina.

Respuestas

200Respuesta correcta

Encabezados de la respuesta

  • Link

    Dirección de la página siguiente, <…>; rel="next". Si no hay encabezado, es la última página.

  • X-Next-Cursor

    Cursor de la página siguiente para el parámetro cursor. Si no hay encabezado, es la última página.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Valores permitidos: wholepartial

  • access_contactstring

    A quién dirigirse para obtener acceso (solo cuando access=partial).

  • aclobject
    Campos
    • verifybooleanobligatorio
    • writebooleanobligatorio
  • categorystringobligatorio
  • category_confidencenumber | nullobligatorio
  • category_lockedbooleanobligatorio
  • category_reviewbooleanobligatorio
  • category_sourceCategorySource | nullobligatorio
  • collectionstringobligatorio
  • collection_idintegerobligatorio
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Contenido del editor de la última versión publicada. El campo puede no aparecer; en ese caso, obtenga el contenido del editor a partir de un borrador (POST /v1/drafts con card_id).

  • editing_lockEditingLock | null

    Bloqueo de edición activo. El campo puede no aparecer; en ese caso, el editor sabe quién tiene el bloqueo por la respuesta 409 cards.locked de POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligatorio
  • days_since_verifiedintegerobligatorio
  • errorstring | nullobligatorio
  • eventsarray of CardEvent
  • feedback_negintegerobligatorio
  • feedback_posintegerobligatorio
  • foldersarray of CardFolderRef

    Solo en la lista de tarjetas: las carpetas que contienen la tarjeta (las que el usuario puede ver), con sus rutas desde la raíz de la colección. Una lista vacía significa que la tarjeta no está en ninguna carpeta.

  • has_tablesboolean

    Solo en la lista de tarjetas.

  • hidden_partsboolean
  • idstringobligatorio
  • jobJob | null
  • kindCardKindobligatorio
  • org_idintegerobligatorio
  • owner_activeboolean | null
  • owner_idinteger | nullobligatorio
  • owner_namestring | nullobligatorio
  • pagesinteger | nullobligatorio
  • parserstring | nullobligatorio

    Analizador del documento como código neutro: document (estructura completa: páginas, títulos, tablas, páginas escaneadas), pdf (la capa de texto del PDF), docx, xlsx, csv, markdown, html, text. La lista puede ampliarse.

  • partsarray of CardPartobligatorio
  • sensitivebooleanobligatorio
  • sha256string | nullobligatorio
  • sizeintegerobligatorio
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligatorio
  • source_pathstring | nullobligatorio
  • source_urlstring | nullobligatorio
  • statusstringobligatorio

    Valores permitidos: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligatorio
  • titlestringobligatorio
  • trustnumberobligatorio
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligatorio
  • updated_atstring (date-time)obligatorio
  • verificationVerificationobligatorio
  • verified_atstring (date-time) | nullobligatorio
  • verified_byinteger | nullobligatorio
  • verified_by_namestring | null
  • verifier_idsarray of integerobligatorio
  • verifiersarray of object
    Campos
    • activebooleanobligatorio
    • idintegerobligatorio
    • namestringobligatorio
  • verify_interval_daysintegerobligatorio
  • versionintegerobligatorio
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Configuración manual del análisis (vista previa).

  • doc_kindDocKind | null

    Tipo de documento. null si el tipo no está determinado (por ejemplo, en las tarjetas indexadas antes de que existieran los tipos de documento).

  • doc_kind_confidencenumber | null

    Grado de certeza del tipo de documento, de 0 a 1.

  • doc_kind_sourcestring | null

    Qué determinó el tipo: reglas (rules), un usuario (manual) o la clasificación automática. La lista puede ampliarse: trate un valor desconocido como clasificación automática.

    Valores permitidos: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Campos de una factura, una nota de crédito o un recibo (solo para estos tipos, y solo en la tarjeta, no en la lista). null si no tiene acceso a todo el documento, porque los campos se extraen del documento completo.

  • warningsarray of ReviewWarning

    Advertencias del análisis del documento (ReviewWarning; solo en la tarjeta, no en la lista).

  • enrichmentCardEnrichmentStatus | null

    Estado del enriquecimiento (solo en la tarjeta, no en la lista). El tipo de documento, los campos de la factura y los registros financieros se añaden en segundo plano después de la indexación y pueden recalcularse más tarde; aparecen en la tarjeta cuando están listos. null significa que no hay estado disponible (la tarjeta se indexó sin enriquecimiento en segundo plano).

  • external_idstring | null

    ID de la tarjeta en el sistema del integrador. Es único en la organización entre las tarjetas que no proceden de fuentes; null significa que no está definido. /v1/cards-by-external-id/{external_id} lee y sustituye la tarjeta a partir de él.

    length ≤ 512

  • metadataMetadata
400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

404El objeto no existe o no está disponible para usted. La API no confirma la existencia de un objeto restringido.

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

  • Retry-After

    Número de segundos que hay que esperar antes de reintentar la solicitud.

  • RateLimit-Policy

    Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.

  • RateLimit

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

  • X-RateLimit-Limit

    Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).

  • X-RateLimit-Remaining

    Solicitudes restantes del límite más estricto.

  • X-RateLimit-Reset

    Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← cards · Referencia de la API