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

# Supply

> Gestión de inventario: stock global, niveles por Nippy Center, alertas, retiros y centros de distribución

## Ejemplos de lo que puedes preguntarle a tu agente

* "¿Qué productos tengo en inventario y cuántos quedan de cada uno?"
* "¿Hay algo por debajo del stock mínimo? Avísame qué urge reponer"
* "Muéstrame los centros de distribución que tengo y qué hay en cada uno"
* "Registra una entrega de 3 uniformes a Carlos en el centro de Guadalajara"
* "¿Cuántos retiros hubo en abril? Dame el historial completo"

Supply te deja manejar todo tu inventario desde el chat. Consultas lo que hay, recibes alertas cuando algo se está acabando y registras movimientos. Las operaciones que modifican datos (crear centros, asignar stock, registrar retiros) siempre te muestran un preview antes de ejecutarse — nada se escribe sin que confirmes.

***

## Tools de lectura

### `supply_list_stocks`

Lista el catálogo global de productos (stock) de este negocio.

<ParamField body="limit" type="integer" default="100">
  Número máximo de items a retornar.
</ParamField>

**Respuesta incluye:** `_id`, `productName`, `totalStock`, `minStockAlert`, `type`, `createdAt`

```json theme={null}
{
  "name": "supply_list_stocks",
  "arguments": {
    "limit": 50
  }
}
```

***

### `supply_list_nippy_center_stocks`

Lista los niveles de stock por Nippy Center. Opcionalmente filtra por un centro específico.

<ParamField body="nippy_center_id" type="string" default="''">
  ID del Nippy Center. Si se omite, retorna todos los centros del negocio.
</ParamField>

<ParamField body="limit" type="integer" default="100">
  Número máximo de items a retornar.
</ParamField>

**Respuesta incluye:** `_id`, `stockId`, `nippyCenterId`, `currentStock`, `minStockAlert`, `criticality`, `productName`

```json theme={null}
{
  "name": "supply_list_nippy_center_stocks",
  "arguments": {
    "nippy_center_id": "64aed18101d27bba60dce608",
    "limit": 100
  }
}
```

***

### `supply_get_low_stock_alerts`

Lista todos los items donde el stock actual está por debajo del umbral mínimo configurado.

<ParamField body="limit" type="integer" default="100">
  Número máximo de alertas a retornar.
</ParamField>

**Respuesta incluye:** items con `currentStock < minStockAlert`, con `productName` joineado del catálogo.

```json theme={null}
{
  "name": "supply_get_low_stock_alerts",
  "arguments": {
    "limit": 20
  }
}
```

***

### `supply_get_withdrawal_history`

Lista el historial de retiros de supply para este negocio en un rango de fechas.

<ParamField body="date_from" type="string" default="''">
  Fecha de inicio en formato ISO 8601, e.g. `"2026-01-01"`. Opcional.
</ParamField>

<ParamField body="date_to" type="string" default="''">
  Fecha de fin en formato ISO 8601, e.g. `"2026-05-08"`. Opcional.
</ParamField>

<ParamField body="limit" type="integer" default="50">
  Número máximo de retiros a retornar.
</ParamField>

```json theme={null}
{
  "name": "supply_get_withdrawal_history",
  "arguments": {
    "date_from": "2026-05-01",
    "date_to": "2026-05-08",
    "limit": 100
  }
}
```

***

### `supply_list_nippy_centers`

Lista los Nippy Centers (puntos de distribución) del negocio.

<ParamField body="limit" type="integer" default="100">
  Número máximo de centros a retornar.
</ParamField>

**Respuesta incluye:** `_id`, `name`, `address`, `geo`, `capacity`, `schedule`, `isActive`, `type`

```json theme={null}
{
  "name": "supply_list_nippy_centers",
  "arguments": {
    "limit": 50
  }
}
```

***

## Tools de escritura — Nippy Centers

### `supply_propose_nippy_center`

Genera un preview del Nippy Center antes de crearlo. **No escribe a la base de datos.**

