---
title: "Versionado de la API"
description: "/api/v1/ es la única superficie pública. Política de cambios compatibles, mayores y cómo anunciamos cada movimiento."
canonical: https://factura.com.do/desarrolladores/versionado
lang: es
generator: factura.com.do docs-index
---

Convenciones 

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

Idempotency-Key todavía no es parte del contrato

Si tu integración necesita reintentos seguros, gestiona la idempotencia en tu lado (caché de respuestas con `documentId` como llave) hasta que esta página documente `Idempotency-Key` formalmente.

## Siguientes pasos

Siguiente paso 

## Continúa por aquí

- [  Errores Convenciones de respuesta que la API mantendrá estables en v1. ](/desarrolladores/errores)
- [  Webhooks Catálogo de eventos sembrado desde la migración inicial. ](/desarrolladores/webhooks)