---
title: Versionado y estabilidad
description: Qué partes de /api/v1 puedes tratar como contrato y cómo te enteras cuando algo va a cambiar.
url: https://notta.cl/docs/versionado
related:
  - https://notta.cl/docs/api-reference
  - https://notta.cl/docs/errors
  - https://notta.cl/docs/rate-limits
---

> Documentación de Notta en markdown. Índice completo: https://notta.cl/llms.txt — corpus entero: https://notta.cl/llms-full.txt

# Versionado y estabilidad

La API de Notta se versiona por path: todos los endpoints viven bajo `/api/v1`. Dentro de v1 el compromiso es **additive changes only** — lo existente no se rompe, lo nuevo se agrega al lado.

## Qué se preserva en v1

- Los campos existentes de request y response: nombre, tipo y semántica.
- Los códigos de error (`code`) documentados y la semántica de su `next_action`.
- Los paths y métodos de los endpoints documentados en la [Referencia de la API](/docs/api-reference).

## Qué puede agregarse sin aviso

- Campos nuevos en responses.
- Códigos de error nuevos, con `next_action` nuevos.
- Endpoints y eventos nuevos.

Escribe tu cliente como *tolerant reader*: ignora los campos que no reconoces y maneja los `next_action` desconocidos con un fallback (loguear y escalar), no con un crash.

## Cómo se anuncian los breaking changes

Un cambio incompatible solo llega con una versión nueva de la API (`/api/v2`). Si un cambio dentro de v1 resultara inevitable — por ejemplo, por exigencia normativa del SII — se anuncia en esta página y por email a los dueños de API keys activas, con un plazo de migración antes de aplicarse.

Hoy v1 es la única versión y no hay cambios incompatibles planificados. Todavía no publicamos un calendario formal de deprecación; cuando exista, va a vivir en esta página.

## Cambios

- **2026-06**: forma_pago y receptor completo (giro/dirección/comuna) pasan a obligatorios para factura 33/34. Un POST de emisión de tipo 33 o 34 ahora requiere `forma_pago` (1=Contado, 2=Crédito, 3=Sin costo) en el cuerpo y `giro`, `direccion` y `comuna` no vacíos en `receptor`. Exigencia normativa del SII para la carátula del DTE.

## Próximos pasos

- **[Referencia de la API](/docs/api-reference)** — los endpoints y shapes que este contrato protege.
- [Errores](/docs/errors) — el catálogo de `code` y `next_action` con semántica estable.
- [Rate limits](/docs/rate-limits) — los límites operativos de la API, complemento de este contrato.