API de mywoork

Para leer y escribir en mywoork desde otro programa —o desde un asistente de IA— sin pasar por la pantalla.

Cómo empezar

Crea un token en la aplicación, en Acceso API. Solo se ve una vez. Después, en cada petición: 

curl https://tu-mywoork/api/v1/me \
-H "Authorization: Bearer mw_..."

GET /api/v1/me es el primer sitio donde mirar: dice quién eres, de qué empresa y qué permisos tiene el token, sin tener que averiguarlo a base de 403.

Lo que conviene saber antes

Un token, una empresa
El token guarda su empresa y no puede leer ni escribir datos de otra, pase lo que pase. Tampoco ve nada que su dueño no vea en pantalla.
Nunca en la URL
El token va en la cabecera. Mandarlo por el query string acaba escribiéndolo en los registros del servidor y en el historial del navegador, así que la API lo rechaza con un 400.
Escribir implica leer
contactos:write incluye contactos:read. Al revés no.
Las escrituras no mienten
Si el cuerpo trae un campo desconocido, no editable o mal formado, se rechaza la petición entera con un 422 que los enumera, y no se guarda nada — ni siquiera los campos correctos. Nunca recibirás un 2xx por un cambio que no se aplicó.
PATCH y PUT son distintos
PATCH toca solo los campos que envías. PUT reemplaza: los campos editables que no envíes quedan vacíos.
Reintentos sin duplicar
Toda escritura acepta Idempotency-Key. La misma clave dentro de 24 horas devuelve la respuesta original sin repetir el cambio. La misma clave con otro cuerpo es un 409.
Listados
Cursor: ?limit= (50 por defecto, 200 como máximo) y ?cursor=. La respuesta trae items y next_cursor. Un limit fuera de rango se rechaza, no se recorta en silencio.
Fechas
ISO 8601. Las de sistema (created_at, updated_at) son UTC y llevan Z. Las fechas de trabajo (scheduled_on, archived_at) van sin zona: la columna no la tiene en la base de datos y ponérsela sería inventarse un dato.
Errores
RFC 7807 (application/problem+json), con un detail que dice qué falta exactamente.

Quién soy

El primer sitio donde mirar: quién eres, de qué empresa y qué permisos tiene este token. No exige ningún ámbito — un token sin permisos para nada tiene que poder preguntar qué es lo que no puede hacer.

GET /api/v1/me Quién eres y qué puedes hacer con este token. cualquier token

Campos

Campo Tipo Qué es
user objeto solo lectura La persona dueña del token.
company objeto solo lectura Su empresa. Un token solo ve ésta.
token objeto solo lectura Descripción, ámbitos, caducidad, último uso y estado del token.

Contactos

Los clientes, proveedores y personas de la empresa.

GET /api/v1/contactos Lista los contactos, paginados por cursor. contactos:read
GET /api/v1/contactos/{id} Un contacto. contactos:read
POST /api/v1/contactos Crea un contacto. contactos:write
PATCH /api/v1/contactos/{id} Cambia SOLO los campos enviados. contactos:write
PUT /api/v1/contactos/{id} Reemplaza el contacto: los campos editables que no envíes quedan VACÍOS. contactos:write
DELETE /api/v1/contactos/{id} Archiva el contacto (borrado lógico) y lo devuelve con archived: true. contactos:write

Filtros

Solo estos. Cualquier otro parámetro se rechaza con un 422, en vez de ignorarse y devolver la lista entera como si hubiera filtrado.

q Busca en nombre, razón social, población, teléfonos, correos, webs y campos personalizados.
type `empresa` o `persona`.
created_by Solo los creados por ese usuario.

Campos

Campo Tipo Qué es
id texto solo lectura Identificador del contacto.
name texto se escribe Nombre de la persona.
business_name texto se escribe Razón social. Hace falta al menos uno de los dos: nombre o razón social.
tax_code texto se escribe NIF / CIF / NIE.
address texto se escribe Dirección.
postal_code texto se escribe Código postal.
city texto se escribe Población.
province texto se escribe Provincia.
country texto se escribe País.
phones lista de textos se escribe Teléfonos.
emails lista de textos se escribe Correos.
websites lista de textos se escribe Páginas web.
parent_id texto solo lectura La empresa de la que esta persona forma parte, si la hay.
archived sí/no solo lectura Si está archivado. Se cambia con DELETE, no escribiéndolo.
company_id texto solo lectura La empresa. Sale del token.
created_by texto solo lectura Quién lo creó.
created_at fecha ISO solo lectura Cuándo se creó (UTC).
updated_at fecha ISO solo lectura Último cambio (UTC).
open_tasks número solo lectura Tareas abiertas (agregado).

