# Listas y campos

Los métodos de esta página trabajan con el esquema de una lista: su nombre y sus campos. Cómo funcionan los campos y qué tipos tienen se describe en la página [Listas](https://support.jetbot24.ru/es/api/lists#tipos-de-campo).

## getListSchemas

Devuelve las listas de todos los proyectos del propietario de la clave, 50 por página.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `page` | entero | no | Número de página, `1` por defecto |

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

```json title="Respuesta 200"
{
  "data": [
    {
      "id": "6650a1f2c3d4e5f6a7b8c9d0",
      "fields": {
        "title": {
          "name": "Nombre",
          "type": "string",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        },
        "price": {
          "name": "Precio",
          "type": "money",
          "currency": "USD",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        }
      },
      "name": "Carta de la cafetería",
      "bot_id": 12345,
      "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
      "is_menu": false,
      "created_at": "2026-10-01T09:15:00+00:00",
      "updated_at": "2026-10-02T11:40:12+00:00"
    }
  ],
  "links": {
    "first": "…/v1/getListSchemas?page=1",
    "last": "…/v1/getListSchemas?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "…/v1/getListSchemas",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}
```

Campos de la lista en la respuesta:

| Campo | Descripción |
|---|---|
| `id` | ID de la lista |
| `fields` | Campos: la clave es el `slug`, y el valor contiene el nombre (`name`), el tipo (`type`) y la configuración. Un campo de dinero también tiene `currency`. Los campos creados en tu cuenta pueden tener también otras claves |
| `name` | Nombre de la lista |
| `bot_id` | El bot en el que se creó la lista; `null` si la lista se creó en el proyecto |
| `project` | UUID del proyecto al que pertenece la lista |
| `is_menu` | Un indicador obsoleto; no afecta al funcionamiento de la lista |
| `created_at`, `updated_at` | Cuándo se creó la lista y cuándo cambió por última vez |

Notas:

- El tamaño de página es de 50 listas y no se puede cambiar. El número total de páginas está en `meta.last_page`, y la dirección de la página siguiente, en `links.next`.
- No se incluyen las listas de los proyectos a los que te invitaron como miembro del equipo: la API solo trabaja con los proyectos del propietario de la clave.

## getListSchema

Devuelve una lista con sus campos.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |

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

```json title="Respuesta 200"
{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "title": {
        "name": "Nombre",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "price": {
        "name": "Precio",
        "type": "money",
        "currency": "USD",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Carta de la cafetería",
    "bot_id": 12345,
    "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "is_menu": false,
    "created_at": "2026-10-01T09:15:00+00:00",
    "updated_at": "2026-10-02T11:40:12+00:00"
  }
}
```

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

Errores:

- La lista no existe o se eliminó: `404`. El texto del error está en `error` y `message`; por compatibilidad, también en `errors.schema_id`.
- La lista pertenece a un proyecto ajeno: `403`.

## createListSchema

Crea una lista con campos, en un proyecto o en un bot.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `name` | cadena | sí | Nombre de la lista, hasta 255 caracteres |
| `project_uuid` | cadena | sí, si no hay `bot_id` | UUID del proyecto en el que crear la lista |
| `bot_id` | entero | sí, si no hay `project_uuid` | ID del bot: la lista va al proyecto de este bot y se marca como creada en él. Si se envían ambos parámetros, se usa `bot_id` |
| `fields` | array | sí | Campos de la lista, de 1 a 30 |
| `fields[].name` | cadena | sí | Nombre del campo, hasta 255 caracteres |
| `fields[].slug` | cadena | sí | Slug del campo: letras, dígitos, `-` y `_`, hasta 255 caracteres; mejor con letras latinas. Debe ser único dentro de la lista y no coincidir con los [nombres de servicio](https://support.jetbot24.ru/es/api/lists#límites) |
| `fields[].type` | cadena | sí | Tipo de campo: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot` |
| `fields[].currency` | cadena | no | Solo para `money`: un código de moneda ISO 4217 de tres letras, `USD`, `EUR`, `GBP`. Por defecto, `USD`. Un código desconocido: `422` |
| `fields[].is_required` | booleano | no | Campo obligatorio. Por defecto, `true` |
| `fields[].is_hidden` | booleano | no | Ocultar el campo en la interfaz. Por defecto, `false` |
| `fields[].is_encryptable` | booleano | no | Guardar el valor cifrado. Por defecto, `false` |
| `is_menu` | booleano | no | Un indicador obsoleto; no afecta al funcionamiento de la lista |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/createListSchema" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "name": "Carta de la cafetería",
    "fields": [
      {"name": "Nombre", "slug": "title", "type": "string"},
      {"name": "Precio", "slug": "price", "type": "money", "currency": "USD"},
      {"name": "Foto", "slug": "photo", "type": "image", "is_required": false},
      {"name": "Disponible", "slug": "in_stock", "type": "bool", "is_required": false}
    ]
  }'
```

```json title="Respuesta 201"
{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "title": {
        "name": "Nombre",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "price": {
        "name": "Precio",
        "type": "money",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false,
        "currency": "USD"
      },
      "photo": {
        "name": "Foto",
        "type": "image",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      },
      "in_stock": {
        "name": "Disponible",
        "type": "bool",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Carta de la cafetería",
    "bot_id": null,
    "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "is_menu": false,
    "created_at": "2026-10-03T08:00:00+00:00",
    "updated_at": "2026-10-03T08:00:00+00:00"
  }
}
```

```json title="Respuesta 422"
{
  "message": "The slug is reserved.",
  "errors": {
    "fields.0.slug": ["The slug is reserved."]
  }
}
```

Notas y errores:

- Los campos se añaden a la lista en el orden en que se envían.
- Solo puedes crear una lista en tu propio proyecto o en tu propio bot. Un bot o proyecto de otra cuenta, incluido uno al que te invitaron como miembro del equipo: `403`.
- Un `bot_id` o `project_uuid` que no existe: `422`.
- Un `slug` repetido: `422` con un error en el campo `fields.N.slug`, donde N es la posición del campo en el array, empezando por cero.
- Un código de moneda desconocido: `422` con un error en el campo `fields.N.currency`.
- El proyecto ya tiene 5000 listas: `403`, `{"message": "A project cannot have more than 5000 lists", "error": "A project cannot have more than 5000 lists"}`.
- En una solicitud `GET`, los campos se pasan en la dirección así: `fields[0][name]=Title&fields[0][slug]=title&fields[0][type]=string`. Es más fácil enviar `POST` con JSON.

## deleteListSchema

Elimina una lista junto con sus registros.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |

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

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

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

Notas y errores:

- Antes de eliminarla, asegúrate de que la lista no esté seleccionada en ningún bloque del bot: tras eliminarla, los bloques no encontrarán registros.
- Tras la eliminación, los registros de la lista no se encuentran ni con `getListItems` ni por `item_id`: `updateListItem` y `deleteListItem` responden con `404`.
- La lista no existe o ya se eliminó: `404`, como en [`getListSchema`](#getlistschema).
- La lista pertenece a un proyecto ajeno: `403`.

## addListSchemaField

Añade un campo al final de la lista.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |
| `field` | objeto | sí | El campo nuevo |
| `field.name` | cadena | sí | Nombre del campo, hasta 255 caracteres |
| `field.slug` | cadena | sí | Slug del campo: letras, dígitos, `-` y `_`, hasta 255 caracteres; mejor con letras latinas |
| `field.type` | cadena | sí | Tipo de campo, como en `createListSchema` |
| `field.is_required` | booleano | no | Campo obligatorio. Por defecto, `true` |
| `field.is_hidden` | booleano | no | Ocultar el campo en la interfaz. Por defecto, `false` |
| `field.is_encryptable` | booleano | no | Guardar el valor cifrado. Por defecto, `false` |
| `field.currency` | cadena | para `money` | Solo para `money`: un código de moneda ISO 4217 de tres letras, `USD`, `EUR`, `GBP` |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/addListSchemaField" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "field": {"name": "Tamaño, oz", "slug": "volume", "type": "number", "is_required": false}
  }'
```

```json title="Respuesta 422"
{
  "message": "The list already has a field with this slug",
  "errors": {
    "field.slug": ["The list already has a field with this slug"]
  }
}
```

Una respuesta correcta tiene el código `204` y no tiene cuerpo. Para ver la lista con el campo nuevo, llama a [`getListSchema`](#getlistschema).

Notas y errores:

- Ya existe un campo con este `slug`: `422` con un error en `field.slug`.
- Un campo `money` necesita una moneda en `field.currency`: sin ella, o con un código desconocido, `422` con un error en `field.currency`.
- Si el campo nuevo es obligatorio, tendrás que rellenarlo cada vez que añadas un registro. Los registros que ya están en la lista no cambian.
- La lista no existe: `404`, como en [`getListSchema`](#getlistschema); la lista pertenece a un proyecto ajeno: `403`.

## deleteListSchemaField

Elimina un campo de la lista y borra sus valores en todos los registros.

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

| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `schema_id` | cadena | sí | ID de la lista |
| `slug` | cadena | sí | Slug del campo |

```bash title="Solicitud"
curl -X POST "https://app.jetbot24.ru/api/v1/deleteListSchemaField" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "volume"}'
```

```json title="Respuesta 422"
{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}
```

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

> [!WARNING]
> Los valores del campo se borran en todos los registros a la vez. No se pueden restaurar, igual que cuando [eliminas un campo en tu cuenta](https://support.jetbot24.ru/es/lists/create#eliminar-un-campo).

Errores:

- No hay ningún campo con este `slug`: `422` con un error en `slug`.
- La lista no existe: `404`, como en [`getListSchema`](#getlistschema); la lista pertenece a un proyecto ajeno: `403`.