POST/v1/uploads/{upload_id}/complete

Completar una subida

complete_upload

Cuando se han recibido todas las partes, Sursa ensambla el archivo, compara el SHA-256 del archivo completo con sha256 del cuerpo y ejecuta las mismas comprobaciones que para una subida en una sola solicitud: el formato por la firma del contenido y el análisis antivirus. El resultado es ready, o rejected con reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Cada rechazo de la comprobación de formato o del antivirus se anota en el registro de auditoría como file.rejected.

Una respuesta 200 significa que el resultado está listo; 202, que el archivo aún se está comprobando (processing), y el resultado se obtiene con GET /v1/uploads/{upload_id}. Si el estado vuelve a pending (un reinicio de una instancia de la API interrumpió la comprobación), envíe complete de nuevo. Repetir complete después del resultado devuelve el mismo resultado. Las partes que faltan devuelven 409 uploads.incomplete (details.missing). Un sha256 distinto del declarado al crear la subida, o un parts[].etag distinto del de una parte recibida, devuelve 422 uploads.checksum_mismatch. Una subida lista que no se usa se conserva durante 24 horas. 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 ruta

upload_idstringobligatorio
ID de la subida (upl_ seguido de 32 caracteres hexadecimales).
length ≤ 64

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

Cuerpo de la solicitud

application/json

Objeto: UploadComplete

sha256stringobligatorio
El SHA-256 del archivo completo.
partsarray of UploadPartRef
Comprobación opcional de las partes: el ETag de cada parte tal como lo devuelve PUT …/parts/{n}.
items ≤ 1000

Respuestas

200El resultado está listo: `ready` o `rejected`.

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: Upload

idstringobligatorio
El ID de la subida (upl_ seguido de 32 caracteres hexadecimales).
purposeUploadPurposeobligatorio
filenamestringobligatorio
El nombre del archivo (sin carpetas).
content_typestringobligatorio
El tipo de contenido declarado; vacío si no se declaró.
sizeinteger (int64)obligatorio
El tamaño del archivo en bytes.
sha256string | nullobligatorio
El SHA-256 del archivo, declarado al crear la subida o en complete; null si todavía no se conoce.
statusUploadStatusobligatorio
part_sizeinteger (int64)obligatorio
El tamaño de cada parte excepto la última (de 5 a 100 MiB).
part_countintegerobligatorio
El número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobligatorio
El número de partes recibidas.
≥ 0
partsarray of UploadPartobligatorio
Las partes recibidas por número (vacío en la respuesta de POST /v1/uploads).
reject_reasonstring | nullobligatorio
El motivo del rechazo (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. La enumeración puede ampliarse; null si no se rechazó.
reject_detailsobject | nullobligatorio
Detalles del rechazo (la extensión, el formato declarado y el detectado, las sumas de comprobación); null si no se rechazó.
created_atstring (date-time)obligatorio
Cuándo se creó la subida.
expires_atstring (date-time)obligatorio
El plazo para completar la subida y, una vez lista, para usarla.
completed_atstring (date-time) | nullobligatorio
Cuándo terminó la comprobación (ready o rejected).
consumed_atstring (date-time) | nullobligatorio
Cuándo se usó la subida (en una tarjeta, un archivo comprimido o una importación).

202El archivo aún se está comprobando (`processing`).

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: Upload

idstringobligatorio
El ID de la subida (upl_ seguido de 32 caracteres hexadecimales).
purposeUploadPurposeobligatorio
filenamestringobligatorio
El nombre del archivo (sin carpetas).
content_typestringobligatorio
El tipo de contenido declarado; vacío si no se declaró.
sizeinteger (int64)obligatorio
El tamaño del archivo en bytes.
sha256string | nullobligatorio
El SHA-256 del archivo, declarado al crear la subida o en complete; null si todavía no se conoce.
statusUploadStatusobligatorio
part_sizeinteger (int64)obligatorio
El tamaño de cada parte excepto la última (de 5 a 100 MiB).
part_countintegerobligatorio
El número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobligatorio
El número de partes recibidas.
≥ 0
partsarray of UploadPartobligatorio
Las partes recibidas por número (vacío en la respuesta de POST /v1/uploads).
reject_reasonstring | nullobligatorio
El motivo del rechazo (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. La enumeración puede ampliarse; null si no se rechazó.
reject_detailsobject | nullobligatorio
Detalles del rechazo (la extensión, el formato declarado y el detectado, las sumas de comprobación); null si no se rechazó.
created_atstring (date-time)obligatorio
Cuándo se creó la subida.
expires_atstring (date-time)obligatorio
El plazo para completar la subida y, una vez lista, para usarla.
completed_atstring (date-time) | nullobligatorio
Cuándo terminó la comprobación (ready o rejected).
consumed_atstring (date-time) | nullobligatorio
Cuá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-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

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.

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.

← uploads · Referencia de la API

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -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

upload_id path *

Idempotency-Key

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

Cuerpo de la solicitud (JSON)