A API de tokidu

Comezar

1. En Conta → Integracións, crea un token e marca «Ver os teus proxectos e tarefas» (e «Crear e cambiar tarefas», se vai escribir).
2. Cópiao, porque só se amosa unha vez, e gárdao como un contrasinal. Nos exemplos vai na variable TOKIDU_TOKEN.
3. Próbao pedindo a túa conta:

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

Chámaa desde un servidor ou un script, non desde unha páxina web: a API non admite CORS e non mira as cookies.

Tokens e ámbitos

Ao crear un token escolles que pode facer, a que proxectos chega e cando caduca:

• read, «Ver os teus proxectos e tarefas»: ler os proxectos, as tarefas e «O seguinte».
• write, «Crear e cambiar tarefas»: crear proxectos e tarefas, cambialas, rematalas, reabrilas e borralas, como na web.
• Proxectos: todos os que ves ou só os que marques. Se deixas de ver un, o token deixa de chegar a el.
• Caducidade: aos 30, 90 ou 365 días. Se non escolles, ao ano.

O token de Madrugo (integrations:read) só le «O seguinte» para Madrugo, de todos os proxectos que ves: non abre esta API e non se pode limitar a uns proxectos.

Podes ter 10 tokens activos. Revógaos dun en un ou todos á vez, e mira en cada un os seus últimos cambios: gardamos que cambios se fixeron con cada token, sen o contido, durante 90 días.

Límites

• 1000 peticións por hora para toda a túa conta e 60 por minuto para cada token.
• Cada resposta leva RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset: o límite, o que queda e cando se renova.
• Se te pasas, a resposta é 429 demasiadas_peticiones con Retry-After: espera eses segundos e volve probar.
• O corpo dunha petición pode ocupar 64 KiB como moito.

Crear tarefas sen duplicalas

Crear unha tarefa esixe a cabeceira Idempotency-Key: de 1 a 100 caracteres, distinta para cada tarefa que queres crear (por exemplo, o id da fila, do correo ou do formulario de onde sae).

Se repites a petición coa mesma clave, por exemplo despois dun corte de rede, non se crea outra: devólveche a que xa existe, con 200 e Idempotent-Replayed: true.

Se a tarefa desa clave se borrou, non volve: a resposta é 410 tarea_borrada. A mesma clave noutro proxecto crea outra tarefa.

Erros

Un erro responde co seu código HTTP e o campo error do corpo; con 422, tamén field, o campo que non vale.

401 token_invalido

Falta o token, non existe, está revogado ou caducou (non se di cal).

403 ambito

Ao token fáltalle o ámbito que pide a ruta.

403 proyecto_fuera_del_token

O token está limitado a outros proxectos.

403 max_necesario

É do plan Max e quen comparte o proxecto non o ten (ou ti, ao crear un proxecto).

403 solo_lectura

Nese proxecto só podes ver, non cambiar.

403 en_pausa

O proxecto está en pausa: quen o comparte xa non ten o plan Equipo, así que só se pode ver.

404 proyecto_inexistente

O proxecto non existe ou non o ves.

404 tarea_inexistente

A tarefa non existe ou non a ves.

404 ruta_inexistente

Esa ruta non é da API: revisa o método e o enderezo.

404 webhook_inexistente

Ese aviso non existe ou non o creou este token.

409 id_ocupado

Esa Idempotency-Key corresponde a unha tarefa que non ves: usa outra.

409 horas_de_otros

Non se pode borrar porque ten horas doutras persoas, como na web.

409 adjuntos_de_otros

Non se pode borrar porque ten ficheiros doutras persoas, como na web.

409 entrada_facturada

Non se pode borrar porque ten horas xa facturadas, coma na web.

409 ciclo

Esa espera pecharía un círculo: unha tarefa acabaría esperando por si mesma.

409 webhooks_completo

Xa tes 20 avisos: borra algún para crear outro.

410 tarea_borrada

Esa Idempotency-Key é dunha tarefa que se borrou: non se volve crear. Para crear outra, usa outra clave.

413 cuerpo_grande

O corpo pasa de 64 KiB.

415 json_necesario

O corpo ten que ir en JSON, con Content-Type: application/json.

422 peticion_invalida

Un campo non vale: field di cal.

422 url_no_valida

O enderezo dun aviso non vale: reason di por que (https, puerto, usuario, local, tokidu, dns ou ip_privada).

428 idempotencia_necesaria

Para crear unha tarefa falta a cabeceira Idempotency-Key.

429 demasiadas_peticiones

Pasácheste do límite: espera o que diga Retry-After.

429 demasiados_intentos

Comprobaches moitos enderezos de avisos seguidos: agarda o que diga Retry-After.

503 ocupado

O proxecto estaba ocupado con outro cambio: repite a petición pasado o que diga Retry-After.

503 no_disponible

O servizo non puido responder agora: repite a petición pasado o que diga Retry-After.

Referencia

Todas as rutas van detrás do enderezo base e responden en JSON. Os ids de proxectos e tarefas son os que devolve a 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":"Chamar 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 outras apps (webhooks)

Cando pasa algo nos teus proxectos, tokidu manda un POST asinado ao enderezo que digas. Créanse en Conta → Integracións, ou pola API cun token co ámbito webhooks (o que usan Zapier ou Make). Só o dono con Max, e só dos seus proxectos; ata 20 por conta.

Que podes escoitar

• task.created · Créase unha tarefa
• task.done · Remátase unha tarefa
• task.reopened · Reábrese unha tarefa
• task.unblocked · Desbloquéase unha tarefa
• task.assigned · Asígnase unha tarefa
• task.deleted · Bórrase unha tarefa
• project.status · Cambia o semáforo dun proxecto

Cada aviso leva o tipo, un id do feito, a hora, o proxecto e, se é dunha tarefa, o seu título, estado, responsable, data límite e ligazón. Nunca notas, ligazóns, ficheiros, correos nin horas.

Comprobar a sinatura

Segue Standard Webhooks: cabeceiras webhook-id, webhook-timestamp (segundos) e webhook-signature (v1, e un HMAC-SHA256 en base64 de id.timestamp.corpo, coa clave que vai detrás de whsec_). Compróbaa co corpo tal como chega e rexeita os de máis 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 e reintentos

Calquera 2xx é bo; as redireccións non se seguen. Se falla, reinténtase a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Con 20 entregas falladas seguidas, ou 3 días sen un 2xx, o aviso apágase e mandámosche un correo.

Só enderezos https:// públicos, no porto 443 ou 8443, sen usuario nin contrasinal: nada de localhost, redes internas nin IP privadas (compróbase tamén ao enviar).

OpenAPI

Todos os campos de cada petición e de cada resposta, en formato OpenAPI, para xerar un cliente ou importalos na túa ferramenta: /api/v1/openapi.json.