Ir al contenido

Gestiona las tareas cron

Lista, añade, cambia, desactiva y elimina los comandos programados (tareas cron) de una cuenta de hosting a través de la API y sigue su última ejecución.

Esta guía muestra cómo gestionar con la API las tareas cron de una cuenta de hosting. Una tarea cron ejecuta un comando según un horario dentro del contenedor web de un sitio, como el usuario del sitio.

  • Una clave de API con el scope crons:read para listar las tareas cron y crons:write para añadirlas, cambiarlas o eliminarlas (scopes).
  • El id de la cuenta y el id del sitio que ejecuta el comando. Los obtienes con GET /api/v1/accounts y GET /api/v1/accounts/{account_id}/sites.
  • Un plan que permita tareas cron. Sin él, añadir una tarea responde 403 plan_feature_disabled.
export PLUSPANEL_URL="https://panel.example.com"
export PLUSPANEL_API_KEY="ppk_…"
export ACCOUNT_ID="5a5a5a5a-1111-4222-8333-444455556666"
export SITE_ID="6b6b6b6b-1111-4222-8333-444455556666"

GET /api/v1/accounts/{id}/crons devuelve todas las tareas cron de la cuenta, con el resultado de su última ejecución.

curl -fsS "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"
{
  "items": [
    {
      "id": "8d8d8d8d-1111-4222-8333-444455556666",
      "account_id": "5a5a5a5a-1111-4222-8333-444455556666",
      "site_id": "6b6b6b6b-1111-4222-8333-444455556666",
      "schedule": "*/15 * * * *",
      "command": "echo hello from cron",
      "enabled": true,
      "source": "user",
      "last_run_at": "2026-11-14T09:45:00Z",
      "last_exit": 0
    }
  ],
  "sync": { "state": "applied" }
}
  • last_run_at y last_exit están vacíos (null) hasta que la tarea se ha ejecutado una vez. Un código de salida distinto de 0 significa que el comando falló; su salida está en el cron.log del sitio.
  • source es user para las tareas que añadiste tú y migration para las que trajo una migración de cPanel.
  • sync.state indica si el servidor ha aplicado la lista: applied, pending o failed.

POST /api/v1/accounts/{id}/crons añade una tarea. site_id, schedule y command son obligatorios; enabled es true por defecto.

curl -fsS -X POST "$PLUSPANEL_URL/api/v1/accounts/$ACCOUNT_ID/crons" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"site_id": "'"$SITE_ID"'", "schedule": "*/15 * * * *", "command": "echo hello from cron"}'

La respuesta es 201, con la nueva tarea en cron y un job_id: el servidor aplica el cambio como un job, así que la tarea cron llega al servidor un instante después. Guarda el id de la nueva tarea como CRON_ID para los pasos siguientes.

  • schedule son cinco campos (minuto, hora, día del mes, mes, día de la semana) o uno de @hourly, @daily, @weekly, @monthly, @yearly. @reboot no está soportado. Las horas son UTC.
  • command es texto imprimible de 1024 bytes como máximo. Un comando se ejecuta durante una hora como máximo.
  • Una cuenta tiene como máximo 100 tareas cron.

PATCH /api/v1/crons/{id} cambia cualquiera de schedule, command, site_id y enabled; los miembros que omitas se quedan como están. Desactivar mantiene la tarea en la lista.

curl -fsS -X PATCH "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}'

La respuesta tiene la misma forma que la de una tarea nueva: cron y job_id. Para enviar el cambio solo si nadie más ha modificado la tarea mientras tanto, usa una cabecera If-Match.

curl -fsS -X DELETE "$PLUSPANEL_URL/api/v1/crons/$CRON_ID" \
  -H "Authorization: Bearer $PLUSPANEL_API_KEY"

La respuesta es 204, sin cuerpo.

Un cambio responde antes de que el servidor lo haya aplicado. Para esperarlo, consulta el job_id con GET /api/v1/jobs/{id} (scope jobs:read) hasta que su status sea final, o vigila GET .../crons hasta que sync.state sea applied. Una aplicación fallida aparece como sync.state: "failed".

Estado Código Qué significa
401 invalid_api_key La clave falta, ha caducado o se ha revocado.
403 plan_feature_disabled El plan de la cuenta no permite tareas cron.
403 La clave no tiene scope crons, o el usuario no puede gestionar esta cuenta.
404 La cuenta o la tarea cron no existe o no es visible para ti.
409 crons_unsupported_agent El agente del servidor no ejecuta tareas cron.
409 conflict La cuenta ya tiene 100 tareas cron.
422 validation_failed El horario o el comando no es válido, o el sitio no es de la cuenta.

Los errores son problem details: decide según code.

Cuando el servidor ha aplicado un cambio, el job termina y se envía un evento job.succeeded (job.failed si falló); data.object_id es el job_id de la respuesta. Suscríbete a ellos como se describe en webhooks.