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.

getListSchemas

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

GETPOSThttps://watbot.org/es/api/v1/getListSchemas

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

Solicitud

curl -X POST "https://watbot.org/es/api/v1/getListSchemas" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

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.

GETPOSThttps://watbot.org/es/api/v1/getListSchema

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

Solicitud

curl -X POST "https://watbot.org/es/api/v1/getListSchema" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'

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"
  }
}

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.

GETPOSThttps://watbot.org/es/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
`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

Solicitud

curl -X POST "https://watbot.org/es/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}
    ]
  }'

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"
  }
}

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.

GETPOSThttps://watbot.org/es/api/v1/deleteListSchema

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

Solicitud

curl -X POST "https://watbot.org/es/api/v1/deleteListSchema" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'

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.
La lista pertenece a un proyecto ajeno: 403.

addListSchemaField

Añade un campo al final de la lista.

GETPOSThttps://watbot.org/es/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`

Solicitud

curl -X POST "https://watbot.org/es/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}
  }'

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.

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; la lista pertenece a un proyecto ajeno: 403.

deleteListSchemaField

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

GETPOSThttps://watbot.org/es/api/v1/deleteListSchemaField

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

Solicitud

curl -X POST "https://watbot.org/es/api/v1/deleteListSchemaField" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "volume"}'

Respuesta 422

{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}

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

Advertencia

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.

Errores:

No hay ningún campo con este slug: 422 con un error en slug.
La lista no existe: 404, como en getListSchema; la lista pertenece a un proyecto ajeno: 403.

Listas y campos#

getListSchemas#

getListSchema#

createListSchema#

deleteListSchema#

addListSchemaField#

deleteListSchemaField#

Listas y campos

getListSchemas

getListSchema

createListSchema

deleteListSchema

addListSchemaField

deleteListSchemaField