Tareas

El trabajo del equipo. El estado y la fecha son POR PERSONA: una tarea compartida entre tres tiene tres estados.

GET /api/v1/tareas Lista las tareas que puedes ver, paginadas por cursor. tareas:read
GET /api/v1/tareas/{id} Una tarea. tareas:read
POST /api/v1/tareas Crea una tarea y tu propia fila de estado. tareas:write
PATCH /api/v1/tareas/{id} Cambia SOLO los campos compartidos enviados. tareas:write
PUT /api/v1/tareas/{id} Reemplaza el contenido compartido: lo que no envíes queda VACÍO. tareas:write
PATCH /api/v1/tareas/{id}/mi-estado Cambia TU estado y TU fecha. No toca el de los demás participantes. tareas:write
DELETE /api/v1/tareas/{id} Borra la tarea para todos. Requiere participar en ella. tareas:write
GET /api/v1/tareas/{id}/comentarios Los comentarios de la tarea, del más antiguo al más nuevo. tareas:read
POST /api/v1/tareas/{id}/comentarios Escribe un comentario, con sus minutos trabajados si los hay. tareas:write
PUT /api/v1/tareas/{id}/participantes Con quién se comparte la tarea. Reemplaza la lista entera. tareas:write

Filtros

Solo estos. Cualquier otro parámetro se rechaza con un 422, en vez de ignorarse y devolver la lista entera como si hubiera filtrado.

open `true` sin archivar por ti, `false` archivadas por ti.
mias `abiertas` = lo que tienes pendiente: tu estado no es `completada` y no la has archivado. Es la consulta de todos los días, en una sola llamada.
status TU propio estado. Repite el parámetro para varios: `?status=pendiente&status=en_curso`. Varios valores se combinan con OR. Valores: pendiente, en_curso, en_espera, completada.
contact_id Solo las ligadas a ese contacto.
tag_id Etiqueta. Repite el parámetro para varias: `?tag_id=A&tag_id=B`.
tag_match Cómo se combinan varias etiquetas: `any` (por defecto) = lleva AL MENOS UNA; `all` = lleva TODAS.
scheduled_from Desde ese día (incluido), sobre TU `scheduled_on`. Se compara por DÍA: la columna no tiene zona horaria, así que comparar instantes obligaría a inventarse una.
scheduled_to Hasta ese día (incluido), sobre TU `scheduled_on`.
scheduled `null` = las que no tienen fecha tuya puesta.
q Busca en el título y la descripción, sin distinguir acentos ni mayúsculas.

Campos

Campo Tipo Qué es
id texto solo lectura Identificador de la tarea.
title texto se escribe Qué hay que hacer.
text texto se escribe Descripción. Admite HTML sencillo.
company_wide sí/no solo lectura Si la ve toda la empresa. Se cambia en la aplicación, no por API.
created_by texto solo lectura Quién la creó.
contacts lista de ids se escribe Los clientes de la tarea. Se ESCRIBE como lista de ids y se DEVUELVE con el nombre de cada uno. Solo ids: la API nunca resuelve nombres, para que no pueda equivocarse de cliente por ti.
tags lista de ids se escribe Las etiquetas de la tarea, como lista de ids. Reemplaza las que hubiera.
me objeto solo lectura TU estado en esta tarea. `null` si es de toda la empresa y no la has tocado nunca.
participants lista solo lectura El estado de CADA participante. En mywoork el estado es por persona, no de la tarea.
created_at fecha ISO solo lectura Cuándo se creó (UTC).
updated_at fecha ISO solo lectura Último cambio (UTC).
status texto solo lectura No se escribe aquí: es por persona, va en PATCH /tareas/{id}/mi-estado.
scheduled_on fecha ISO solo lectura No se escribe aquí: es por persona, va en PATCH /tareas/{id}/mi-estado.
filed_at fecha ISO solo lectura Se deriva del estado propio.
company_id texto solo lectura La empresa. Sale del token.

Notas

Notas del equipo, con el mismo modelo de visibilidad que las tareas.

