> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riqra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronizar stock

> Fija el stock disponible por SKU y ubicación desde tu sistema de inventario.

Estos endpoints leen tus ubicaciones y fijan el stock de cada SKU en cada una. Sirven para que tu
ERP o WMS mantenga el stock de Riqra al día, también cuando vendes desde más de un almacén.

## Endpoints

| Acción                     | Endpoint                 | Scope         |
| -------------------------- | ------------------------ | ------------- |
| Listar ubicaciones activas | `GET /stock/locations`   | `stock:read`  |
| Fijar stock                | `POST /stock/levels/set` | `stock:write` |

## Listar las ubicaciones

`GET /stock/locations` devuelve las ubicaciones activas con el `id` que necesitas para fijar stock.
Las ubicaciones se crean desde el panel; revisa [Ubicaciones](/plataforma/inventario/ubicaciones).

```bash theme={null}
curl "https://api-v2.riqra.com/public/v1/stock/locations" \
  -H "Authorization: Bearer rq_live_tu_api_key"
```

```json theme={null}
{
  "locations": [
    { "id": "0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b", "name": "Almacén Lima", "isDefault": true },
    { "id": "1c3d4e6f-8a9b-4c1d-9e3f-4a5b6c7d8e9f", "name": "Almacén Chincha", "isDefault": false }
  ]
}
```

## Fijar stock

`POST /stock/levels/set` recibe hasta 100 ítems. Cada ítem identifica un par SKU + ubicación y
lleva **exactamente uno** de estos campos:

* `onHand`: cantidad física en la ubicación.
* `available`: cantidad vendible. Riqra guarda `onHand = available + committed`, donde `committed`
  son las unidades reservadas por pedidos abiertos.

```bash theme={null}
curl -X POST "https://api-v2.riqra.com/public/v1/stock/levels/set" \
  -H "Authorization: Bearer rq_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "sku": "SKU-001", "locationId": "0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b", "available": 120 },
      { "sku": "SKU-001", "locationId": "1c3d4e6f-8a9b-4c1d-9e3f-4a5b6c7d8e9f", "onHand": 35 }
    ]
  }'
```

La respuesta es `200` siempre que el cuerpo sea válido. Cada fila trae su propio `status`, en el
mismo orden del pedido:

```json theme={null}
{
  "results": [
    {
      "sku": "SKU-001",
      "locationId": "0b2e9f5a-1c3d-4e6f-8a9b-0c1d2e3f4a5b",
      "status": 200,
      "onHand": 123,
      "committed": 3,
      "available": 120
    },
    {
      "sku": "SKU-001",
      "locationId": "1c3d4e6f-8a9b-4c1d-9e3f-4a5b6c7d8e9f",
      "status": 200,
      "onHand": 35,
      "committed": 0,
      "available": 35
    }
  ]
}
```

### Reglas

* La escritura es **absoluta**: el valor enviado reemplaza al almacenado, no es un incremento.
* `committed` lo administra Riqra a partir de los pedidos. La API nunca lo escribe.
* Un `onHand` menor que `committed` responde `STOCK_BELOW_COMMITTED` en esa fila. Si tu sistema
  conoce el stock vendible, envía `available` y ese error nunca ocurre.
* Fijar stock de un SKU en una ubicación lo marca como **vendido en esa ubicación**, aunque la
  cantidad sea `0` (aparece como agotado). Para dejar de vender un SKU en una ubicación usa el panel.
* El SKU debe coincidir exactamente con el de la variante, incluidas mayúsculas y minúsculas.
* Un par SKU + ubicación repetido en el mismo pedido responde `400`.

### Errores por fila

| `code`                  | `status` | Cuándo                                                    |
| ----------------------- | -------- | --------------------------------------------------------- |
| `SKU_NOT_FOUND`         | `404`    | Ninguna variante tiene ese SKU.                           |
| `LOCATION_NOT_FOUND`    | `404`    | La ubicación no existe en tu organización.                |
| `LOCATION_INACTIVE`     | `409`    | La ubicación está desactivada.                            |
| `STOCK_BELOW_COMMITTED` | `422`    | El `onHand` enviado es menor que las unidades reservadas. |

Una fila con error no afecta a las demás: las filas válidas del mismo pedido se guardan.

## Stock por ubicación y por comprador

Cada **política comercial** decide desde qué ubicaciones compran las personas a las que aplica. Si
una política selecciona una sola ubicación, sus compradores ven únicamente el stock de esa
ubicación en el catálogo, el carrito y el checkout, y sus pedidos descuentan de ella. Así, un
segmento de trabajadores de una sede puede comprar solo con el stock de esa sede.

Una política sin ubicaciones seleccionadas muestra la mejor disponibilidad entre todas las
ubicaciones activas. Si alimentas más de un almacén por esta API, asigna a cada política las
ubicaciones que le corresponden desde el panel.