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.

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.