POST/v1/cards/archive

Subir un archivo comprimido de documentos

upload_card_archive

Envíe un archivo comprimido ZIP en el campo file de un formulario multipart/form-data. Cada archivo compatible que contiene se convierte en un documento independiente, igual que en las subidas individuales (POST /v1/cards). Los contenedores de firma ASiC (.asice, .sce, .bdoc, .asics) también son archivos comprimidos: sus archivos de datos se convierten en documentos, META-INF/ se omite y la firma no se verifica. Los campos del formulario son los mismos que para la subida de un archivo (colección, etiquetas, responsable, categoría, confidencialidad), sin vista previa.

El archivo comprimido se comprueba por su firma (un documento de Office renombrado no cuenta como archivo comprimido y devuelve 415 files.type_mismatch), se aplica el límite de subida de la instalación y el análisis antivirus abarca todo el archivo comprimido.

La lista de contenido se comprueba de forma síncrona. La respuesta contiene el plan (qué archivos se convierten en documentos, cuáles se omiten y por qué) y el trabajo de extracción (job_id, batch_id). El trabajo abre los archivos comprimidos anidados (hasta 3 niveles de forma predeterminada), comprueba cada documento por su firma y con el antivirus, y lo pone en cola para la indexación normal con el mismo batch_id (progreso de los documentos: GET /v1/jobs?batch=). El resultado está disponible en GET /v1/archives/{job_id}.

Límites (valores predeterminados de la instalación): hasta 1000 archivos en todo el árbol (si hay más, se devuelve 413 cards.archive_too_many_files), hasta 2048 MB descomprimidos (si se superan, 413 cards.archive_too_large) y no más que el almacenamiento restante de la organización según su plan (402 limits.storage), el límite de subida por archivo para cada archivo interno y una tasa de compresión de como máximo 100:1 por entrada. Las entradas con «..», una ruta absoluta o una letra de unidad, los enlaces simbólicos, las entradas cifradas y los formatos no compatibles se omiten con un motivo (skipped[].reason). Los archivos del sistema operativo, los directorios y los archivos vacíos se omiten sin aviso (ignored). Los nombres que no están en UTF-8 se leen como cp866 o cp1251. Un archivo que no es un ZIP devuelve 400 cards.archive_invalid; un archivo comprimido cifrado por completo, 400 cards.archive_encrypted, y un archivo comprimido sin ningún documento, 400 cards.archive_empty.

Cada documento recuerda su archivo comprimido: CardVersion.archive y Card.source_archive (la tarjeta muestra el archivo comprimido de su versión actual).

En lugar del formulario, puede enviar un cuerpo application/json (ArchiveUploadFromUpload, desde 1.62.0): el archivo comprimido es una subida por partes ya lista upload_id (con la finalidad archive), los campos son los mismos que en el formulario y tags es una lista de cadenas. El archivo comprimido ya se comprobó en complete, y el límite de tamaño es el de la subida por partes en lugar del de la subida en una sola solicitud. La subida se usa una sola vez, en la misma transacción que pone en cola el trabajo de extracción; los códigos de error de la subida son los mismos que para POST /v1/cards.

Autenticación

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

Parámetros de encabezado

Idempotency-Keystring
Clave para reintentar de forma segura una escritura: de 1 a 255 caracteres ASCII imprimibles; se recomienda un UUID v4 por operación lógica. Un reintento con la misma clave en un plazo de 24 horas no vuelve a ejecutar la operación: devuelve la respuesta guardada (estado, encabezados y cuerpo) con el encabezado Idempotency-Replayed: true. La misma clave con otro método, otra ruta, otro Content-Type u otro cuerpo devuelve 409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso, 409 api.idempotency_in_progress con Retry-After: 1. Tras una respuesta 5xx o 429, la clave se libera y un reintento vuelve a ejecutar la operación. La clave se aplica a la organización y a quien llama a la API (clave de API, usuario o clave de fuente personalizada).
length ≥ 1, length ≤ 255
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.

Cuerpo de la solicitud

multipart/form-data

Objeto: ArchiveUploadForm

filestring (application/zip)obligatorio
collectionstring
Predeterminado: "default"
tagsstring
Predeterminado: ""
forceboolean
Predeterminado: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Carpeta de collection en la que se colocan todos los documentos del archivo comprimido. Una carpeta de otra colección devuelve 400 folders.card_collection_mismatch, una carpeta inexistente devuelve 404 folders.not_found, y la falta del permiso COLLECTION_EDIT_CARDS sobre la carpeta devuelve 403 authz.forbidden. La comprobación se hace antes de guardar el archivo comprimido. Los duplicados de archivos ya subidos no se mueven a la carpeta.
length ≤ 64
collection_idinteger | null
Colección por ID. Cuando también se envía collection, prevalece collection_id. Una colección que no existe en la organización o no es visible devuelve 404 collections.not_found.

application/json

Objeto: ArchiveUploadFromUpload

upload_idstringobligatorio
Una subida lista (ready) con la finalidad archive; se usa una sola vez.
collectionstring
Predeterminado: "default"
collection_idinteger | null
Colección por ID. Si también se pasa collection, prevalece collection_id. Una colección que no existe en la organización, no es visible o está fuera de las colecciones de la clave devuelve 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Predeterminado: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Respuestas

200Plan de extracción y trabajo

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.
Idempotency-Replayed
true significa que la respuesta se reprodujo a partir de la guardada para esta Idempotency-Key: la operación no se volvió a ejecutar.

application/json

Objeto: ArchiveUploadResult

job_idintegerobligatorio
batch_idstringobligatorio
Lote de trabajos de indexación de los documentos del archivo comprimido (GET /v1/jobs?batch=).
statusstringobligatorio
Valores permitidos: queued
archiveArchiveInfoobligatorio
plannedarray of stringobligatorio
Rutas de los archivos de todos los niveles que se convertirán en documentos, incluidos los archivos de los archivos comprimidos anidados (b.zip/c.pdf).
documentsintegerobligatorio
Número de documentos de todos los niveles, incluidos los archivos de los archivos comprimidos anidados. El resultado de la extracción suma el mismo número: creados + duplicados + rechazados por la comprobación del contenido (ArchiveJob).
nested_archivesintegerobligatorio
skippedarray of ArchiveSkipobligatorio
ignoredintegerobligatorio
Entradas del sistema (archivos del sistema operativo, directorios, archivos vacíos, firmas del contenedor).

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

402La organización ha alcanzado un límite del plan (tarjetas, almacenamiento o usuarios). `error.details` contiene `kind`, `limit` y `used`.

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

409El estado del objeto no permite la acción, por ejemplo, un duplicado, una indexación en curso o un trabajo ya procesado.

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

410El objeto existió, pero ya no está disponible: el enlace ya se usó o caducó, o el archivo se eliminó al final de su período de conservación.

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

413El cuerpo de la solicitud supera el tamaño permitido.

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

415El formato del archivo no es compatible.

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

503Un servicio del que depende esta solicitud no está disponible temporalmente. Vuelva a intentarlo más tarde.

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

Códigos de error

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

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la 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

curl -X POST 'https://api.sursa.com/v1/cards/archive' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Probar

Clave de API

La clave se queda en la memoria de esta pestaña y solo se envía a https://api.sursa.com.

Las solicitudes actúan sobre los datos reales de su organización.

Idempotency-Key header

X-View-As header

Idempotency-Key

Si este campo está vacío, se genera una clave nueva para cada solicitud.

Cuerpo de la solicitud (JSON)