<ParamField body="name" type="string" required>
  Nombre del Nippy Center.
</ParamField>

<ParamField body="address" type="string" default="''">
  Dirección física del centro.
</ParamField>

<ParamField body="lat" type="float" default="0.0">
  Latitud para Google Maps.
</ParamField>

<ParamField body="long" type="float" default="0.0">
  Longitud para Google Maps.
</ParamField>

<ParamField body="google_maps_link" type="string" default="''">
  URL de Google Maps. Si se omite, se genera automáticamente a partir de lat/long.
</ParamField>

<ParamField body="active_member_duration" type="integer" default="30">
  Duración de la cita para miembros activos (minutos).
</ParamField>

<ParamField body="non_member_duration" type="integer" default="15">
  Duración de la cita para no miembros (minutos).
</ParamField>

<ParamField body="capacity" type="integer" default="50">
  Capacidad máxima del centro.
</ParamField>

<ParamField body="country_id" type="string" default="''">
  ID del país. Si se omite, usa el default del negocio.
</ParamField>

<ParamField body="type" type="string" default="'physical'">
  Tipo de centro: `"physical"` u `"online"`.
</ParamField>

<ParamField body="is_active" type="boolean" default="true">
  Si el centro está activo.
</ParamField>

```json theme={null}
{
  "name": "supply_propose_nippy_center",
  "arguments": {
    "name": "Centro Norte CDMX",
    "address": "Av. Insurgentes 123, CDMX",
    "lat": 19.4326,
    "long": -99.1332,
    "capacity": 80,
    "type": "physical"
  }
}
```

***

### `supply_create_nippy_center`

Crea el Nippy Center en la base de datos. Mismos parámetros que `propose_nippy_center`.

<Warning>
  Solo llama esta tool después de mostrar al usuario el preview de `propose_nippy_center` y recibir confirmación explícita.
</Warning>

**Respuesta:** `{"_id": "...", "name": "Centro Norte CDMX", "status": "created"}`

***

## Tools de escritura — Stock global

### `supply_propose_stock`

Genera un preview del producto de stock antes de crearlo. **No escribe a la base de datos.**

<ParamField body="product_name" type="string" required>
  Nombre del producto.
</ParamField>

<ParamField body="total_stock" type="integer" required>
  Cantidad total de stock inicial.
</ParamField>

<ParamField body="min_stock_alert" type="integer" required>
  Umbral mínimo para alertas de bajo inventario.
</ParamField>

<ParamField body="type" type="string" default="''">
  Categoría del producto, e.g. `"insumo"`, `"premio"`, `"uniforme"`. Opcional.
</ParamField>

```json theme={null}
{
  "name": "supply_propose_stock",
  "arguments": {
    "product_name": "Mochila Nippy 2026",
    "total_stock": 500,
    "min_stock_alert": 50,
    "type": "premio"
  }
}
```

***

### `supply_create_stock`

Crea el producto en el catálogo global. Mismos parámetros que `propose_stock`.

<Warning>
  Solo llama esta tool después de mostrar al usuario el preview de `propose_stock` y recibir confirmación explícita.
</Warning>

**Respuesta:** `{"_id": "...", "productName": "Mochila Nippy 2026", "status": "created"}`

***

## Tools de escritura — Stock por Nippy Center

### `supply_propose_nippy_center_stock`

Genera un preview de la asignación de stock a un Nippy Center. **No escribe a la base de datos.**

<ParamField body="stock_id" type="string" required>
  ID del producto del catálogo global (de `list_stocks`).
</ParamField>

<ParamField body="nippy_center_id" type="string" required>
  ID del Nippy Center (de `list_nippy_centers`).
</ParamField>

<ParamField body="current_stock" type="integer" required>
  Cantidad de stock a asignar al centro.
</ParamField>

<ParamField body="min_stock_alert" type="integer" required>
  Umbral mínimo para alertas en este centro.
</ParamField>

<ParamField body="criticality" type="string" default="''">
  Nivel de criticidad: `"low"`, `"medium"`, `"high"`. Opcional.
</ParamField>

