Modificar tarea

PATCH/tasks/{id}

Requiere el scope tasks:write.

Las mismas tareas que GET (mismo 404 opaco): en un proyecto compartido cualquier miembro edita las visibles. En un proyecto archivado responde 409 project_archived. El cuerpo debe traer al menos un campo (422 empty_patch si no).

assigneeId asigna la tarea a una persona con acceso a su proyecto compartido (null la deja sin asignar). Se aplica en la misma operación que el resto de campos: si falla (422 assignee_not_member, task_not_shared, task_private), no se aplica nada.

status: done fija completedAt y progress: 100 en la primera compleción; si la tarea es recurrente, el servidor crea la siguiente ocurrencia. Volver a backlog/in_progress limpia completedAt.

PATCH no borra notes ni deadline. projectId: null deja la tarea sin proyecto y recurrence: null hace que deje de repetirse (la serie se para; la tarea se conserva). Un patrón nuevo rige desde la siguiente ocurrencia: la tarea actual conserva su fecha. La recurrencia exige deadline y una tarea no completada (422 si no).

Parámetros de ruta

idstringobligatorio: Id de la tarea.

Cuerpo de la petición

JSON, obligatorio. Modelo TaskPatch.

titlestring

Rango: al menos 1 carácter

notesstring

projectIdstring | null

deadlinenumber

Rango: ≥ 0

deadlineStartnumber

Rango: ≥ 0

deadlineTypeDeadlineType

Granularidad del deadline (deadline = fin o fecha exacta, deadlineStart = inicio opcional).

Valores: exactdateweekmonthcustom

priorityTaskPriority

Valores: highmediumlow

progressnumber

Rango: 0–100

statusTaskStatus

Valores: backlogin_progressdone

recurrenceRecurrenceInput | null

Regla de recurrencia al crear o en PATCH. Campos no listados → 422 unknown_field. Los valores deben ser enteros; dayOfMonth admite -1 (último día) o 1..31, nunca 0.

Campos de RecurrenceInput

frequencyRecurrenceFrequencyobligatorio: Valores: dailyweeklymonthlyyearly
intervalinteger: Rango: 1–99
dayOfWeekinteger: Rango: 0–6
dayOfMonthinteger: Rango: -1–31

No admite otros campos: uno desconocido responde 422.

assigneeIdstring | null

Id de la cuenta (Person.id) de alguien con acceso al proyecto compartido de la tarea; null = sin asignar.

No admite otros campos: uno desconocido responde 422.

Respuestas

200

La tarea tras aplicar el patch.

dataTaskobligatorio

Tarea. Todos los campos están siempre presentes; los sin valor van como null (nunca se omiten). Timestamps en epoch milisegundos UTC.

Campos de Task

idstringobligatorio

titlestringobligatorio

statusTaskStatusobligatorio

Valores: backlogin_progressdone

priorityTaskPriorityobligatorio

Valores: highmediumlow

progressnumber | nullobligatorio

Rango: 0–100

notesstring | nullobligatorio

projectIdstring | nullobligatorio

deadlinenumber | nullobligatorio

Fin del intervalo o fecha exacta (epoch ms).

deadlineStartnumber | nullobligatorio

Inicio del intervalo (epoch ms).

deadlineTypeDeadlineType | nullobligatorio

Granularidad del deadline (deadline = fin o fecha exacta, deadlineStart = inicio opcional).

Valores: exactdateweekmonthcustom

recurrenceRecurrence | nullobligatorio

Solo la lleva la ocurrencia pendiente de una serie; las completadas van con null.

Campos de Recurrence

frequencyRecurrenceFrequencyobligatorio: Valores: dailyweeklymonthlyyearly
intervalnumber: Rango: 1–99
dayOfWeeknumber: 0 = domingo … 6 = sábado.
Rango: 0–6
dayOfMonthnumber: -1 = último día del mes; si no, 1..31.
Rango: -1–31

seriesIdstring | nullobligatorio

Serie recurrente a la que pertenece (pendiente o completada); null si nunca se repitió.

createdAtnumberobligatorio

updatedAtnumberobligatorio

completedAtnumber | nullobligatorio

createdByPersonobligatorio

Cuenta de SecretarIA. Sin correo a propósito.

Campos de Person

idstringobligatorio
namestring | nullobligatorio: Nombre de pila; null si la cuenta ya no existe.

assigneePerson | nullobligatorio

Persona asignada en un proyecto compartido; null = sin asignar.

Campos de Person

idstringobligatorio
namestring | nullobligatorio: Nombre de pila; null si la cuenta ya no existe.

401

Key ausente, malformada, inexistente, revocada, expirada o API deshabilitada (invalid_api_key, indistinguibles a propósito).

Códigos: invalid_api_key

403

Scope insuficiente (insufficient_scope), recurso sin acceso (forbidden) o sincronización de calendario de una tarea que creó otra persona (calendar_creator_only).

Códigos: insufficient_scopeforbiddencalendar_creator_only

404

Recurso inexistente, de otro usuario o id malformado (not_found, indistinguibles a propósito).

Códigos: not_found

409

El proyecto de la tarea está archivado y es de solo lectura (project_archived). No se aplicó nada.

Códigos: project_archived

422

Entrada inválida (invalid_json, unknown_field, missing_field, invalid_field, invalid_query_param, empty_patch, body_too_large — cuerpos de más de 64 KB —, invalid_idempotency_key, validation_error, y al asignar assignee_not_member, task_not_shared, task_private).

Códigos: invalid_jsonunknown_fieldmissing_fieldinvalid_fieldinvalid_query_paramempty_patchbody_too_largeinvalid_idempotency_keyvalidation_errorassignee_not_membertask_not_sharedtask_private

429

Límite superado (rate_limited) — 60 req/min (ráfagas de 20) y 5.000 req/día por key. Reintentar tras Retry-After.

Códigos: rate_limited

Cabecera Retry-After: Segundos (enteros) a esperar antes de reintentar.

500

Error interno (internal_error). Cuerpo opaco a propósito; reintentar con backoff.

Códigos: internal_error

bash

curl -X PATCH 'https://system.secretar-ia.org/api/v1/tasks/jd7f3k2m9q8w1x4v6b5n0c2a7s8e3r1t' \
  -H "Authorization: Bearer $SECRETARIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "in_progress",
  "progress": 40,
  "assigneeId": "p3s7v1y5b9e2h6k0m4q8t2w6z0c4f8j1"
}'

Tarea completa

JSON

{
  "data": {
    "id": "jd7f3k2m9q8w1x4v6b5n0c2a7s8e3r1t",
    "title": "Revisar informe mensual",
    "status": "in_progress",
    "priority": "high",
    "progress": 40,
    "notes": "Comparar con el trimestre anterior.",
    "projectId": "kh72p9d3w1v8m4x6c0b5n2q7r9s3t1a8",
    "deadline": 1767225599999,
    "deadlineStart": null,
    "deadlineType": "date",
    "recurrence": {
      "frequency": "weekly",
      "interval": 1,
      "dayOfWeek": 1
    },
    "seriesId": "m9c2x6v0b4n8q3w7e1r5t9y3u7i1o5p2",
    "createdAt": 1765804800000,
    "updatedAt": 1766063400000,
    "completedAt": null,
    "createdBy": {
      "id": "k1m8x2c5v9b3n7q0w4e6r1t8y2u5i3o9",
      "name": "Ana"
    },
    "assignee": {
      "id": "p3s7v1y5b9e2h6k0m4q8t2w6z0c4f8j1",
      "name": "Bruno"
    }
  }
}