Tareas
Crear una tarea
Crea una tarea con validación de dominio: el tipo, el personal, el proyecto y el documento relacionado se comprueban contra tu cuenta, y una referencia ajena responde 400 sin crear nada.
Ejemplos de petición
curl https://app.filmo.io/api/v1/tasks \
--request POST \
--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 '{
"title": "Preparar kit de iluminación para rodaje",
"description": "Revisar baterías y focos antes de la entrega.",
"startDate": "2026-09-01T09:00:00+02:00",
"endDate": "2026-09-01T11:00:00+02:00",
"isAllDay": false,
"type": "default",
"assignedStaffIds": [
"stf_ana",
"stf_luis"
],
"projectId": "prj_rodaje_otono",
"relatedDocumentId": "ord_00421",
"relatedDocumentType": "order"
}'Generado a partir del esquema
Devuelve la tarea creada.
Autorizaciones
Clave de API como Bearer, con el permiso de abajo. tasks:write
Cabeceras
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"
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\""
Cuerpo
Esquema del cuerpo: TaskCreateBody
Título de la tarea. Obligatorio.
Límites: longitud mín. 1, longitud máx. 300
Descripción o notas de la tarea.
Límites: longitud máx. 5000
Fecha y hora de inicio de la tarea (ISO 8601 con desplazamiento). Obligatorio.
Fecha y hora de fin de la tarea (ISO 8601 con desplazamiento); debe ser igual o posterior a startDate.
Si la tarea dura todo el día. Por defecto es false.
Tipo de tarea: su identificador (tipos de sistema: default, delivery, return, temporaryStock; tipos personalizados: su id, ver /api) o su nombre, comparado sin distinguir mayúsculas ni acentos. Un nombre que coincide con varios tipos personalizados se rechaza con 400 listando sus identificadores. La tarea toma el color del tipo. Obligatorio.
Límites: longitud mín. 1, longitud máx. 100
Identificadores del personal asignado a la tarea (máx. 50).
Límites: máx. 50 elementos, cada uno: longitud mín. 1, cada uno: longitud máx. 100
Identificador del proyecto al que está vinculada la tarea.
Límites: longitud mín. 1, longitud máx. 100
Respuesta
Respuesta correcta.
Esquema de la respuesta: TaskDto
Sobre: TaskResponse. meta. solo aparece cuando la operación está obsoleta.
Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay
La tarea, tal como la devuelve la API.
Mostrar atributos hijosOcultar atributos hijos
Identificador único de la tarea.
Título de la tarea.
Descripción o notas de la tarea; null si no tiene.
Fecha y hora de inicio en ISO 8601 con desplazamiento.
Fecha y hora de fin en ISO 8601 con desplazamiento; null si no tiene un fin definido.
Si la tarea dura todo el día.
Si la tarea está completada.
Si la tarea forma parte de una serie recurrente.
Identificador del grupo de recurrencia al que pertenece; null si no es recurrente.
Patrón de recurrencia de la tarea; null si no es recurrente.
Mostrar atributos hijosOcultar atributos hijos
Frecuencia de recurrencia: daily, weekly, monthly o yearly.
Opciones disponibles: daily, weekly, monthly, yearly
Intervalo entre repeticiones según la frecuencia (p. ej. 2 con weekly = cada dos semanas).
Número de repeticiones tras las cuales termina la recurrencia; null si no termina por número de ocurrencias.
Fecha en que termina la recurrencia, en ISO 8601 con desplazamiento; null si no termina por fecha.
Tipo de tarea (identificador del tipo).
Identificadores del personal asignado a la tarea.
Identificador del proyecto vinculado; null si la tarea no está vinculada.
Aspecto de la tarea en la agenda (color y variante).
Mostrar atributos hijosOcultar atributos hijos
Color de la tarea en la agenda (código hexadecimal).
Variante visual de la tarea: primary, secondary, destructive o default.
Opciones disponibles: primary, secondary, destructive, default
Fecha de creación en ISO 8601 con desplazamiento.
Fecha de la última actualización en ISO 8601 con desplazamiento.
Información adicional sobre la respuesta.
Mostrar atributos hijosOcultar atributos hijos
Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta.
Mostrar atributos hijosOcultar atributos hijos
Código de aviso estable.
Opciones disponibles: deprecated
Para personas: qué está obsoleto, hasta cuándo y qué usar.
Día (YYYY-MM-DD) en que la operación deja de estar disponible.
operationId de la operación que hay que usar en su lugar, o null si no hay ninguna.
Dónde está documentada la deprecación (el changelog).
Petición no válida (validation_error): consulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Fallo de autenticación (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin).
Cabeceras: X-Request-Id · Content-Language · Idempotent-Replay
No permitido (insufficient_scope: la clave de API no tiene el scope requerido, indicado en requiredScope; forbidden: el propietario de la clave carece del permiso que exige la operación). insufficient_scope se responde antes de que la petición cuente contra el límite de peticiones, así que no lleva cabeceras RateLimit-*; forbidden sí.
Cabeceras: X-Request-Id · Content-Language · Idempotent-Replay
Recurso no encontrado (not_found): no existe o está fuera del alcance de la clave de API.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Conflicto (conflict): el estado actual del recurso impide la operación, ya hay en curso una petición con esa Idempotency-Key, o otra escritura condicional (If-Match) retuvo el recurso durante más de cinco segundos. errors[0]. indica cuál: in_progress y lock_timeout se resuelven reintentando; invalid_state no, porque el estado del recurso prohíbe la operación.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Precondición fallida (precondition_failed): la etiqueta de entidad If-Match no coincide con la representación actual. Lee el recurso de nuevo y reintenta.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Idempotency-Key reutilizada (idempotency_key_reused): la misma clave se usó antes con un cuerpo distinto. Cambia la clave.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Límite de peticiones superado (rate_limited): reintenta tras Retry-After segundos; RateLimit-* indica qué cuota se ha agotado.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Retry-After · Idempotent-Replay
Error interno (internal_error).
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Errores
| Estado | Códigos | Significado |
|---|---|---|
| 400 | validation_error | Consulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable. |
| 404 | not_found | No existe o queda fuera del alcance de la clave de API. |
| 409 | conflict | El 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]. indica cuál: in_progress y lock_timeout se resuelven reintentando; invalid_state no, porque el estado del recurso prohíbe la operación. |
| 412 | precondition_failed | La etiqueta de entidad If-Match no coincide con la representación actual. Vuelve a leer el recurso y reintenta. |
| 422 | idempotency_key_reused | La 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
Relacionado
Páginas relacionadas
Enlace a esta sección: Páginas relacionadasOperaciones
Tarea
La tarea, tal como la devuelve la API.
¿Te ha resultado útil esta página?