*API REST › Referencia de endpoints › Catálogo e inventario › Disponibilidad* # Comprobar la disponibilidad de artículos > Comprueba la disponibilidad de un lote de artículos (1-100) en un rango de fechas común, cada uno con la cantidad que piensas reservar (1 por defecto). Consulta idempotente (POST por el cuerpo estructurado). Comparte la cuota de disponibilidad de 30 req/min. Una entrada por artículo solicitado, en el orden de la petición: su disponibilidad (`available`, `shortfall`, `conflictingPeriods` para esa cantidad, y `commitments`: los pedidos que retienen unidades de él en la ventana, con su número, cantidad máxima y fechas) o un `error` por elemento cuando el artículo no existe en la cuenta. `POST /api/v1/availability/check` — permiso `availability:read` Permiso: `availability:read` · 120/min · +30/min de disponibilidad · MCP: `filmo_availability_check` ## Autorizaciones Clave de API como Bearer, con el permiso de abajo. `availability:read` ## Cuerpo Esquema del cuerpo: `AvailabilityCheckBody` | Nombre | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | `items` | object[] | Sí | Lote de artículos que comprobar (entre 1 y 100). | | `items.itemId` | string | Sí | Identificador del artículo que se comprueba. Obligatorio. | | `items.variantId` | string | No | Identificador de la variante concreta que se comprueba; omítelo para el artículo base. | | `items.transactionType` | string | No | Tipo de transacción que comprobar: rental o sale. Por defecto, rental. `rental`, `sale` | | `items.quantity` | integer | No | Unidades que piensas reservar. Determina `available`, `shortfall`, `status` y `conflictingPeriods`. Por defecto es 1. | | `startDate` | string | Sí | Inicio del rango a comprobar (ISO 8601 con desplazamiento), compartido por todo el lote. | | `endDate` | string | Sí | Fin del rango a comprobar (ISO 8601 con desplazamiento), compartido por todo el lote; debe ser posterior a startDate. | ## Ejemplos de petición *Comprobar la disponibilidad de artículos* **cURL** ```bash curl https://app.filmo.io/api/v1/availability/check \ --request POST \ --header "Authorization: Bearer $FILMO_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "itemId": "itm_9f3a2b", "variantId": "var_rojo", "transactionType": "rental", "quantity": 4 }, { "itemId": "itm_camara_a7" } ], "startDate": "2026-09-01T08:00:00+02:00", "endDate": "2026-09-05T20:00:00+02:00" }' ``` **Node.js** ```javascript fetch('https://app.filmo.io/api/v1/availability/check', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ items: [ { itemId: 'itm_9f3a2b', variantId: 'var_rojo', transactionType: 'rental', quantity: 4 }, { itemId: 'itm_camara_a7' } ], startDate: '2026-09-01T08:00:00+02:00', endDate: '2026-09-05T20:00:00+02:00' }) }) ``` **Python** ```python import requests requests.post( "https://app.filmo.io/api/v1/availability/check", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Content-Type": "application/json" }, json={ "items": [ { "itemId": "itm_9f3a2b", "variantId": "var_rojo", "transactionType": "rental", "quantity": 4 }, { "itemId": "itm_camara_a7" } ], "startDate": "2026-09-01T08:00:00+02:00", "endDate": "2026-09-05T20:00:00+02:00" } ) ``` ## Respuesta Esquema de la respuesta: `AvailabilityCheckEntryDto` | Estado | Descripción | | --- | --- | | 200 | 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. | | 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). | **200** | Nombre | Tipo | Descripción | | --- | --- | --- | | `data` | object[] | | | `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 · 200* ```json { "data": [ { "itemId": "item_9f3a2b", "variantId": "variant_9f3a2b", "itemName": "Example item name", "quantity": 1, "available": true, "status": "ok", "totalStock": 1, "reserved": 1, "minRemaining": 1, "shortfall": 1, "temporaryAvailable": 1, "conflictingPeriods": [ "Example conflicting periods" ], "commitments": [ { "orderId": "order_9f3a2b", "orderNumber": "2026-0001", "quantity": 1, "startDate": "2026-09-01T08:00:00.000Z", "endDate": "2026-09-01T08:00:00.000Z" } ], "checkedAt": "2026-09-01T08:00:00.000Z" } ] } ``` ## 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. | ## 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/check-item-availability Última actualización: 2026-10-25