---
title: "API versioning"
description: "/api/v1/ is the only public surface. Policy for compatible and major changes and how we announce each movement."
canonical: https://factura.com.do/en/desarrolladores/versionado
lang: en
generator: factura.com.do docs-index
---

Conventions 

# API versioning

Today `/api/v1/` is the only public surface. We do not use a version header, there are no parallel versions and we have not yet published a formal deprecation policy.

## Summary

Versioning lives in the URL. Every call starts with `/api/v1/<resource>`; there is no `Accept-Version`, no query params for versioning and no _feature flags_ visible from the API. The body and response shape is stable within the major version.

## /api/v1/ is the only public surface

If an endpoint or field does not appear under `/api/v1/`, do not treat it as a contract. Internal routes (for example, `/api/ApiToken/*`, `/api/Webhook/*`, `/api/enfc/*`) cover app functionality and may change without notice. When one of those routes is promoted to a public surface, it appears under `/api/v1/` and enters this documentation.

## Compatible vs. major changes

Your integration must tolerate compatible changes without new code. Major changes are never made on the current version.

### Compatible changes (no new version)

- Adding a new resource or endpoint.
- Adding an optional field to a request or response DTO.
- Adding a new value to an enum (as long as the client treats unknowns as 'other').
- Adding an optional header to the response.
- Adding a new event to the webhook catalog.

### Major changes (would go to /api/v2/)

- Renaming an existing field or changing its type.
- Removing a resource, endpoint, field or event.
- Changing the shape of PagedResult or the error envelope.
- Reassigning the meaning of an HTTP code on a specific endpoint.

## How we announce changes

When a v2 exists, it will appear at `/api/v2/` and we will maintain `/api/v1/` with prior notice. The support period duration is pending definition with the platform team; when published, this page will document it in a table with absolute dates.

Idempotency-Key is not yet part of the contract

If your integration needs safe retries, manage idempotency on your side (response cache with `documentId` as the key) until this page formally documents `Idempotency-Key`.

## Next steps

Next step 

## Continue here

- [  Errors Response conventions the API will keep stable in v1. ](/en/desarrolladores/errores)
- [  Webhooks Event catalog seeded from the initial migration. ](/en/desarrolladores/webhooks)