Versionado y estabilidad

Qué partes de /api/v1 puedes tratar como contrato y cómo te enteras cuando algo va a cambiar.

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.
El catálogo de operaciones del MCP hereda este mismo contrato. Las operaciones que discover publica son additive-only: sacar o renombrar una operación es un cambio incompatible y sigue el proceso de deprecación de esta página. El manifiesto público /.well-known/mcp.json es la lista vigente.

Una precisión sobre los permisos: cada operación declara el scope que exige, y ese scope se exige solo a las conexiones MCP. Las API keys conservan su comportamiento actual; si una key tuya lee hoy una ruta sin tener el scope declarado, va a seguir leyéndola.

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: los endpoints y shapes que este contrato protege.
Errores: el catálogo de code y next_action con semántica estable.
Rate limits: los límites operativos de la API, complemento de este contrato.