> ## Documentation Index > Fetch the complete documentation index at: https://muveya.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Versionado y estabilidad > Qué se mantiene estable dentro de /v1, qué cambios considera muveya incompatibles, cómo escribir un cliente que tolere cambios aditivos y dónde se anuncian los cambios. La versión de la API forma parte de la ruta. Todo lo documentado en esta pestaña vive bajo `/v1`, y `/v1` es la única API pública: otras rutas que usa la consola de muveya no son un contrato público, pueden cambiar en cualquier momento y las integraciones no deben llamarlas. ## El compromiso * **Dentro de `/v1`, los cambios son aditivos.** Una operación, un campo o un valor del que depende tu integración no se elimina ni se renombra dentro de `/v1`. * **Un cambio incompatible necesita una versión nueva.** Se publica como una nueva versión mayor en la ruta (`/v2`), con un período de migración. `/v1` nunca se modifica de forma incompatible. * **El contrato se verifica en cada cambio.** El contrato OpenAPI detrás de las páginas de **Endpoints** se genera desde el código de muveya, y cada cambio se compara con la versión anterior mediante una verificación automática de compatibilidad que rechaza los cambios incompatibles de la lista de abajo. La `version` que aparece dentro del documento OpenAPI es la revisión de ese documento. La versión de la API con la que te integras es el `/v1` de la ruta. ## Qué se considera incompatible muveya considera incompatibles estos cambios en `/v1`, y no los hace dentro de `/v1`: | Cambio | Ejemplo | | - | - | | Eliminar una operación o cambiar su `operationId` | Eliminar `GET /v1/orders` | | Eliminar un estado de respuesta documentado de una operación | Dejar de responder `404` donde estaba documentado | | Eliminar un parámetro de consulta, de ruta o de encabezado | Quitar `status` de `GET /v1/fulfillments` | | Agregar un parámetro nuevo **obligatorio** | Hacer obligatorio `limit` | | Quitar un valor aceptado de una enumeración de la solicitud | Dejar de aceptar `weekly` como `period` | | Hacer obligatoria una propiedad del cuerpo de la solicitud | Exigir `period` en `POST /v1/analytics/exports` | | Eliminar una propiedad de la respuesta | Quitar `hasMore` de las listas | | Convertir una propiedad garantizada de la respuesta en opcional | Hacer opcional `status` en `Order` | | Quitar un valor de una enumeración de la respuesta | Dejar de devolver `in_transit` como estado de caja | | Cambiar el tipo de un campo | Convertir `onHand` de entero a texto | ## Qué puede cambiar dentro de `/v1` Estos cambios son aditivos y pueden llegar en cualquier momento, anunciados en [Novedades](/docs/es/changelog): * Operaciones y recursos nuevos. * Parámetros de consulta y encabezados nuevos opcionales. * Campos nuevos opcionales en las respuestas. * Valores nuevos en las enumeraciones de respuesta, por ejemplo un estado de pedido nuevo, un `type` de movimiento de existencias nuevo o una clave de métrica de analítica nueva. * Valores nuevos de `code` de error. * Scopes nuevos. * Otra redacción en los textos para personas: `title` y `detail` de los errores, `label` del resumen gerencial, descripciones de esta referencia. * Valores operativos que la API informa en tiempo de ejecución, como el presupuesto de límite de uso en los encabezados de respuesta. Un campo que aparece porque una clave obtuvo un scope (por ejemplo, los campos de costo con `catalog.cost:read`) no es un cambio del contrato: siempre estuvo documentado como opcional. ## Escribe un cliente tolerante Interpreta solo los campos que usas. No falles cuando una respuesta trae un campo que no está en tu modelo. Da a cada `switch` sobre un estado, un tipo de movimiento o una clave de métrica una rama por defecto. Un valor nuevo no debe romper tu integración; regístralo y trátalo como "otro". Un campo marcado como opcional puede no venir. Nunca se envía como `null` en su lugar (salvo tres campos de analítica, `value`, `averageHours` y `maxAgeHours`, descritos en la referencia). Verifica que exista antes de leerlo. Maneja los códigos de error que conoces y usa el estado HTTP para cualquier código que todavía no conozcas. Consulta [Errores](/docs/es/api-reference/errors). `title`, `detail` y `label` cambian con el idioma y la redacción. Usa claves, códigos e ids. Los cursores son opacos y el orden de las claves JSON no tiene significado. ## Obsolescencia Hoy no hay ninguna operación ni campo de `/v1` marcado como obsoleto, y ninguna respuesta trae encabezados de obsolescencia. Cuando exista una `/v2`, `/v1` tendrá un período de retiro anunciado. El retiro se publicará en [Novedades](/docs/es/changelog) antes de aplicarse, y muveya prevé indicarlo en las respuestas con los encabezados estándar `Deprecation` y `Sunset`. ## Qué no está en `/v1` hoy Las funciones que no están documentadas en esta pestaña no están disponibles, por ejemplo crear o cambiar pedidos por la API, o los webhooks (consulta [Webhooks](/docs/es/api-reference/webhooks)). Si llegan, llegarán como cambios aditivos y se anunciarán en las novedades. El único formato de clave de API que se emite hoy es `mvy_test_` (consulta [Autenticación](/docs/es/api-reference/authentication)). ## Dónde se anuncian los cambios * [Novedades](/docs/es/changelog) lista los cambios visibles para clientes, del más reciente al más antiguo. * Las páginas de **Endpoints** se regeneran desde el contrato cada vez que cambia, en inglés, español y portugués. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.