Versionado y obsolescencia

La versión del contrato sigue semver y aparece en info.version en el archivo OpenAPI. GET /api/v1/account también la devuelve. Usa esa versión para identificar el contrato de tu integración. Consulta también la Referencia de OpenAPI.

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.

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, 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.

// 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 });
  }
}

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})

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.

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.