POST/v1/uploads
Iniciar una subida por partes
create_upload
Abre una sesión de subida para un archivo grande (hasta el límite de la instalación para las subidas por partes, 5 GB de forma predeterminada): el nombre, el tipo de contenido, el tamaño y purpose, que indica qué usará la subida: card_file (POST /v1/cards), archive (POST /v1/cards/archive) o import_attachment (un adjunto de un documento de una fuente personalizada). La respuesta contiene el id (upl_ seguido de 32 caracteres hexadecimales), el tamaño de parte part_size y el número de partes part_count. Todas las partes excepto la última miden exactamente part_size bytes (de 5 a 100 MiB), y la última es el resto. Una subida sin completar se conserva durante 24 horas (expires_at).
Una extensión del nombre del archivo fuera de los formatos de la finalidad devuelve 415 uploads.unsupported_format (un adjunto de importación admite cualquier extensión). Un archivo que supera el límite de la instalación o el almacenamiento total de la organización según su plan devuelve 413 uploads.too_large. Si no queda suficiente almacenamiento, contando las subidas sin completar de la organización, se devuelve 402 limits.storage.
Las partes pasan por Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) y se cifran con la clave de la organización en el almacenamiento de archivos; no hay enlaces directos al almacenamiento. Solo la clave de API o el usuario que creó la subida pueden verla y usarla. Se añadió en 1.62.0.
Autenticación
Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.
Parámetros de encabezado
Idempotency-KeystringClave 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, otroContent-Typeu otro cuerpo devuelve409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso,409 api.idempotency_in_progressconRetry-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
Cuerpo de la solicitud
application/json
filenamestringobligatorioEl nombre del archivo con su extensión; la extensión determina el formato.
length ≥ 1, length ≤ 255
content_typestringEl tipo de contenido declarado (MIME); se compara con la firma del archivo.
length ≤ 255
sizeinteger (int64)obligatorioEl tamaño del archivo en bytes.
≥ 1
sha256stringEl SHA-256 del archivo, si se conoce de antemano;
completecompara con él la suma de comprobación.
Respuestas
201La sesión de subida se ha creado.
Encabezados de la respuesta
RateLimit-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
Idempotency-Replayedtruesignifica que la respuesta se reprodujo a partir de la guardada para estaIdempotency-Key: la operación no se volvió a ejecutar.
application/json
idstringobligatorioEl ID de la subida (
upl_seguido de 32 caracteres hexadecimales).filenamestringobligatorioEl nombre del archivo (sin carpetas).
content_typestringobligatorioEl tipo de contenido declarado; vacío si no se declaró.
sizeinteger (int64)obligatorioEl tamaño del archivo en bytes.
sha256string | nullobligatorioEl SHA-256 del archivo, declarado al crear la subida o en
complete;nullsi todavía no se conoce.part_sizeinteger (int64)obligatorioEl tamaño de cada parte excepto la última (de 5 a 100 MiB).
part_countintegerobligatorioEl número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobligatorioEl número de partes recibidas.
≥ 0
Las partes recibidas por número (vacío en la respuesta de
POST /v1/uploads).reject_reasonstring | nullobligatorioEl motivo del rechazo (
rejected):checksum_mismatch,type_mismatch,unsupported_format,infected,scan_unavailable,unsafe_content. La enumeración puede ampliarse;nullsi no se rechazó.reject_detailsobject | nullobligatorioDetalles del rechazo (la extensión, el formato declarado y el detectado, las sumas de comprobación);
nullsi no se rechazó.created_atstring (date-time)obligatorioCuándo se creó la subida.
expires_atstring (date-time)obligatorioEl plazo para completar la subida y, una vez lista, para usarla.
completed_atstring (date-time) | nullobligatorioCuándo terminó la comprobación (
readyorejected).consumed_atstring (date-time) | nullobligatorioCuándo se usó la subida (en una tarjeta, un archivo comprimido o una importación).
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-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
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-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
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-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
413El cuerpo de la solicitud supera el tamaño permitido.
Encabezados de la respuesta
RateLimit-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
415El formato del archivo no es compatible.
Encabezados de la respuesta
RateLimit-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
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-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
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-AfterNúmero de segundos que hay que esperar antes de reintentar la solicitud.
RateLimit-PolicyLí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>.keyes 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 esusery sin credenciales,ip);minute,dayymonthson las cuotas de la organización para el minuto, el día y el mes naturales en UTC.RateLimitLo que queda de cada límite de
RateLimit-Policy:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitLímite de la entrada más estricta de
RateLimit-Policy(la que tiene menos solicitudes restantes).X-RateLimit-RemainingSolicitudes restantes del límite más estricto.
X-RateLimit-ResetSegundos hasta que se restablece el límite más estricto.
application/json
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.