La API de tokidu

Empezar

1. En Cuenta → Integraciones, crea un token y marca «Ver tus proyectos y tareas» (y «Crear y cambiar tareas», si va a escribir).
2. Cópialo, porque solo se enseña una vez, y guárdalo como una contraseña. En los ejemplos va en la variable TOKIDU_TOKEN.
3. Pruébalo pidiendo tu cuenta:

curl https://tokidu.com/api/v1/me \
  -H "Authorization: Bearer $TOKIDU_TOKEN"

Llámala desde un servidor o un script, no desde una página web: la API no admite CORS y no mira las cookies.

Tokens y ámbitos

Al crear un token eliges qué puede hacer, a qué proyectos llega y cuándo caduca:

• read, «Ver tus proyectos y tareas»: leer los proyectos, las tareas y «Lo siguiente».
• write, «Crear y cambiar tareas»: crear proyectos y tareas, cambiarlas, terminarlas, reabrirlas y borrarlas, como en la web.
• Proyectos: todos los que ves o solo los que marques. Si dejas de ver uno, el token deja de llegar a él.
• Caducidad: a los 30, 90 o 365 días. Si no eliges, al año.

El token de Madrugo (integrations:read) solo lee «Lo siguiente» para Madrugo, de todos los proyectos que ves: no abre esta API y no se puede limitar a unos proyectos.

Puedes tener 10 tokens activos. Revócalos de uno en uno o todos a la vez, y mira en cada uno sus últimos cambios: guardamos qué cambios se hicieron con cada token, sin el contenido, durante 90 días.

Límites

• 1000 peticiones por hora para toda tu cuenta y 60 por minuto para cada token.
• Cada respuesta lleva RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset: el límite, lo que queda y cuándo se renueva.
• Si te pasas, la respuesta es 429 demasiadas_peticiones con Retry-After: espera esos segundos y vuelve a probar.
• El cuerpo de una petición puede ocupar 64 KiB como mucho.

Crear tareas sin duplicarlas

Crear una tarea exige la cabecera Idempotency-Key: de 1 a 100 caracteres, distinta para cada tarea que quieres crear (por ejemplo, el id de la fila, del correo o del formulario de donde sale).

Si repites la petición con la misma clave, por ejemplo tras un corte de red, no se crea otra: te devuelve la que ya existe, con 200 e Idempotent-Replayed: true.

Si la tarea de esa clave se borró, no vuelve: la respuesta es 410 tarea_borrada. La misma clave en otro proyecto crea otra tarea.

Errores

Un error responde con su código HTTP y el campo error del cuerpo; con 422, también field, el campo que no vale.

401 token_invalido

Falta el token, no existe, está revocado o ha caducado (no se dice cuál).

403 ambito

Al token le falta el ámbito que pide la ruta.

403 proyecto_fuera_del_token

El token está limitado a otros proyectos.

403 max_necesario

Es del plan Max y quien comparte el proyecto no lo tiene (o tú, al crear un proyecto).

403 solo_lectura

En ese proyecto solo puedes ver, no cambiar.

403 en_pausa

El proyecto está en pausa: quien lo comparte ya no tiene el plan Equipo, así que solo se puede ver.

404 proyecto_inexistente

El proyecto no existe o no lo ves.

404 tarea_inexistente

La tarea no existe o no la ves.

404 ruta_inexistente

Esa ruta no es de la API: revisa el método y la dirección.

404 webhook_inexistente

Ese aviso no existe o no lo creó este token.

409 id_ocupado

Esa Idempotency-Key corresponde a una tarea que no ves: usa otra.

409 horas_de_otros

No se puede borrar porque tiene horas de otras personas, como en la web.

409 adjuntos_de_otros

No se puede borrar porque tiene archivos de otras personas, como en la web.

409 entrada_facturada

No se puede borrar porque tiene horas ya facturadas, como en la web.

409 ciclo

Esa espera cerraría un círculo: una tarea acabaría esperándose a sí misma.

409 webhooks_completo

