Tareas

Actualizar una tarea

Actualiza parcialmente una tarea (envía solo los campos que cambian).

PATCH
/api/v1/tasks/{taskId}

Ejemplos de petición

curl https://app.filmo.io/api/v1/tasks/task_8f2a1c \
  --request PATCH \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "isCompleted": true,
  "assignedStaffIds": [
    "stf_ana"
  ]
}'
{
  "data": {
    "id": "task_9f3a2b",
    "title": "Example title",
    "description": "Example text.",
    "startDate": "2026-09-01T08:00:00.000Z",
    "endDate": "2026-09-01T08:00:00.000Z",
    "isAllDay": true,
    "isCompleted": true,
    "isRecurring": true,
    "recurringGroupId": "recurring_group_9f3a2b",
    "recurrencePattern": {
      "frequency": "daily",
      "interval": 1,
      "endAfterOccurrences": 1,
      "endDate": "2026-09-01T08:00:00.000Z"
    },
    "type": "Example type",
    "assignedStaffIds": [
      "assigned_staff_9f3a2b"
    ],
    "projectId": "project_9f3a2b",
    "relatedDocumentId": "related_document_9f3a2b",
    "relatedDocumentType": "Example related document type",
    "appearance": {
      "color": "Example color",
      "variant": "primary"
    },
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z"
  }
}

Generado a partir del esquema

El personal, el proyecto y el documento relacionado se comprueban contra tu cuenta igual que en la creación. Devuelve la tarea actualizada.

Autorizaciones

Clave de API como Bearer, con el permiso de abajo. tasks:write

Cabeceras

Idempotency-Keystring

Identificador único de la petición, elegido por el cliente (sirve un UUID). Entre 1 y 255 caracteres: una cabecera vacía se rechaza con 400 validation_error, porque el cliente se creería protegido. Repetir la misma clave con el MISMO cuerpo en 24 h devuelve la respuesta guardada sin volver a ejecutar, con la cabecera Idempotent-Replay: true. Con un cuerpo DISTINTO devuelve 422. Es la forma segura de reintentar tras un tiempo de espera de red.

Límites: longitud mín. 1, longitud máx. 255

Ejemplo:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

Bloqueo optimista: el ETag que leíste del recurso (o *). Si el recurso ha cambiado desde entonces, la escritura se rechaza con 412 precondition_failed antes de hacer nada; léelo de nuevo y reintenta. Sin la cabecera, la escritura siempre se realiza.

Ejemplo:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Parámetros de ruta

taskIdstringObligatorio

Identificador de la tarea.

Límites: longitud mín. 1

Cuerpo

application/json

Esquema del cuerpo: TaskUpdateBody

titlestring

Título de la tarea.

Límites: longitud mín. 1, longitud máx. 300

descriptionstring | null

Descripción o notas de la tarea; null las borra.

Límites: longitud máx. 5000

startDatestring<date-time>

Fecha y hora de inicio de la tarea (ISO 8601 con desplazamiento).

endDatestring<date-time> | null

Fecha y hora de fin de la tarea (ISO 8601 con desplazamiento); debe ser igual o posterior a startDate. null la borra.

isAllDayboolean

Si la tarea dura todo el día.

isCompletedboolean

Marca la tarea como completada o pendiente.

typestring

Tipo de tarea: su identificador o su nombre, comparado sin distinguir mayúsculas ni acentos (ver POST /api/v1/tasks). Cambiarlo también cambia el color de la tarea al del tipo.

Límites: longitud mín. 1, longitud máx. 100

assignedStaffIdsstring[]

Identificadores del personal asignado a la tarea (máx. 50); sustituye la asignación existente.

Límites: máx. 50 elementos, cada uno: longitud mín. 1, cada uno: longitud máx. 100

projectIdstring | null

Identificador del proyecto vinculado; null lo desvincula.

Límites: longitud mín. 1, longitud máx. 100

relatedDocumentIdstring | null

Identificador del documento relacionado; va siempre junto con relatedDocumentType. null (con relatedDocumentType: null) lo desvincula.

Límites: longitud mín. 1, longitud máx. 100

relatedDocumentTypestring | null

Tipo del documento relacionado; va siempre junto con relatedDocumentId. null (con relatedDocumentId: null) lo desvincula.

Opciones disponibles: contact, order, item, kit, space, collection, invoice, quote, purchaseOrder, supplierInvoice, incident, repairTicket, project, vehicle, staff, service, opportunity

