*API REST › Referencia de endpoints › Catálogo e inventario › Disponibilidad* # Declarar una indisponibilidad > Declara que un recurso no está disponible en una ventana: vacaciones, un mantenimiento, un cierre. `reason` se ACEPTA y no se devuelve: se queda en Filmo para quien tenga acceso. Para una persona o un vehículo, los compromisos que se solapan no bloquean: la indisponibilidad se registra y `warningCount` indica cuántos compromisos ya reservados se solapan con ella. Un espacio es distinto: declararlo `unavailable` en una ventana en la que está reservado responde 409 `conflict` y no se escribe nada, así que en un espacio `warningCount` es siempre 0. También responde 409 si ya existe una indisponibilidad idéntica (mismo recurso, ventana, estado, tipo y motivo). Responde 400 `validation_error`, con `errors[0].path` en el campo, cuando `endDate` no es posterior a `startDate`, cuando `resourceId` no existe o pertenece a otra cuenta, y cuando `absenceType` no es uno de los de su tipo de recurso: `vacation`, `sick`, `personal`, `training` u `other` para el personal; `maintenance`, `inspection`, `repair`, `reserved` u `other` para los vehículos; `academic`, `maintenance`, `event`, `closure` u `other` para los espacios. En un espacio responde 503 `service_unavailable` mientras las indisponibilidades de espacios estén desactivadas para la cuenta. `POST /api/v1/availability/unavailabilities` — permiso `availability:write` Permiso: `availability:write` · 120/min · Idempotency-Key · MCP: `filmo_unavailabilities_create` ## Autorizaciones Clave de API como Bearer, con el permiso de abajo. `availability:write` ## Cabeceras | Nombre | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | `Idempotency-Key` | string | No | 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. | ## Cuerpo Esquema del cuerpo: `UnavailabilityCreateBody` | Nombre | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | `resourceType` | string | Sí | Qué recurso se declara no disponible. `staff`, `vehicle`, `space` | | `resourceId` | string | Sí | Identificador de ese recurso. | | `startDate` | string | Sí | Inicio, en ISO 8601 con desplazamiento. | | `endDate` | string | Sí | Fin, en ISO 8601 con desplazamiento. | | `state` | string | Sí | Lo que se declara para esa ventana. `available`, `unavailable`, `unknown` | | `absenceType` | string | No | Tipo de ausencia. `vacation`, `sick`, `personal`, `training`, `maintenance`, `inspection`, `repair`, `reserved`, `academic`, `event`, `closure`, `other` | | `reason` | string | No | Motivo. Se guarda en Filmo y la API NO lo devuelve. | ## Ejemplos de petición *Declarar una indisponibilidad* **cURL** ```bash curl https://app.filmo.io/api/v1/availability/unavailabilities \ --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 '{ "resourceType": "staff", "resourceId": "stf_ana", "startDate": "2026-08-01T00:00:00+02:00", "endDate": "2026-08-15T23:59:59+02:00", "state": "unavailable", "absenceType": "vacation" }' ``` **Node.js** ```javascript fetch('https://app.filmo.io/api/v1/availability/unavailabilities', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Idempotency-Key': crypto.randomUUID(), 'Content-Type': 'application/json' }, body: JSON.stringify({ resourceType: 'staff', resourceId: 'stf_ana', startDate: '2026-08-01T00:00:00+02:00', endDate: '2026-08-15T23:59:59+02:00', state: 'unavailable', absenceType: 'vacation' }) }) ``` **Python** ```python import uuid import requests requests.post( "https://app.filmo.io/api/v1/availability/unavailabilities", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json" }, json={ "resourceType": "staff", "resourceId": "stf_ana", "startDate": "2026-08-01T00:00:00+02:00", "endDate": "2026-08-15T23:59:59+02:00", "state": "unavailable", "absenceType": "vacation" } ) ``` ## Respuesta Esquema de la respuesta: `UnavailabilityResultDto` | Estado | Descripción | | --- | --- | | 201 | Respuesta correcta. | | 400 | Petición no válida (validation_error): consulta o cuerpo mal formados. `errors[]` enumera cada campo erróneo con su código estable. | | 401 | Fallo de autenticación (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). | | 403 | 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í. | | 404 | Recurso no encontrado (not_found): no existe o está fuera del alcance de la clave de API. | | 409 | 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].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. | | 422 | Idempotency-Key reutilizada (idempotency_key_reused): la misma clave se usó antes con un cuerpo distinto. Cambia la clave. | | 429 | Límite de peticiones superado (rate_limited): reintenta tras `Retry-After` segundos; `RateLimit-*` indica qué cuota se ha agotado. | | 500 | Error interno (internal_error). | | 503 | Servicio no disponible (service_unavailable): la función en la que escribe esta operación está desactivada para la cuenta. La petición es correcta; vuelve a funcionar en cuanto se activa la función. | **201** | Nombre | Tipo | Descripción | | --- | --- | --- | | `data` | object | Resultado de declarar o actualizar una indisponibilidad. | | `data.availability` | object | La indisponibilidad tal como queda ahora. | | `data.availability.id` | string | Identificador único de la indisponibilidad. | | `data.availability.resourceType` | string | Qué recurso: staff, vehicle o space. | | `data.availability.resourceId` | string | Identificador de ese recurso. | | `data.availability.resourceName` | string | Nombre del recurso; null si no consta. | | `data.availability.startDate` | string | Inicio de la indisponibilidad en ISO 8601 UTC. | | `data.availability.endDate` | string | Fin de la indisponibilidad en ISO 8601 UTC. | | `data.availability.state` | string | Estado declarado. Este listado solo devuelve ventanas `unavailable` que aún no han terminado, así que aquí siempre es `unavailable`; `available` y `unknown` existen como declaraciones pero no se listan. | | `data.availability.absenceType` | string | Tipo de ausencia. Solo se emite para vehículos y espacios, donde es operativo; para el personal es un dato de salud y se devuelve como null. | | `data.availability.updatedAt` | string | Última modificación en ISO 8601 UTC; null si no está registrada. | | `data.warningCount` | integer | Compromisos del recurso que se solapan con esta indisponibilidad. | | `meta` | object | Información adicional sobre la respuesta. | | `meta.warnings` | object[] | Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta. | | `meta.warnings.code` | string | Código de aviso estable. `deprecated` | | `meta.warnings.message` | string | Para personas: qué está obsoleto, hasta cuándo y qué usar. | | `meta.warnings.sunset` | string | Día (YYYY-MM-DD) en que la operación deja de estar disponible. | | `meta.warnings.replacement` | string | `operationId` de la operación que hay que usar en su lugar, o null si no hay ninguna. | | `meta.warnings.link` | string | Dónde está documentada la deprecación (el changelog). | *Respuesta de ejemplo · 201* ```json { "data": { "availability": { "id": "availability_9f3a2b", "resourceType": "Example resource type", "resourceId": "resource_9f3a2b", "resourceName": "Example resource name", "startDate": "2026-09-01T08:00:00.000Z", "endDate": "2026-09-01T08:00:00.000Z", "state": "Madrid", "absenceType": "Example absence type", "updatedAt": "2026-09-01T08:00:00.000Z" }, "warningCount": 1 } } ``` ## 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].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. | | 422 | `idempotency_key_reused` | La misma clave se usó antes con un cuerpo distinto. Cambia la clave. | | 503 | `service_unavailable` | La función en la que escribe esta operación está desactivada para la cuenta. La petición es correcta; vuelve a funcionar en cuanto se activa la función. | ## Obsolescencia Esta operación no está obsoleta. Las obsolescencias se anuncian con la cabecera Deprecation y una fecha de retirada. --- URL canónica: https://docs.filmo.io/es/rest-api/endpoint-reference/availability/declare-an-unavailability Última actualización: 2026-10-25