API de Google Tasks, Webhooks y Zapier para usuarios avanzados

Quieres que se cree una tarea en Google Tasks cada vez que se envía un formulario. O recibir un mensaje en Slack cuando un compañero complete una tarea de la lista compartida de lanzamiento. O un script nocturno que archive las tareas vencidas en una hoja de cálculo.

Google tiene una API de Tasks que funciona. Pero no incluye webhooks, así que para saber “cuándo se completa una tarea” hay que consultar cada lista periódicamente. No sabe nada de etiquetas, asignados o tableros, porque Google Tasks no los tiene. Y cada script comienza con un proyecto en Google Cloud, una pantalla de consentimiento OAuth y una rutina para refrescar tokens.

TasksBoard ahora ofrece una API REST pública sobre tus datos de Google Tasks, con claves API personales, webhooks firmados con HMAC y una app para Zapier. Esta guía cubre lo que ofrece, cómo obtener una clave, los endpoints más útiles, cómo funcionan los webhooks y el polling, y para quién es útil. La API es parte del plan Team.

Lo que la API de TasksBoard añade a Google Tasks

La API lee y escribe las mismas listas y tareas de Google Tasks que ves en Gmail y la app de Google Tasks. Cada ID de lista y tarea es el de Google Tasks, así que todo lo que construyas será compatible con Google Tasks y otras herramientas que usen su API.

Además, expone lo que TasksBoard añade:

• Etiquetas y asignados como campos propios. Google Tasks solo guarda título, notas y fecha límite; TasksBoard almacena etiquetas y asignados dentro de las notas (etiquetas en la primera línea, luego 👤 Asignado a <email>). La API los lee y escribe como labels y assignee, así que el texto libre en notes es lo que la gente ve en el tablero.
• Tableros: qué listas muestra cada tablero de TasksBoard.
• Listas compartidas: un flag shared en cada lista, y eventos cuando un colaborador cambia una tarea compartida.
• Webhooks para task.created, task.updated, task.completed y task.deleted.

URL base: https://api.tasksboard.com/v1. Las respuestas son JSON bajo una clave data; los errores vienen como { "error": { "code", "message", "details" } }, donde code es estable y details nombra los campos inválidos en un 422.

Crea una clave API

Las claves son personales. Una clave actúa como el usuario que la creó: todo lo que esa persona pueda hacer en Google Tasks, la clave podrá hacerlo.

1. En TasksBoard, haz clic en tu avatar y abre Team, luego la pestaña API (o ve directamente a /team?tab=api).
2. Haz clic para crear una clave. Elige si puede escribir; una clave sin permiso de escritura recibirá 403 forbidden en cada operación de escritura.
3. Copia la clave. Empieza por tb_live_ y solo se muestra una vez.
4. Envíala como token bearer en cada petición:

curl https://api.tasksboard.com/v1/lists \
  -H "Authorization: Bearer tb_live_…"

En esa misma pestaña verás tus claves con sus permisos, podrás revocarlas y ver tus webhooks. Revoca una clave si sospechas que ha sido comprometida; crear una nueva solo toma unos segundos.

Los endpoints principales

Un recorrido rápido por los recursos. La referencia completa, generada desde la definición OpenAPI, está en el centro de ayuda: Referencia de la API de TasksBoard.

Cuenta

• GET /me: la cuenta a la que pertenece la clave, su plan y los permisos de la clave.

Listas

• GET /lists: tus listas de Google Tasks, con shared y boardId.
• POST /lists: crea una lista (title).
• GET /lists/{listId}: una lista específica.

Tareas

• GET /lists/{listId}/tasks: tareas abiertas por defecto; status=completed o all, updatedAfter, dueBefore, dueAfter, includeDeleted.
• POST /lists/{listId}/tasks: crea una tarea con title, notes, due, labels, assignee, parent (hacerla subtarea), previous (insertar después de una hermana).
• GET /tasks/{taskId}?listId=: una tarea específica. Google identifica una tarea por lista e ID, así que listId es obligatorio.
• PATCH /tasks/{taskId}: actualización parcial; envía null para borrar notes, due, labels o assignee; status: "open" reabre una tarea completada.
• POST /tasks/{taskId}/complete: márcala como completada.
• DELETE /tasks/{taskId}?listId=: elimínala.

Tableros

• GET /boards: tus tableros y los IDs de lista que muestra cada uno. El tablero principal siempre aparece primero.

Webhooks

• GET, POST /webhooks, y GET, PATCH, DELETE /webhooks/{webhookId}.

Crear una tarea con etiqueta y asignado se ve así:

curl -X POST https://api.tasksboard.com/v1/lists/LIST_ID/tasks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Enviar el reporte Q3", "due": "2026-10-24",
       "labels": ["❗️Importante"], "assignee": "bob@example.com"}'

El asignado debe ser colaborador de la lista (o tú). Los endpoints de lista devuelven meta.nextCursor cuando hay más resultados; pásalo como cursor con los mismos filtros.

Webhooks: recibe notificaciones cuando cambia una tarea

