---
title: "Versionado"
description: "Cómo se versiona la API de Matchai: /v1 en la URL, qué cambios llegan sin versión nueva, qué es incompatible y cómo se anuncian las obsolescencias."
last_updated: "2026-10-21"
lang: "es"
status: "coming-soon"
canonical: "https://matchai.co/docs/es/developers/versioning"
---
# Versionado
> Cómo se versiona la API de Matchai: /v1 en la URL, qué cambios llegan sin versión nueva, qué es incompatible y cómo se anuncian las obsolescencias.
**Próximamente. Esto se documenta antes del lanzamiento para que puedas planificar tu integración; todavía no está disponible.**
Source: https://matchai.co/docs/es/developers/versioning
La API de Matchai tiene versiones para que una integración que construyas siga funcionando. Esta página explica qué se mantiene igual, qué puede cambiar sin que tengas que hacer nada y cómo te enteras de los cambios que requieren tu atención.
## La versión está en la ruta [#the-version-is-in-the-path]
La versión principal forma parte de cada dirección:
```text title="Base URL"
https://api.matchai.co/v1
```
Los eventos de webhook llevan la misma versión en su cuerpo, como `"api_version": "v1"`. Una dirección que empieza con `/v1` se comporta como dice esta documentación mientras `/v1` exista.
Hasta que la API esté abierta, esta documentación es una vista previa. El archivo del contrato tiene la versión `1.0.0-preview`, y los detalles todavía pueden cambiar antes del lanzamiento. Cuando la API abra, las reglas de esta página se aplicarán a `/v1`.
## Cambios que no necesitan una versión nueva [#changes-that-do-not-need-a-new-version]
Matchai puede publicar estos cambios en cualquier momento, sin una versión nueva y sin más aviso que el [registro de cambios](https://matchai.co/docs/es/developers/changelog):
- Endpoints nuevos, tipos de eventos de webhook nuevos y alcances nuevos. Una conexión nunca obtiene un alcance que no se le haya concedido.
- Campos opcionales nuevos en las solicitudes y parámetros de consulta nuevos.
- Campos nuevos en las respuestas y en el contenido de los webhooks.
- Valores nuevos en un enum, como un `status` nuevo, una profesión nueva o un tipo de evento nuevo.
- Códigos de error nuevos y tipos de error nuevos.
- Un orden diferente de los campos en un objeto JSON.
- Cambios en la longitud o el formato de los ids y los cursores. Los ids son opacos.
- Correcciones de comportamientos que no coincidían con esta documentación.
Así que escribe tu cliente para que los espere:
- **Ignora los campos que no conoces.**
- **Trata un valor de enum desconocido como "otro".** No dejes que tu código falle por eso, y no adivines su significado.
- **Nunca analices ni construyas ids.** Guárdalos y devuélvelos tal cual.
- **Decide según el `code` de un error, y recurre a su `type` y a su estado** cuando encuentres un código que no conoces. Consulta [errores](https://matchai.co/docs/es/developers/errors).
- **Ignora los eventos de webhook que no manejas.** Responde `2xx` y sigue adelante.
## Cambios incompatibles [#breaking-changes]
Un cambio incompatible es uno que puede hacer que una integración correcta deje de funcionar. Estos cambios siempre se publican como una versión principal nueva, junto a la anterior:
- Quitar o cambiar el nombre de un endpoint, un campo, un parámetro de consulta, un valor de enum, un tipo de evento o un alcance.
- Cambiar el tipo, el formato o el significado de un campo existente.
- Hacer obligatorio un campo opcional de la solicitud, o agregar uno nuevo que sea obligatorio.
- Rechazar solicitudes que antes se aceptaban, al endurecer la validación.
- Cambiar el estado HTTP o el `code` que produce una situación existente.
- Cambiar cómo funciona la autenticación, o reducir lo que permite un alcance.
Una versión principal nueva, como `/v2`, funciona junto a `/v1`. Nunca reemplaza a `/v1` en su lugar, y no se migra nada a ella por ti.
## Obsolescencia [#deprecation]
Matchai no retira una versión, un endpoint ni un campo sin avisarte primero. Una obsolescencia se **anuncia con antelación en el registro de cambios**, y cada anuncio dice:
- qué se retira y qué lo reemplaza;
- cómo hacer la transición;
- qué tienes que hacer, si es que hay algo.
El anuncio llega mucho antes de que se elimine el comportamiento anterior, para que tengas tiempo de hacer la transición. Lee el [registro de cambios](https://matchai.co/docs/es/developers/changelog) cuando planifiques un lanzamiento, y cuando no hayas tenido noticias durante un tiempo.
## El servidor MCP tiene su propio versionado [#the-mcp-server-is-versioned-separately]
El [servidor MCP](https://matchai.co/docs/es/developers/mcp-server) informa su propia versión en `serverInfo.version`, una versión semántica que cambia cuando se agrega una herramienta o un campo, o cuando cambia su estructura. Las herramientas se describen al asistente cada vez que se conecta, así que un cliente que se comporta correctamente detecta las herramientas nuevas sin ningún cambio de tu parte.
Dónde se anuncian los cambios y las obsolescencias.
Cómo decidir según códigos que pueden aumentar con el tiempo.
El contrato de /v1, y el archivo OpenAPI para descargar.
## Sitemap
- [Todas las páginas de la documentación de Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/es/llms.txt)