# Registros

Los métodos de esta página trabajan con los registros de una lista. Los valores de los campos se envían en el objeto `data`: la clave es el `slug` del campo y el valor va en el formato de su tipo. Los formatos de todos los tipos se describen en la página [Listas](https://support.jetbot24.ru/es/api/lists#tipos-de-campo).

## getListItems

Devuelve los registros de una lista por páginas, con filtrado por los valores de los campos y ordenación.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/getListItems
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |
| `limit` | entero | no | Registros por página: de 1 a 1000, 50 por defecto |
| `page` | entero | no | Número de página, `1` por defecto |
| `order_by` | cadena | no | Ordenación: el `slug` del campo y la dirección separados por una coma, `price,desc`. La dirección es `asc` (ascendente, por defecto) o `desc`. También puedes ordenar por `created_at` y `updated_at`. Cualquier otro campo o dirección: `422` |
| `filters` | objeto | no | Filtrado por los valores de los campos; ver más abajo |
| `contact_id` | entero | no | Solo los registros vinculados a este contacto mediante un campo `contact` |
| `bot_id` | entero | no | Solo los registros vinculados a este bot mediante un campo `bot` |

Por ejemplo, lattes de 12 oz o más, de mayor a menor:

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/getListItems" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "filters": {"volume": ">=,12", "title": "like,%latte%"},
    "order_by": "volume,desc",
    "limit": 20
  }'
```

```json title="Respuesta 200"
{
  "data": [
    {
      "id": "6650b7a1c3d4e5f6a7b8c9e1",
      "created_at": "2026-10-03T08:05:00+00:00",
      "updated_at": "2026-10-03T08:05:00+00:00",
      "title": "Latte con leche de avena",
      "price": 5.25,
      "photo": {
        "type": "image",
        "mime_type": "image/jpeg",
        "created_at": null,
        "name": "latte.jpg",
        "size": 0,
        "storage": "url",
        "caption": null,
        "meta": {"width": null, "height": null, "duration": null, "codec": null},
        "url": "https://example.com/menu/latte.jpg"
      },
      "in_stock": true,
      "volume": 16
    }
  ],
  "links": {
    "first": "…/v1/getListItems?page=1",
    "last": "…/v1/getListItems?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "…/v1/getListItems",
    "per_page": 20,
    "to": 1,
    "total": 1
  }
}
```

```json title="Respuesta 422"
{
  "message": "The limit field must not be greater than 1000.",
  "errors": {
    "limit": ["The limit field must not be greater than 1000."]
  }
}
```

Cada registro contiene `id`, `created_at`, `updated_at` y los valores de todos los campos de la lista, incluidos los ocultos y los cifrados (descifrados). Si un registro está vinculado a un contacto o a un bot, también tiene `contact_id` o `bot_id`.

### Filtrado

En `filters`, la clave es el `slug` del campo y el valor es uno de estos:

- `"valor"` o simplemente un valor JSON: el campo es igual al valor, `{"title": "Cappuccino"}`, `{"volume": 12}`, `{"in_stock": true}`;
- `"operador,valor"`: una comparación, `{"volume": ">=,12"}`.

| Operador | Significado |
|---|---|
| `=` | igual a |
| `!=`, `<>` | distinto de |
| `<`, `<=`, `>`, `>=` | menor que, menor o igual que, mayor que, mayor o igual que |
| `like` | coincide con un patrón: `%`, cualquier número de caracteres; `_`, un carácter. No distingue mayúsculas de minúsculas. Sin `%`, debe coincidir el valor completo |
| `not like` | no coincide con un patrón |

Un operador solo se reconoce si el texto anterior a la primera coma es un operador de la tabla. Si no, toda la cadena es el valor: `{"title": "Flat white, grande"}` encuentra el registro «Flat white, grande». Si el propio valor empieza por un operador y una coma, como `">, 5"`, indica el operador explícitamente: `"=,>, 5"`.

Las condiciones sobre campos distintos se combinan con «y».

Cómo se compara el valor depende del tipo de campo:

| Tipo de campo | Valor del filtro | Operadores |
|---|---|---|
| `string` | Texto. Un número JSON se compara como texto | todos |
| `number` | Un número: `12`, `"12"`, `"4.5"` | todos salvo `like` y `not like` |
| `money` | Un importe en unidades principales, como al escribir: `5` o `"4.99"` | todos salvo `like` y `not like` |
| `bool` | `true`, `false`, `"true"`, `"false"`, `1`, `0` | `=`, `!=` |
| `date` | Una fecha: `"2026-10-15"`. El día se compara en UTC: `"2026-10-15"` también encuentra un registro con fecha del 15 de octubre a las 14:30, y `"<=,2026-10-15"` encuentra todo hasta el final de ese día | todos salvo `like` y `not like` |
| `datetime` | Una fecha y hora: `"2026-10-15 14:30"` o `"2026-10-15T14:30:00+03:00"`. Una hora sin zona horaria es UTC | todos salvo `like` y `not like` |
| `contact`, `bot` | Un ID de contacto o de bot | todos salvo `like` y `not like` |

Un patrón `like` o `not like` puede tener hasta 255 caracteres, con un máximo de 10 signos `%`; varios `%` seguidos cuentan como uno.

Un valor que no corresponde al campo (texto en un campo `number`, `like` sobre un importe, un objeto en lugar de un valor): `422` con un error en `filters.<slug>`. Si `filters` no es un objeto, el error está en `filters`.

Una condición se omite sin error si la lista no tiene ningún campo con ese `slug`, si el campo está cifrado, si es un archivo o una imagen, o si el valor es `null`.

En una solicitud `GET`, los filtros se pasan en la dirección: `filters[volume]=>=,12`. Codifica los caracteres especiales: `%` como `%25`.

### Páginas

El número total de registros y de páginas está en `meta.total` y `meta.last_page`, y la dirección de la página siguiente, en `links.next` (`null` en la última). Sin `order_by`, el orden de los registros no está definido: al recorrer las páginas, indica un orden, por ejemplo `created_at`.

Errores:

- La lista no existe: `404`, `{"message": "Schema not found", "error": "Schema not found", "errors": {"schema_id": ["Schema not found"]}}`.
- La lista pertenece a un proyecto ajeno: `403`.
- `order_by` o `filters` no válidos: `422`.

## addListItem

Añade un registro a una lista.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/addListItem
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |
| `data` | objeto | sí | Valores de los campos: la clave es el `slug`, y el valor, en el formato del tipo de campo |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/addListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "data": {
      "title": "Cappuccino",
      "price": 4.5,
      "photo": {
        "url": "https://example.com/menu/cappuccino.jpg",
        "storage": "url",
        "name": "cappuccino.jpg",
        "type": "image"
      },
      "in_stock": true,
      "volume": 12
    }
  }'
```

