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.

getListItems#

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

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

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

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

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

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:

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.

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

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

{
  "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.

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

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

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

{
  "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.

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

{
  "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.
• El registro pertenece a una lista de un proyecto ajeno: 403.