Ya tienes 20 avisos: borra alguno para crear otro.

410 tarea_borrada

Esa Idempotency-Key es de una tarea que se borró: no se vuelve a crear. Para crear otra, usa otra clave.

413 cuerpo_grande

El cuerpo pasa de 64 KiB.

415 json_necesario

El cuerpo tiene que ir en JSON, con Content-Type: application/json.

422 peticion_invalida

Un campo no vale: field dice cuál.

422 url_no_valida

La dirección de un aviso no vale: reason dice por qué (https, puerto, usuario, local, tokidu, dns o ip_privada).

428 idempotencia_necesaria

Para crear una tarea falta la cabecera Idempotency-Key.

429 demasiadas_peticiones

Te has pasado del límite: espera lo que diga Retry-After.

429 demasiados_intentos

Has comprobado muchas direcciones de avisos seguidas: espera lo que diga Retry-After.

503 ocupado

El proyecto estaba ocupado con otro cambio: repite la petición pasado lo que diga Retry-After.

503 no_disponible

El servicio no ha podido responder ahora: repite la petición pasado lo que diga Retry-After.

Referencia

Todas las rutas van detrás de la dirección base y responden en JSON. Los ids de proyectos y tareas son los que devuelve la propia API.

curl "https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks?status=open" \
  -H "Authorization: Bearer $TOKIDU_TOKEN"

curl https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks \
  -H "Authorization: Bearer $TOKIDU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-42" \
  -d '{"title":"Llamar a Ana","due":"2026-10-20"}'

curl -X PATCH https://tokidu.com/api/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $TOKIDU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"due":"2026-10-24"}'

curl -X POST https://tokidu.com/api/v1/tasks/$TASK_ID/done \
  -H "Authorization: Bearer $TOKIDU_TOKEN"

Avisos a otras apps (webhooks)

Cuando pasa algo en tus proyectos, tokidu manda un POST firmado a la dirección que digas. Se crean en Cuenta → Integraciones, o por la API con un token con el ámbito webhooks (lo que usan Zapier o Make). Solo el dueño con Max, y solo de sus proyectos; hasta 20 por cuenta.

Qué puedes escuchar

• task.created · Se crea una tarea
• task.done · Se termina una tarea
• task.reopened · Se reabre una tarea
• task.unblocked · Se desbloquea una tarea
• task.assigned · Se asigna una tarea
• task.deleted · Se borra una tarea
• project.status · Cambia el semáforo de un proyecto

Cada aviso lleva el tipo, un id del hecho, la hora, el proyecto y, si es de una tarea, su título, estado, responsable, fecha límite y enlace. Nunca notas, enlaces, archivos, correos ni horas.

Comprobar la firma

Sigue Standard Webhooks: cabeceras webhook-id, webhook-timestamp (segundos) y webhook-signature (v1, y un HMAC-SHA256 en base64 de id.timestamp.cuerpo, con la clave que va detrás de whsec_). Compruébala con el cuerpo tal cual llega y rechaza los de más de 5 minutos. En Node:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyTokidu(secret, headers, body, toleranceSeconds = 300) {
  const id = headers["webhook-id"], ts = headers["webhook-timestamp"], sigs = headers["webhook-signature"];
  if (!id || !ts || !sigs) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest();
  return sigs.split(" ").some((s) => {
    const [version, sig] = s.split(",");
    const given = Buffer.from(sig ?? "", "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

Envíos y reintentos

Cualquier 2xx es bueno; las redirecciones no se siguen. Si falla, se reintenta a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Con 20 entregas fallidas seguidas, o 3 días sin un 2xx, el aviso se apaga y te mandamos un correo.

Solo direcciones https:// públicas, en el puerto 443 u 8443, sin usuario ni contraseña: nada de localhost, redes internas ni IP privadas (se comprueba también al enviar).

OpenAPI

Todos los campos de cada petición y de cada respuesta, en formato OpenAPI, para generar un cliente o importarlos en tu herramienta: /api/v1/openapi.json.