*API REST › Guías*

# Versionado y obsolescencia

> Dentro de v1 Filmo solo añade cosas. Cualquier cosa que pueda romper tu integración se anuncia antes, ya sea como una nueva versión mayor o como una obsolescencia con al menos seis meses antes de la retirada.

## La versión del contrato

La versión del contrato sigue semver y aparece en `info.version` en el archivo OpenAPI. [`GET /api/v1/account`](https://docs.filmo.io/es/rest-api/endpoint-reference/account/get-the-account) también la devuelve. Usa esa versión para identificar el contrato de tu integración. Consulta también la [Referencia de OpenAPI](https://docs.filmo.io/es/rest-api/openapi).

## Política de compatibilidad

| Cambio | Dentro de v1 | Cómo te llega |
| --- | --- | --- |
| Una operación nueva; un campo de petición, filtro o parámetro opcional nuevo | Aditivo: permitido | Se publica en cualquier versión sin aviso previo. Se registra en el changelog con la versión en la que llegó. |
| Una propiedad nueva en una respuesta; un valor nuevo en una unión de respuesta (un estado, un tipo) | Aditivo: permitido | Igual que arriba. |
| Una validación más laxa | Aditivo: permitido | Igual que arriba. |
| Eliminar o renombrar una operación, un campo o un parámetro; cambiar un tipo; hacer anulable una propiedad de la respuesta | Incompatible | Solo con una nueva versión mayor, o mediante una obsolescencia con aviso previo. |
| Endurecer una validación; cambiar el scope que requiere una operación | Incompatible | Igual que arriba. |
| Eliminar un campo | Nunca dentro de una versión mayor | Un campo que deja de tener sentido se marca como obsoleto en su esquema y se registra en el changelog. Solo se elimina en la siguiente versión mayor. |

Los campos con datos sensibles para el negocio (costes, márgenes, códigos de acceso, documentos fiscales internos, nóminas del personal y datos personales) quedan excluidos por diseño del borde público. Hoy no forman parte de la v1, así que no planifiques una integración en torno a ellos.

## Cómo te llega una deprecación

Un cambio incompatible se hace exactamente de una de estas dos formas.

- En una nueva versión mayor, `/api/v2`. Filmo mantiene v1 en funcionamiento durante al menos doce meses después de anunciar v2.
- Mediante deprecación con aviso. La operación se marca como `deprecated` en el archivo OpenAPI, con un objeto `x-deprecation` que lleva `since` (la versión que la anunció), `on` (el día en que entra en vigor), `sunset` (el día en que desaparece), `replacement` (opcional) y una `note`. Los días son `YYYY-MM-DD`.

Una operación obsoleta te lo indica en tres sitios.

- Toda respuesta, incluidas las de error, lleva la cabecera `Deprecation` (RFC 9745, una marca de tiempo Unix con el prefijo `@`) y la cabecera `Sunset` (RFC 8594, una fecha HTTP).
- Las mismas respuestas llevan una cabecera `Link` con dos relaciones: `rel="deprecation"` y `rel="sunset"`, ambas apuntan a la documentación.
- Todo cuerpo JSON correcto lleva una entrada `meta.warnings[]` con `code` puesto en `deprecated`, un `message`, el día `sunset`, el `replacement` (o `null` cuando no hay ninguno) y un `link` a la documentación.

El día de sunset es al menos 180 días (seis meses) después del día en que la deprecación entra en vigor. La operación sigue funcionando hasta entonces y desaparece el día de sunset: después responde 404 [`not_found`](https://docs.filmo.io/es/rest-api/errors/not_found), antes incluso de autenticar la petición, así que un cliente que ignoró los avisos ve una operación inexistente en lugar de un error de autorización.

*Registra las deprecaciones en tu cliente HTTP*

**Node**

```javascript
// Call this for every response you receive, with the parsed JSON body (or null).
export function noteDeprecation(method, path, res, body) {
  const deprecation = res.headers.get("Deprecation");
  const sunset = res.headers.get("Sunset");
  const warned = (body?.meta?.warnings ?? []).some((w) => w.code === "deprecated");
  if (deprecation || sunset || warned) {
    console.warn("Deprecated:", method, path, { deprecation, sunset });
  }
}
```

**Python**

```python
def note_deprecation(method, path, res, body):
    """Call for every response, with the parsed JSON body (or None)."""
    deprecation = res.headers.get("Deprecation")
    sunset = res.headers.get("Sunset")
    warnings = ((body or {}).get("meta") or {}).get("warnings") or []
    warned = any(w.get("code") == "deprecated" for w in warnings)
    if deprecation or sunset or warned:
        print("Deprecated:", method, path, {"deprecation": deprecation, "sunset": sunset})
```

## El changelog

Cada versión queda registrada en la pestaña Changelog de estos documentos, en el formato Keep a Changelog: un encabezado con la versión y la fecha (`[x.y.z] - YYYY-MM-DD`) y, debajo, solo las secciones que tienen contenido entre Added, Changed, Deprecated, Removed y Fixed. Una línea de deprecación nombra la operación, el día en que quedó obsoleta, su día de retirada y el sustituto. Nada se elimina antes de su retirada. Suscríbete al feed y léelo antes de cada actualización de un cliente generado.

## Escribe un cliente tolerante

Los cambios aditivos se publican sin aviso, así que tu integración debe tolerarlos.

- Ignora las propiedades de respuesta que no uses. No valides las respuestas con un esquema cerrado que rechace propiedades desconocidas.
- Gestiona los valores que no conozcas en una unión: un estado, un tipo. Hoy los estados son listas cerradas, y un valor nuevo es un cambio aditivo documentado. Da a cada switch una rama por defecto.
- Ten cuidado con los clientes generados con enums cerrados. Un valor nuevo puede hacer que lancen un error al procesar una respuesta.
- No controles la lógica con `detail` ni con `errors[].message`. Son para personas y cambian con el idioma. Ramifica según `code`.
- Configura alertas para las cabeceras `Deprecation` y `Sunset` y para `meta.warnings[]`, de modo que una obsolescencia llegue a una persona al menos 180 días antes de la retirada.

Las mismas comprobaciones están en la [lista de comprobación de salida a producción](https://docs.filmo.io/es/rest-api/guides/going-live).

---

URL canónica: https://docs.filmo.io/es/rest-api/guides/versioning  
Última actualización: 2026-10-09