Respuesta

application/json

Respuesta correcta.

Esquema de la respuesta: TaskDto

Sobre: TaskResponse. meta.warnings solo aparece cuando la operación está obsoleta.

Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

La tarea, tal como la devuelve la API.

Mostrar atributos hijos
data.idstring

Identificador único de la tarea.

data.titlestring

Título de la tarea.

data.descriptionstring | null

Descripción o notas de la tarea; null si no tiene.

data.startDatestring<date-time>

Fecha y hora de inicio en ISO 8601 con desplazamiento.

data.endDatestring<date-time> | null

Fecha y hora de fin en ISO 8601 con desplazamiento; null si no tiene un fin definido.

data.isAllDayboolean

Si la tarea dura todo el día.

data.isCompletedboolean

Si la tarea está completada.

data.isRecurringboolean

Si la tarea forma parte de una serie recurrente.

data.recurringGroupIdstring | null

Identificador del grupo de recurrencia al que pertenece; null si no es recurrente.

data.recurrencePatternobject | null

Patrón de recurrencia de la tarea; null si no es recurrente.

Mostrar atributos hijos
data.recurrencePattern.frequencystring

Frecuencia de recurrencia: daily, weekly, monthly o yearly.

Opciones disponibles: daily, weekly, monthly, yearly

data.recurrencePattern.intervalinteger

Intervalo entre repeticiones según la frecuencia (p. ej. 2 con weekly = cada dos semanas).

data.recurrencePattern.endAfterOccurrencesinteger | null

Número de repeticiones tras las cuales termina la recurrencia; null si no termina por número de ocurrencias.

data.recurrencePattern.endDatestring<date-time> | null

Fecha en que termina la recurrencia, en ISO 8601 con desplazamiento; null si no termina por fecha.

data.typestring

Tipo de tarea (identificador del tipo).

data.assignedStaffIdsstring[]

Identificadores del personal asignado a la tarea.

data.projectIdstring | null

Identificador del proyecto vinculado; null si la tarea no está vinculada.

data.relatedDocumentIdstring | null

Identificador del documento relacionado; null si no tiene.

data.relatedDocumentTypestring | null

Tipo del documento relacionado (contacto, pedido, factura, presupuesto, proyecto, etc.); null si no tiene.

data.appearanceobject

Aspecto de la tarea en la agenda (color y variante).

Mostrar atributos hijos
data.appearance.colorstring

Color de la tarea en la agenda (código hexadecimal).

data.appearance.variantstring

Variante visual de la tarea: primary, secondary, destructive o default.

Opciones disponibles: primary, secondary, destructive, default

data.createdAtstring<date-time>

Fecha de creación en ISO 8601 con desplazamiento.

data.updatedAtstring<date-time>

Fecha de la última actualización en ISO 8601 con desplazamiento.

metaobject

Información adicional sobre la respuesta.

Mostrar atributos hijos
meta.warningsobject[]

Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta.

Mostrar atributos hijos
meta.warnings.codestring

Código de aviso estable.

Opciones disponibles: deprecated

meta.warnings.messagestring

Para personas: qué está obsoleto, hasta cuándo y qué usar.

meta.warnings.sunsetstring

Día (YYYY-MM-DD) en que la operación deja de estar disponible.

meta.warnings.replacementstring | null

operationId de la operación que hay que usar en su lugar, o null si no hay ninguna.

Errores

EstadoCódigosSignificado
400validation_errorConsulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable.
404not_foundNo existe o queda fuera del alcance de la clave de API.
409conflictEl estado actual del recurso impide la operación, ya hay en curso una petición con esa Idempotency-Key, u otra escritura condicional (If-Match) retuvo el recurso durante más de cinco segundos. errors[0].code indica cuál: in_progress y lock_timeout se resuelven reintentando; invalid_state no, porque el estado del recurso prohíbe la operación.
412precondition_failedLa etiqueta de entidad If-Match no coincide con la representación actual. Vuelve a leer el recurso y reintenta.
422idempotency_key_reusedLa misma clave se usó antes con un cuerpo distinto. Cambia la clave.

401, 403, 429, 500 los puede devolver cualquier operación. Errores

Obsolescencia

Esta operación no está obsoleta. Las obsolescencias se anuncian con la cabecera Deprecation y una fecha de retirada. Política de versiones

  • Operaciones

    Tarea

    La tarea, tal como la devuelve la API.

¿Te ha resultado útil esta página?