Cargas
Un archivo grande enviado por partes: la entrada de una operación masiva.
Cargas
Objetos
Upload
idintegerobligatorioID del registro, único entre los registros de su tipo en la tienda.
file_namestringobligatorioNombre del archivo dado al iniciar la carga.
sizeintegerobligatorioTamaño del archivo completo en bytes.
receivedintegerobligatorioBytes recibidos: el desplazamiento de la siguiente parte.
completebooleanobligatorioEl archivo está armado: una operación masiva puede tomarlo por id. Después de eso la carga deja de existir.
chunk_bytesintegerobligatorioTamaño máximo de una parte en bytes.
expires_atstring (date-time)obligatorioDespués de este momento una carga no usada se elimina.
created_atstring (date-time)obligatorioCuándo se creó el registro.
Endpoints
Obtener una carga de archivo por partes: cuánto se recibió
get/uploads/{upload}
Scope: bulk:read
Parámetros
Ruta
uploadintegerobligatorioID de la carga.
Respuestas
200Éxito
application/json
Devuelve Upload
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl "https://api.saleya.app/v1/uploads/{upload}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"file_name": "string",
"size": 0,
"received": 0,
"complete": true,
"chunk_bytes": 0,
"expires_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z"
}Iniciar una carga de archivo por partes: la entrada de una operación masiva
post/uploads
Scope: bulk:write
Parámetros
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
Cuerpo de la solicitud application/json
file_namestringobligatorioNombre del archivo dado al iniciar la carga.
- Largo máximo:
- 255
sizeintegerobligatorioTamaño del archivo completo en bytes.
- Mínimo:
- 1
- Máximo:
- 268435456
Respuestas
201Creado
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
application/json
Devuelve Upload
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X POST "https://api.saleya.app/v1/uploads" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"file_name": "string",
"size": 1
}{
"id": 0,
"file_name": "string",
"size": 0,
"received": 0,
"complete": true,
"chunk_bytes": 0,
"expires_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z"
}Agregar una parte del archivo como cuerpo crudo
post/uploads/{upload}/chunks
Scope: bulk:write
Parámetros
Ruta
uploadstringobligatorioID de la carga.
Query
offsetintegerobligatorioByte del archivo donde empieza la parte: igual a received de la carga, si no, 409 upload_offset_mismatch. La parte en sí es el cuerpo crudo de la solicitud.
- Mínimo:
- 0
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
Cuerpo de la solicitud application/octet-stream
string (binary)
Respuestas
200Éxito
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
application/json
Devuelve Upload
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 409
upload_offset_mismatchLa parte no empieza donde corresponde - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X POST "https://api.saleya.app/v1/uploads/{upload}/chunks?offset=<offset>" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @file{
"id": 0,
"file_name": "string",
"size": 0,
"received": 0,
"complete": true,
"chunk_bytes": 0,
"expires_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z"
}