# Listas

Los métodos de esta sección crean y eliminan [listas](https://support.jetbot24.ru/es/lists), cambian sus campos y gestionan los registros: añadirlos, leerlos, actualizarlos y eliminarlos. Por ejemplo, tu sitio web puede mantener al día una lista «Carta de la cafetería», y el bot se la muestra a las personas.

## Cómo se estructura una lista

Una lista tiene dos partes:

- **El esquema**: el nombre de la lista y sus campos. Con él trabajan los métodos de la página [Listas y campos](https://support.jetbot24.ru/es/api/lists/schemas). Los nombres de los métodos lo llaman exactamente así: `getListSchema`, `createListSchema`.
- **Los registros**: las filas de la lista con los valores de los campos. Con ellos trabajan los métodos de la página [Registros](https://support.jetbot24.ru/es/api/lists/items).

Las listas pertenecen a un proyecto. Una lista se puede crear en un proyecto o en un bot; en ese caso, también pasa al proyecto de ese bot. La API da acceso a todas las listas de los proyectos del propietario de la clave: tanto las creadas en bots como las creadas directamente en el proyecto.

## Identificadores

| Qué | Cómo es | Dónde obtenerlo |
|---|---|---|
| Lista (`schema_id`, `id` en las respuestas) | Una cadena de 24 caracteres: `6650a1f2c3d4e5f6a7b8c9d0` | Respuestas de `getListSchemas` y `createListSchema` |
| Registro (`item_id`, `id` en las respuestas) | Una cadena de 24 caracteres, como la de una lista | Respuestas de `getListItems` y `addListItem` |
| Campo (`slug`) | Letras, dígitos, `-` y `_`, preferiblemente latinas: `price` | Claves del objeto `fields` en la respuesta de `getListSchema` |
| Proyecto (`project_uuid`, `project` en las respuestas) | Un UUID: `3f2b8c1e-…` | La dirección del proyecto en tu cuenta: `/projects/<uuid>/…` |
| Bot (`bot_id`) | Un número | La dirección del bot en tu cuenta: `/bots/12345/…` |
| Contacto | Un número | Los métodos de contactos |

El `slug` es [el nombre del campo en las plantillas](https://support.jetbot24.ru/es/lists/create#el-nombre-del-campo-en-las-plantillas): el valor se guarda en el registro con ese nombre, y los bloques del bot lo leen con el mismo nombre. Los campos creados en tu cuenta lo reciben automáticamente; a través de la API lo defines tú.

## Tipos de campo

El tipo se define en el parámetro `type` al crear el campo y no se puede cambiar después.

| `type` | Tipo en tu cuenta | Qué enviar | Qué se devuelve |
|---|---|---|---|
| `string` | «Texto» | Una cadena | Una cadena |
| `number` | «Número» | Un número o una cadena con un número: `12`, `"4.5"` | Un número |
| `bool` | «Sí/No» | `true` o `false` (también sirven `1` y `0`) | `true` o `false` |
| `date` | «Fecha» | Una fecha en cualquier formato habitual: `"2026-10-15"` | Una fecha y hora en UTC: `"2026-10-15T00:00:00.000000Z"` |
| `datetime` | «Fecha y hora» | Una fecha y hora: `"2026-10-15 14:30"` o `"2026-10-15T14:30:00-05:00"` | Una fecha y hora en UTC |
| `money` | «Dinero» | Un importe en dólares, euros, etc.: `4.5` o `12.99` | El importe en las mismas unidades: `4.5` |
| `file` | «Archivo» | Un objeto con un enlace; ver más abajo | Un objeto que describe el archivo |
| `image` | «Imagen» | Un objeto con un enlace; ver más abajo | Un objeto que describe el archivo |
| `contact` | «ID del contacto» | Un ID de contacto | El ID del contacto |
| `bot` | «ID del bot» | Un ID de bot | El ID del bot |

Un campo vacío se devuelve como `null`.

### Fecha y hora

Una hora sin zona horaria se trata como UTC: `"2026-10-15 14:30"` se guarda como 14:30 UTC. Para enviar la hora local, añade el desfase: `"2026-10-15T14:30:00-05:00"`. Un campo `date` no recorta la hora: si envías una fecha con hora, la hora se conserva.

### Dinero

La moneda se define en el campo al crearlo (`currency`) y no se envía con los registros. Es un código ISO 4217 de tres letras: `USD`, `EUR`, `GBP`. En `createListSchema` la moneda se puede omitir, y entonces es `USD`; en `addListSchemaField` es obligatoria. Un código desconocido: `422`.

Envía los importes en unidades principales: dólares, no céntimos. El importe se redondea a los decimales de la moneda (dos para el dólar y el euro), y las mitades se redondean hacia arriba: `0.295` se guarda como `0.30`.

### Archivos e imágenes

El valor de un campo `file` o `image` es un objeto. A través de la API solo puedes guardar un enlace a un archivo disponible en internet:

```json
{
  "url": "https://example.com/menu/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}
```

| Clave | Obligatoria | Descripción |
|---|---|---|
| `url` | sí | Un enlace `http://` o `https://` |
| `storage` | sí | Siempre `"url"` |
| `name` | no | Nombre del archivo |
| `type` | no | Tipo de archivo: `image`, `video`, `audio` o `document` |
| `mime_type` | no | Tipo MIME: `image/jpeg` |
| `size` | no | Tamaño en bytes |
| `caption` | no | Pie |

> [!WARNING]
> Sin `"storage": "url"`, o con un enlace de otro tipo (no `http`/`https`), el valor no se guarda y no hay aviso: el campo queda en `null` y no se produce ningún error.

Las demás claves (como `uuid` o `path`) se ignoran: el campo guarda solo el enlace externo, y la respuesta lo devuelve exactamente como lo enviaste. Un enlace a un archivo del almacenamiento de la plataforma (como los que contienen las respuestas para los archivos subidos en tu cuenta) solo se puede guardar dentro de tu propia cuenta; un enlace a un archivo de otra cuenta no se guarda, y el campo queda en `null`. Si envías a `updateListItem` el archivo que ya está en el registro, por ejemplo un registro completo de `getListItems`, se queda como estaba.

En las respuestas, un archivo se describe con un objeto con las claves `type`, `mime_type`, `created_at`, `name`, `size`, `storage`, `caption`, `meta` (ancho, alto, duración, códec) y `url`. Los enlaces a archivos subidos en tu cuenta son temporales: descarga el archivo de inmediato o vuelve a pedir el registro.

### Contacto y bot

Los campos `contact` y `bot` reciben un ID. El contacto debe pertenecer a tu bot y el bot debe ser tuyo; si no, la respuesta es `403`. Un ID que no existe no pasa la validación: `422`.

Además del valor del propio campo, el registro recibe las claves de servicio `contact_id` o `bot_id`; el filtro de [`getListItems`](10-items.md#getlistitems) funciona sobre ellas. Si una lista tiene varios campos de este tipo, contienen el valor del último.

## Configuración del campo

| Parámetro | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `is_required` | booleano | `true` | «Campo obligatorio»: no se añade un registro sin valor |
| `is_hidden` | booleano | `false` | «Ocultar campo en la interfaz»: el campo no se muestra en la tabla de registros de tu cuenta. La API lo devuelve como siempre |
| `is_encryptable` | booleano | `false` | «Cifrar campo»: el valor se guarda cifrado. La API lo devuelve descifrado. En tu cuenta, el cifrado solo existe para los tipos `string` y `number`: úsalo solo para ellos. Los filtros no funcionan en campos cifrados |

> [!IMPORTANT]
> Por defecto, un campo creado a través de la API es obligatorio, a diferencia de tu cuenta. Si un campo puede quedar vacío, envía `"is_required": false`.

## Límites

- Hasta 5000 listas por proyecto.
- De 1 a 30 campos al crear una lista.
- Nombres de listas y campos: hasta 255 caracteres.
- No se pueden usar nombres de campos de servicio: `id`, `_id`, `contact`, `contact_id`, `bot`, `bot_id`, `user`, `user_id`, `project`, `project_id`, `data`, `schema_id`, `created_at`, `updated_at`, `deleted_at` ni cualquier nombre que empiece por `__`. Para ese `slug`, la API responde con `422` y el texto «The slug is reserved.».

Las reglas generales (la clave, la frecuencia de solicitudes, los códigos de error) se describen en la página [API](https://support.jetbot24.ru/es/api#errores).

## Métodos

| Método | Qué hace |
|---|---|
| [`getListSchemas`](05-schemas.md#getlistschemas) | Todas las listas de tus proyectos |
| [`getListSchema`](05-schemas.md#getlistschema) | Una lista con sus campos |
| [`createListSchema`](05-schemas.md#createlistschema) | Crear una lista |
| [`deleteListSchema`](05-schemas.md#deletelistschema) | Eliminar una lista |
| [`addListSchemaField`](05-schemas.md#addlistschemafield) | Añadir un campo |
| [`deleteListSchemaField`](05-schemas.md#deletelistschemafield) | Eliminar un campo |
| [`getListItems`](10-items.md#getlistitems) | Registros de una lista con filtrado y ordenación |
| [`addListItem`](10-items.md#addlistitem) | Añadir un registro |
| [`updateListItem`](10-items.md#updatelistitem) | Actualizar un registro |
| [`deleteListItem`](10-items.md#deletelistitem) | Eliminar un registro |