```json title="Respuesta 201"
{
  "data": {
    "id": "6650b7a1c3d4e5f6a7b8c9e2",
    "created_at": "2026-10-03T08:10:00+00:00",
    "updated_at": "2026-10-03T08:10:00+00:00",
    "title": "Cappuccino",
    "price": 4.5,
    "photo": {
      "type": "image",
      "mime_type": null,
      "created_at": null,
      "name": "cappuccino.jpg",
      "size": 0,
      "storage": "url",
      "caption": null,
      "meta": {"width": null, "height": null, "duration": null, "codec": null},
      "url": "https://example.com/menu/cappuccino.jpg"
    },
    "in_stock": true,
    "volume": 12
  }
}
```

```json title="Respuesta 422"
{
  "message": "The data.title field is required.",
  "errors": {
    "data.title": ["The data.title field is required."]
  }
}
```

Notas y errores:

- Los campos obligatorios (`is_required: true`) deben estar rellenos; si no, `422`. Los campos que faltan en `data` quedan vacíos. Las claves que no son campos de la lista se ignoran.
- Un valor de tipo incorrecto: `422` con un error en `data.<slug>`; por ejemplo, texto en un campo `number` o un ID de contacto que no existe.
- Un contacto o bot ajeno en los campos `contact` y `bot`: `403`.
- Las fechas de la respuesta son cadenas en UTC, como en `getListItems`: `"2026-10-15T00:00:00.000000Z"`.
- La lista no existe: `404`, como en `getListItems`; la lista pertenece a un proyecto ajeno: `403`.

## updateListItem

Cambia los valores de los campos de un registro. Los campos que faltan en `data` no cambian.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/updateListItem
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `item_id` | cadena | sí | ID del registro |
| `data` | objeto | sí | Nuevos valores de los campos: la clave es el `slug`, y el valor, en el formato del tipo de campo |

Por ejemplo, un precio nuevo y la marca «agotado»:

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/updateListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "6650b7a1c3d4e5f6a7b8c9e2",
    "data": {"price": 4.75, "in_stock": false}
  }'
```

```json title="Respuesta 200"
{
  "data": {
    "id": "6650b7a1c3d4e5f6a7b8c9e2",
    "created_at": "2026-10-03T08:10:00+00:00",
    "updated_at": "2026-10-03T09:30:00+00:00",
    "title": "Cappuccino",
    "price": 4.75,
    "photo": {
      "type": "image",
      "mime_type": null,
      "created_at": null,
      "name": "cappuccino.jpg",
      "size": 0,
      "storage": "url",
      "caption": null,
      "meta": {"width": null, "height": null, "duration": null, "codec": null},
      "url": "https://example.com/menu/cappuccino.jpg"
    },
    "in_stock": false,
    "volume": 12
  }
}
```

```json title="Respuesta 404"
{
  "message": "Item not found",
  "error": "Item not found",
  "errors": {
    "item_id": ["Item not found"]
  }
}
```

La respuesta contiene el registro completo.

Notas y errores:

- Solo se validan los campos que envías. Un campo obligatorio no se puede enviar vacío: `422`.
- Este método no puede vaciar un campo: `null` y los valores vacíos se omiten, y el campo conserva su valor anterior.
- Las fechas de la respuesta son cadenas en UTC, como en `getListItems`.
- El registro no existe, se eliminó o se eliminó su lista: `404`. El texto del error está en `error` y `message`; por compatibilidad, también en `errors.item_id`.
- El registro pertenece a una lista de un proyecto ajeno: `403`.

## deleteListItem

Elimina un registro.

```endpoint
GET POST https://app.jetbot24.ru/api/v1/deleteListItem
```

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `item_id` | cadena | sí | ID del registro |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/deleteListItem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "6650b7a1c3d4e5f6a7b8c9e2"}'
```

```json title="Respuesta 404"
{
  "message": "Item not found",
  "error": "Item not found",
  "errors": {
    "item_id": ["Item not found"]
  }
}
```

Una respuesta correcta tiene el código `204` y no tiene cuerpo.

Errores:

- El registro no existe, ya se eliminó o se eliminó su lista: `404`, como en [`updateListItem`](#updatelistitem).
- El registro pertenece a una lista de un proyecto ajeno: `403`.