API de Melonhelp Tasks

Próximamente. Melonhelp Tasks todavía no está disponible. Va a vivir en tasks.melonhelp.com y esta página describe cómo va a funcionar cuando salga.

Tasks tiene una API REST para que otras aplicaciones, scripts y tareas programadas lean y modifiquen tus tableros: tableros, listas, tarjetas, etiquetas, checklists, campos personalizados, comentarios y adjuntos. Te conectas con una clave de API personal.

Claves de API personales

Cada persona crea sus claves desde el botón API del encabezado de Tasks. Una clave empieza con tsk_ y actúa con tus permisos: solo ve y modifica los tableros de los que eres miembro, con el rol que tienes en cada uno.

Opción	Qué define
Nombre	Para reconocerla, hasta 60 caracteres
Permiso	`read`, solo lectura (por defecto), o `write`, lectura y escritura
Tableros	Todos tus tableros o solo algunos
Vencimiento	Nunca, 30 días, 90 días o 1 año

El token completo se muestra una sola vez, al crear la clave. Guárdalo en un lugar seguro: Tasks guarda solo una huella (hash) y en la lista ves el prefijo, el último uso y el vencimiento.
Puedes tener hasta 20 claves y revocar cualquiera cuando quieras.
Una clave deja de funcionar cuando la revocas, cuando vence o si tu cuenta se bloquea o se elimina.
Una clave de solo lectura puede hacer peticiones GET. Cualquier otra responde 403.
Con una clave no se pueden crear ni revocar claves, ni entrar a la administración.
Los cambios hechos con una clave aparecen en vivo en los tableros que otras personas tienen abiertos.
Estas claves son solo de Tasks. No sirven en la API de Tickets ni en la de Agents.

Claves limitadas a tableros

Al crear una clave puedes elegir Solo algunos y marcar hasta 50 tableros de los que seas miembro. Así una integración solo toca lo que necesita:

Fuera de esos tableros todo responde 404, igual que un tablero ajeno.
GET /boards lista solo esos tableros.
La clave no puede crear tableros nuevos ni mover o copiar tarjetas hacia otros tableros.
Si se eliminan todos sus tableros, la clave se queda sin acceso. Nunca pasa a tener acceso a todos.

Autenticación

Envía la clave en la cabecera Authorization de cada petición:

Authorization: Bearer tsk_...

Todas las rutas parten de https://tasks.melonhelp.com/api y usan JSON, salvo la subida de adjuntos, que va como multipart/form-data. Los errores responden con { "error": "mensaje" }.

Código	Qué significa
400	Datos inválidos
401	Falta la clave o no es válida
403	Sin permiso: tu rol no alcanza o la clave es de solo lectura
404	No existe o no tienes acceso
409	Conflicto: el registro ya existe, u otra petición cambió lo mismo al mismo tiempo (por ejemplo, movió la tarjeta a otro tablero)
429	Demasiadas peticiones seguidas, o el máximo diario de invitaciones a correos nuevos
503	Servicio ocupado o sin conexión con la cuenta Melonhelp. Vuelve a intentarlo en unos segundos

Swagger

La documentación interactiva va a estar en https://tasks.melonhelp.com/api/docs y la especificación OpenAPI en /api/docs/openapi.json. Pulsa Authorize, pega tu clave tsk_ y prueba cualquier ruta con Try it out.

El flujo típico

GET /boards devuelve tus tableros, o los de la clave si está limitada.
GET /boards/{id} devuelve el tablero completo: listas, tarjetas, etiquetas, campos personalizados y miembros. De ahí sacas los ids que necesitas.
Con esos ids trabajas sobre las tarjetas: POST /lists/{id}/cards crea una, PATCH /cards/{id} la edita, POST /cards/{id}/move la mueve, PUT /cards/{id}/fields/{fieldId} completa un campo personalizado y POST /cards/{id}/comments agrega un comentario.

Ejemplo con curl

Crear una tarjeta al final de la lista 12:

curl -X POST https://tasks.melonhelp.com/api/lists/12/cards \
  -H "Authorization: Bearer tsk_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Revisar el pedido 4821", "description": "Creada desde el CRM"}'

La respuesta es la tarjeta creada, con su id, y el código 201. Para dejarla primera en otra lista del mismo tablero:

curl -X POST https://tasks.melonhelp.com/api/cards/345/move \
  -H "Authorization: Bearer tsk_..." \
  -H "Content-Type: application/json" \
  -d '{"listId": 13, "position": 0}'

Rutas principales

Recurso	Rutas
Tableros	`GET /boards`, `POST /boards`, `GET /boards/{id}`, `PATCH /boards/{id}`, `GET /boards/{id}/search`, `GET /boards/{id}/activity`, `GET /boards/{id}/archived`
Miembros	`GET /boards/{id}/members`, `POST /boards/{id}/members`, `PATCH /boards/{id}/members/{userId}`, `DELETE /boards/{id}/members/{userId}`
Listas	`GET /boards/{id}/lists`, `POST /boards/{id}/lists`, `PATCH /lists/{id}`, `POST /lists/{id}/move`
Tarjetas	`POST /lists/{id}/cards`, `GET /cards/{id}`, `PATCH /cards/{id}`, `POST /cards/{id}/move`, `POST /cards/{id}/copy`, `DELETE /cards/{id}`
Etiquetas y responsables	`POST /boards/{id}/labels`, `PUT /cards/{id}/labels/{labelId}`, `PUT /cards/{id}/members/{userId}`
Checklists	`POST /cards/{id}/checklists`, `POST /checklists/{id}/items`, `PATCH /items/{id}`, `POST /items/{id}/convert`
Campos personalizados	`POST /boards/{id}/custom-fields`, `PATCH /custom-fields/{id}`, `PUT /cards/{id}/fields/{fieldId}`
Comentarios y adjuntos	`POST /cards/{id}/comments`, `POST /cards/{id}/attachments`, `GET /attachments/{id}/download`
Cambios en vivo	`GET /boards/{id}/events`, un flujo de eventos (SSE) que avisa cuando el tablero cambia

La lista completa, con cada campo y cada respuesta, está en Swagger.

Sigue leyendo

Qué es Melonhelp Tasks: todo lo que incluye un tablero.
Acceso y permisos: roles, invitaciones y administración.