El polling es el punto débil de la API de Google Tasks. Un webhook lo reemplaza: TasksBoard llama a tu URL cuando se crea, actualiza, completa o elimina una tarea.

1. Registra un webhook con los eventos que necesites:

curl -X POST https://api.tasksboard.com/v1/webhooks \
  -H "Authorization: Bearer tb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/tasksboard",
       "events": ["task.created", "task.completed"]}'

2. Guarda el secret de la respuesta. Solo se devuelve una vez, en esa respuesta; también puedes proporcionar el tuyo.
3. Responde a cada entrega con cualquier código 2xx en menos de 10 segundos.

Cada entrega incluye tres cabeceras: X-TasksBoard-Event (nombre del evento), X-TasksBoard-Delivery (ID de entrega) y X-TasksBoard-Signature. El cuerpo contiene el evento, un timestamp createdAt, el número de intento, la tarea completa bajo data.task y un source: api para llamadas REST, sync para cambios en listas compartidas, poll para el polling de 15 minutos descrito abajo.

Verifica la firma

La cabecera de firma tiene la forma t=<unix seconds>,v1=<hex>, donde v1 es el HMAC-SHA256 de "<t>.<raw body>" con tu secreto. Calcula el HMAC sobre el cuerpo de la petición exactamente como se recibió, antes de cualquier parseo JSON, y rechaza timestamps demasiado antiguos:

const crypto = require("crypto")

function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"))
}

Reintentos y desactivación

Las entregas fallidas se reintentan hasta 3 veces con backoff. Tras 20 fallos consecutivos el webhook se desactiva (active: false) hasta que lo reactives con PATCH /webhooks/{id} y "active": true. La pestaña API en Team muestra cada webhook con su URL, eventos y un badge Activo o Desactivado, así que es fácil detectar endpoints caídos.

Polling para listas no compartidas

¿De dónde vienen los eventos de webhook? De tres lugares: escrituras directas en la API, cambios propagados en listas compartidas y, si lo activas, un polling de tus otras listas.

Esto último es importante. Un cambio hecho en Gmail o la app de Google Tasks en una lista no compartida no es observado por TasksBoard a menos que algo revise la lista. En la pestaña API, activa poll my lists every 15 minutes: TasksBoard revisará esas listas cada 15 minutos y emitirá eventos con source: "poll". Sin esto, solo las listas compartidas y escrituras API generan eventos.

Si solo necesitas reaccionar a cambios en listas compartidas por tu equipo, deja el polling desactivado.

Zapier

No todo el mundo quiere escribir código. La app de TasksBoard para Zapier se autentica con la misma clave API personal y ofrece:

• Disparadores: Nueva Tarea, Tarea Completada. Ambos usan GET /lists/{listId}/tasks con updatedAfter, el mismo patrón que usarías en tu propio script.
• Acciones: Crear Tarea, Completar Tarea, Crear Lista.

La integración con Zapier está en proceso de publicación. Una vez esté lista, busca TasksBoard en Zapier, pega tu clave cuando te lo pidan y elige una lista. Hasta entonces, la API REST y los webhooks cubren lo mismo, y los disparadores y acciones anteriores te dan una idea de lo que habrá. Para más opciones de automatización, consulta nuestra guía de integraciones con Google Tasks.

Prueba TasksBoard Team

Listas compartidas, roles, registro de actividad y una API REST con webhooks, sobre el Google Tasks que ya usas. Una factura para todo el equipo.

Ver planes →

Para quién es esto

La API es una función del plan Team, y su encaje es específico:

• Equipos con una lista compartida como fuente de verdad. Un webhook en task.completed con source: "sync" se dispara cuando cualquier colaborador completa una tarea, sin importar qué app usó. Ese es el gancho para un mensaje en Slack, una fila en Sheets o una actualización de ticket.
• Personas de operaciones integrando herramientas. Formularios, CRMs y mesas de ayuda pueden crear tareas con etiqueta y asignado en una llamada, y la tarea aparece en el tablero correcto y en la app de Google Tasks de esa persona.
• Desarrolladores que probaron la API de Google Tasks y se detuvieron ante el polling, la configuración OAuth o la falta de asignados. Una clave, una cabecera, los mismos IDs de Google.

No es para reemplazar completamente la API de Google. Si solo necesitas tus propias tareas en un script personal y ya tienes un cliente OAuth, la API de Google es gratuita y cumple. Nuestra guía para exportar Google Tasks cubre los casos puntuales.

Preguntas frecuentes

Conclusión

Google Tasks tiene una API, pero sin webhooks, sin etiquetas o asignados, y con un coste de configuración que frena muchas automatizaciones pequeñas. La API de TasksBoard mantiene los IDs de Google y añade lo que falta: una clave personal que creas en un minuto, endpoints para listas, tareas y tableros, webhooks verificables, polling opcional para listas no compartidas y una app para Zapier en camino.

Crea una clave en la pestaña API de Team, haz una llamada GET /lists, y lo demás sigue de la referencia de la API.