```json theme={null}
{
  "name": "supply_propose_nippy_center_stock",
  "arguments": {
    "stock_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "nippy_center_id": "64aed18101d27bba60dce608",
    "current_stock": 100,
    "min_stock_alert": 10,
    "criticality": "high"
  }
}
```

***

### `supply_create_nippy_center_stock`

Asigna stock a un Nippy Center. Mismos parámetros que `propose_nippy_center_stock`.

<Warning>
  Valida que tanto el stock como el centro pertenezcan al negocio antes de escribir.
</Warning>

**Respuesta:** `{"_id": "...", "status": "created"}`

***

## Tools de escritura — Retiros

### `supply_propose_withdrawal`

Genera un preview del retiro y valida la disponibilidad de stock. **No escribe a la base de datos.**

Verifica que:

* El Nippy Center pertenece al negocio
* El stock pertenece al negocio
* Hay suficiente stock en el centro para la cantidad solicitada

<ParamField body="stock_id" type="string" required>
  ID del producto a retirar.
</ParamField>

<ParamField body="nippy_center_id" type="string" required>
  ID del Nippy Center de donde se retira.
</ParamField>

<ParamField body="worker_id" type="string" required>
  ID del trabajador que recibe el retiro.
</ParamField>

<ParamField body="email" type="string" required>
  Email del trabajador.
</ParamField>

<ParamField body="quantity" type="integer" required>
  Cantidad a retirar.
</ParamField>

<ParamField body="withdrawal_type" type="string" default="'insumos'">
  Tipo de retiro. Consulta `nippy://supply/schema/withdrawals` para los tipos disponibles.
</ParamField>

<ParamField body="entregador" type="string" default="''">
  Nombre del entregador. Opcional.
</ParamField>

<ParamField body="tipo_entrega" type="string" default="''">
  Tipo de entrega. Opcional.
</ParamField>

<ParamField body="ciudad" type="string" default="''">
  Ciudad. Opcional.
</ParamField>

<ParamField body="talla" type="string" default="''">
  Talla (para uniformes u otros items con talla). Opcional.
</ParamField>

```json theme={null}
{
  "name": "supply_propose_withdrawal",
  "arguments": {
    "stock_id": "664f1a2b3c4d5e6f7a8b9c0d",
    "nippy_center_id": "64aed18101d27bba60dce608",
    "worker_id": "665c8d4e5f6a7b8c9d0e1f2a",
    "email": "trabajador@nippy.la",
    "quantity": 2,
    "withdrawal_type": "insumos"
  }
}
```

***

### `supply_approve_withdrawal`

Ejecuta el retiro. Decrementa el stock en el Nippy Center y registra la entrega. Mismos parámetros que `propose_withdrawal`.

<Warning>
  Solo llama esta tool después de mostrar el preview de `propose_withdrawal` y recibir confirmación explícita. Esta operación es atómica e irreversible.
</Warning>

**Respuesta:** `{"_id": "...", "status": "created"}`

***

## Flujo completo de retiro

```
1. supply_list_nippy_centers          → obtener IDs de centros
2. supply_list_stocks                 → obtener IDs de productos
3. supply_list_nippy_center_stocks    → verificar stock disponible en el centro
4. supply_propose_withdrawal          → preview + validación de disponibilidad
5. [usuario confirma]
6. supply_approve_withdrawal          → ejecutar retiro (decrementa stock + crea registro)
```

<Accordion title="Detalles técnicos (avanzado)">
  Referencias de esquemas para el agente:

  | URI                                 | Nombre                       | Descripción                               |
  | ----------------------------------- | ---------------------------- | ----------------------------------------- |
  | `nippy://supply/schema/stock`       | `supply_stock_schema`        | Campos de stock global y stock por centro |
  | `nippy://supply/schema/withdrawals` | `supply_withdrawal_schema`   | Tipos de retiro y reglas de flujo         |
  | `nippy://supply/schema/centers`     | `supply_nippy_center_schema` | Campos de Nippy Center y scheduling       |
</Accordion>