Versionado de la API
Hoy /api/v1/ es la única superficie pública. No usamos cabecera de versión, no hay versiones paralelas y aún no publicamos política formal de deprecación.
Resumen
El versionado vive en la URL. Cada llamada empieza con /api/v1/<recurso>; no hay Accept-Version, no hay query params para versionar y no hay feature flags visibles desde la API. La forma de cuerpo y de respuesta es estable dentro de la mayor.
/api/v1/ es la única superficie pública
Si un endpoint o campo no aparece bajo /api/v1/, no lo trates como contrato. Las rutas internas (por ejemplo, /api/ApiToken/*, /api/Webhook/*, /api/enfc/*) cubren funcionalidad de la app y pueden cambiar sin previo aviso. Cuando una de esas rutas se promueve a superficie pública, aparece bajo /api/v1/ y entra en esta documentación.
Cambios compatibles vs. cambios mayores
Tu integración debe tolerar los cambios compatibles sin código nuevo. Los cambios mayores nunca se hacen sobre la versión vigente.
Cambios compatibles (sin nueva versión)
- Agregar un recurso o endpoint nuevo.
- Agregar un campo opcional a un DTO de request o response.
- Agregar un valor nuevo a un enum (siempre que el cliente trate los desconocidos como 'otros').
- Agregar una cabecera opcional al response.
- Agregar un evento nuevo al catálogo de webhooks.
Cambios mayores (entrarían a /api/v2/)
- Renombrar un campo existente o cambiar su tipo.
- Eliminar un recurso, endpoint, campo o evento.
- Cambiar la forma del PagedResult o del envelope de errores.
- Reasignar el significado de un código HTTP en un endpoint específico.
Cómo anunciamos el cambio
Cuando exista una v2, aparecerá en /api/v2/ y mantendremos /api/v1/ con anuncio previo. La duración del periodo de soporte está pendiente de definir con el equipo de plataforma; cuando se publique, esta página la documentará en una tabla con fechas absolutas.