Stock
Stock de una variante en un local: leer los niveles, fijar el stock físico después de un conteo, ingresar o dar de baja mercadería.
Stock
Objetos
InventoryLevel
variant_idintegerobligatorioID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.
location_idintegerobligatorioID del local de la tienda.
on_handstringobligatorioStock físico del local en todas sus ubicaciones, como cadena decimal en la unidad de la variante. Fijar el stock nombra y verifica este valor.
reservedstringobligatorioCantidad reservada para pedidos, como cadena decimal en la unidad de la variante.
availablestringobligatorioCantidad que se puede vender: stock disponible para preparar menos las reservas, como cadena decimal. Negativa si se vendió más de lo que había.
updated_atstring (date-time) o nullobligatorioCuándo cambió el stock por última vez; null si el par aún no tuvo movimientos.
InventoryChange
statusstringobligatorioResultado de la escritura: applied — el stock cambió; unchanged — el stock ya tenía ese valor; pending_approval — la baja espera aprobación en la tienda: on_hand aún no cambió, available ya excluye la cantidad retenida.
- Valores:
appliedunchangedpending_approval
Nivel de stock del par después de la escritura.
Endpoints
Listar el stock por local cambiado desde un momento dado
get/inventory-levels
Scope: inventory:read
Parámetros
Query
limitintegerTamaño de página: hasta 250 registros; 50 por defecto.
- Mínimo:
- 1
- Máximo:
- 250
cursorstringCursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.
- Largo máximo:
- 4096
updated_sincestring (date-time)Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.
- Patrón:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — devolver también los registros eliminados: los archivados con deleted_at y los borrados de la base como marcas de eliminación {id, deleted_at} en la continuación por el cursor de sincronización. Activalo para sincronizar.
variant_idintegerSolo el stock de esta variante.
- Mínimo:
- 1
location_idintegerSolo el stock de este local.
- Mínimo:
- 1
Respuestas
200Éxito
application/json
Registros de la página.
deletedarray de objectobligatorioRegistros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.
Campos · 2
idintegerobligatorioID del registro borrado.
deleted_atstring (date-time)obligatorioCuándo se borró el registro.
next_cursorstring o nullobligatorioCursor de la página siguiente; null en la última.
has_morebooleanobligatoriotrue si hay una página siguiente.
sync_cursorstring o nullobligatorioEn la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.
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
410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos
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
Errores de este endpoint
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/inventory-levels" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Fijar el stock físico de una variante en un local
post/inventory-levels/set
Scope: inventory: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
variant_idintegerobligatorioID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.
location_idintegerobligatorioID del local de la tienda.
commentstring o nullComentario del movimiento.
- Largo máximo:
- 500
lot_numberstring o nullLote al que va la diferencia, en una variante con lotes.
- Largo máximo:
- 64
expires_atstring (date) o nullFecha de vencimiento de un lote nuevo, en la zona horaria de la tienda.
on_handstringobligatorioStock físico del local en todas sus ubicaciones, como cadena decimal en la unidad de la variante. Fijar el stock nombra y verifica este valor.
- Largo máximo:
- 32
- Patrón:
^-?\d{1,15}(\.\d{1,15})?$
expected_on_handstringobligatorioEl stock físico sobre el que contaste, como cadena decimal. Si el stock cambió desde entonces, la solicitud recibe 409 stock_on_hand_changed y no cambia nada.
- Largo máximo:
- 32
- Patrón:
^-?\d{1,15}(\.\d{1,15})?$
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 InventoryChange
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 - 409
stock_held_by_write_offsEl stock está retenido por bajas pendientes de aprobación - 409
stock_on_hand_changedCambió el stock físico - 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/inventory-levels/set" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"variant_id": 0,
"location_id": 0,
"comment": "string",
"lot_number": "string",
"expires_at": "2026-01-15",
"on_hand": "string",
"expected_on_hand": "string"
}{
"status": "applied",
"inventory_level": {
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
}Ingresar stock o darlo de baja en un local
post/inventory-levels/adjust
Scope: inventory: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
variant_idintegerobligatorioID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.
location_idintegerobligatorioID del local de la tienda.
commentstring o nullComentario del movimiento; obligatorio si lo exige el motivo de baja.
- Largo máximo:
- 500
lot_numberstring o nullEn un ingreso de una variante con lotes — el lote; uno nuevo recibe expires_at. Sin número, la mercadería va a un lote nuevo con número automático, como en una recepción.
- Largo máximo:
- 64
expires_atstring (date) o nullFecha de vencimiento de un lote nuevo, en la zona horaria de la tienda.
reasonstringobligatoriorestock — llega mercadería, delta es positivo; write_off — la mercadería se da de baja por un motivo de la tienda (write_off_reason_id), delta es negativo.
- Valores:
restockwrite_off
deltastringobligatorioCambio del stock físico, como cadena decimal en la unidad de la variante. No se puede bajar el stock sin un motivo de baja: la corrección de un conteo erróneo va por fijar el stock.
- Largo máximo:
- 32
- Patrón:
^-?\d{1,15}(\.\d{1,15})?$
write_off_reason_idintegerEn write_off — el motivo (/v1/write-off-reasons); debe ser selectable.
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 InventoryChange
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/inventory-levels/adjust" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"variant_id": 0,
"location_id": 0,
"comment": "string",
"lot_number": "string",
"expires_at": "2026-01-15",
"reason": "restock",
"delta": "string",
"write_off_reason_id": 0
}{
"status": "applied",
"inventory_level": {
"variant_id": 0,
"location_id": 0,
"on_hand": "string",
"reserved": "string",
"available": "string",
"updated_at": "2026-01-15T12:00:00Z"
}
}