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.

Cargando el índice de búsqueda…

Stock

Objetos

InventoryLevel

  • variant_idintegerobligatorio

    ID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.

  • location_idintegerobligatorio

    ID del local de la tienda.

  • on_handstringobligatorio

    Stock 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.

  • reservedstringobligatorio

    Cantidad reservada para pedidos, como cadena decimal en la unidad de la variante.

  • availablestringobligatorio

    Cantidad 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 nullobligatorio

    Cuándo cambió el stock por última vez; null si el par aún no tuvo movimientos.

InventoryChange

  • statusstringobligatorio

    Resultado 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
  • inventory_levelInventoryLevelobligatorio

    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

  • limitinteger

    Tamaño de página: hasta 250 registros; 50 por defecto.

    Mínimo:
    1
    Máximo:
    250
  • cursorstring

    Cursor 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_deletedboolean

    true — 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_idinteger

    Solo el stock de esta variante.

    Mínimo:
    1
  • location_idinteger

    Solo el stock de este local.

    Mínimo:
    1

Respuestas

200Éxito

application/json

  • dataarray de InventoryLevelobligatorio

    Registros de la página.

  • deletedarray de objectobligatorio

    Registros 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
    • idintegerobligatorio

      ID del registro borrado.

    • deleted_atstring (date-time)obligatorio

      Cuándo se borró el registro.

  • next_cursorstring o nullobligatorio

    Cursor de la página siguiente; null en la última.

  • has_morebooleanobligatorio

    true si hay una página siguiente.

  • sync_cursorstring o nullobligatorio

    En 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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos 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

Ejemplo de solicitud
curl "https://api.saleya.app/v1/inventory-levels" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Ejemplo de respuesta · 200
{
  "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-Keystring

    Clave ú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_idintegerobligatorio

    ID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.

  • location_idintegerobligatorio

    ID del local de la tienda.

  • commentstring o null

    Comentario del movimiento.

    Largo máximo:
    500
  • lot_numberstring o null

    Lote al que va la diferencia, en una variante con lotes.

    Largo máximo:
    64
  • expires_atstring (date) o null

    Fecha de vencimiento de un lote nuevo, en la zona horaria de la tienda.

  • on_handstringobligatorio

    Stock 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_handstringobligatorio

    El 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-Replayedstring

    true 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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterinteger

    Segundos 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos 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

Ejemplo de solicitud
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
Cuerpo de la solicitud — 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"
}
Ejemplo de respuesta · 200
{
  "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-Keystring

    Clave ú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_idintegerobligatorio

    ID de la variante. Junto con location_id identifica el nivel de stock; un par que no está en la lista tiene stock cero.

  • location_idintegerobligatorio

    ID del local de la tienda.

  • commentstring o null

    Comentario del movimiento; obligatorio si lo exige el motivo de baja.

    Largo máximo:
    500
  • lot_numberstring o null

    En 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 null

    Fecha de vencimiento de un lote nuevo, en la zona horaria de la tienda.

  • reasonstringobligatorio

    restock — 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
  • deltastringobligatorio

    Cambio 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_idinteger

    En write_off — el motivo (/v1/write-off-reasons); debe ser selectable.

Respuestas

200Éxito

Encabezados

  • Idempotent-Replayedstring

    true 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-Authenticatestringobligatorio

    Esquema 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-Authenticatestring

    Esquema 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-Afterinteger

    Segundos 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-Afterintegerobligatorio

    Segundos de espera antes de reintentar.

    Mínimo:
    0

application/problem+json

Devuelve RateLimitProblem

503La tienda no está disponible por ahora

Encabezados

  • Retry-Afterinteger

    Segundos 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

Ejemplo de solicitud
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
Cuerpo de la solicitud — 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
}
Ejemplo de respuesta · 200
{
  "status": "applied",
  "inventory_level": {
    "variant_id": 0,
    "location_id": 0,
    "on_hand": "string",
    "reserved": "string",
    "available": "string",
    "updated_at": "2026-01-15T12:00:00Z"
  }
}