GET /api/v1/notas Lista las notas que puedes ver, fijadas incluidas. notas:read
GET /api/v1/notas/{id} Una nota. notas:read
POST /api/v1/notas Crea una nota. notas:write
PATCH /api/v1/notas/{id} Cambia SOLO los campos enviados. notas:write
PUT /api/v1/notas/{id} Reemplaza la nota: lo que no envíes queda VACÍO. notas:write
DELETE /api/v1/notas/{id} Borra la nota. Requiere participar en ella. notas:write

Filtros

Solo estos. Cualquier otro parámetro se rechaza con un 422, en vez de ignorarse y devolver la lista entera como si hubiera filtrado.

contact_id Solo las ligadas a ese contacto.
q Busca en el título y el texto.

Campos

Campo Tipo Qué es
id texto solo lectura Identificador de la nota.
title texto se escribe Título de la nota.
text texto se escribe Contenido.
color texto se escribe `yellow`, `green`, `blue`, `clay`, `violet` o `plain`. Un PUT sin color lo deja en `yellow`: la columna no admite nulos, así que su vacío es su valor por defecto.
company_wide sí/no solo lectura Si la ve toda la empresa. Se cambia en la aplicación, no por API.
created_by texto solo lectura Quién la creó.
contacts lista de ids se escribe Los clientes de la nota. Se ESCRIBE como lista de ids y se DEVUELVE con el nombre de cada uno.
me objeto solo lectura TU estado (fijada, archivada, vista). `null` si no la has tocado.
participants lista solo lectura Con quién está compartida.
created_at fecha ISO solo lectura Cuándo se creó (UTC).
updated_at fecha ISO solo lectura Último cambio (UTC).
company_id texto solo lectura La empresa. Sale del token.

Etiquetas

Etiquetas de la empresa. Escribirlas es del propietario: un miembro no puede crear un token con `etiquetas:write`.

GET /api/v1/etiquetas Lista las etiquetas. etiquetas:read
GET /api/v1/etiquetas/{id} Una etiqueta. etiquetas:read
POST /api/v1/etiquetas Crea una etiqueta. etiquetas:write
PATCH /api/v1/etiquetas/{id} Cambia SOLO los campos enviados. etiquetas:write
PUT /api/v1/etiquetas/{id} Reemplaza la etiqueta: lo que no envíes queda VACÍO. etiquetas:write
DELETE /api/v1/etiquetas/{id} Borra la etiqueta y la quita de sus tareas. Borrado REAL, no lógico. etiquetas:write

Campos

Campo Tipo Qué es
id texto solo lectura Identificador de la etiqueta.
name texto se escribe Nombre. Único por empresa, sin distinguir mayúsculas.
color texto se escribe `gray`, `blue`, `green`, `red`, `yellow`, `teal` o `black`. Un PUT sin color lo deja en `gray`: la columna no admite nulos, así que su vacío es su valor por defecto.
created_at fecha ISO solo lectura Cuándo se creó (UTC).
updated_at fecha ISO solo lectura Último cambio (UTC).
company_id texto solo lectura La empresa. Sale del token.
task_count número solo lectura Tareas que la llevan (agregado).

Equipo

Las personas de la empresa. SOLO LECTURA: en mywoork no se crea un usuario, se le invita por correo desde la pantalla de Equipo.

GET /api/v1/equipo Lista las personas de la empresa. equipo:read
GET /api/v1/equipo/{id} Una persona. equipo:read

Campos

Campo Tipo Qué es
id texto solo lectura Identificador de la persona.
name texto solo lectura Nombre.
email texto solo lectura Correo con el que entra.
role texto solo lectura `owner` o `member`.
active sí/no solo lectura Si puede entrar. En la base de datos es `disabled`; aquí se dice en positivo.
joined_at fecha ISO solo lectura Cuándo se unió (UTC).
last_seen_at fecha ISO solo lectura Última vez que se le vio activo (UTC). Se refresca como mucho una vez al día.

Agregados

Cuentas que la aplicación ya calcula, para no tener que traerse miles de filas y sumarlas fuera.

GET /api/v1/agregados/tareas-abiertas-por-contacto Tareas abiertas por contacto — la misma cuenta que la pantalla de Contactos. contactos:read
GET /api/v1/agregados/mis-tareas-por-estado TUS tareas visibles agrupadas por tu propio estado. tareas:read
GET /api/v1/agregados/horas-por-contacto Horas trabajadas por cliente, sumando los minutos anotados en los comentarios. contactos:read
GET /api/v1/agregados/mis-tareas-abiertas-por-contacto MIS tareas abiertas agrupadas por cliente, con su cuenta — sin pedir la lista para contarla. tareas:read