> ## Documentation Index
> Fetch the complete documentation index at: https://www.emissa.com.ar/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Changelog y compatibilidad

> Qué te podemos cambiar sin avisar y qué no, los seis meses de aviso, y las dos rupturas que hubo antes del primer cliente.

Qué te podemos cambiar sin avisarte, qué no, y qué cambió hasta hoy. Incluida la
ruptura que hubo, contada con lo que sí y lo que no se rompió.

## Lo que `/v1` promete

Mientras `v1` esté vigente:

| Se puede cambiar sin avisar | No se puede |
| - | - |
| Agregar campos nuevos en una respuesta | Quitar o renombrar un campo |
| Agregar parámetros opcionales | Cambiarle el tipo o la semántica a un campo |
| Agregar endpoints nuevos | Volver obligatorio algo que era opcional |
| Agregar valores nuevos a un enum de salida | Cambiar un código de estado |

> [!WARNING]
>
> **Y la contrapartida es tuya: un cliente tiene que tolerar campos que no
> conoce.** Ése es el contrato. Si tu deserializador falla ante una clave que no
> esperaba, vas a romperte con un cambio que nosotros tenemos derecho a hacer.

Dos reglas para tu cliente:

**1. No uses parseo estricto**

Nada que rechace campos desconocidos.

**2. Ramificá por el código de error, no por el mensaje**

El código es estable; el texto puede mejorarse. Ver [todos los
errores](https://www.emissa.com.ar/docs/guias/errores.md).

## Cómo se depreca una versión

Si alguna vez sale `v2` y `v1` se discontinúa:

**1. Las respuestas empiezan a avisar**

`v1` lleva las cabeceras `Deprecation` y `Sunset` (RFC 8594), con la fecha a
partir de la cual deja de responder.

**2. Con al menos seis meses de anticipación**

No es una cortesía: es la política.

> [!NOTE]
>
> **Hoy `v1` está vigente y no se manda ninguna de las dos cabeceras.** Medido: se
> listaron todas las cabeceras de una respuesta de `/v1` y del documento OpenAPI,
> y no aparece ninguna.
>
> Que estén ausentes es deliberado. Mandar un `Sunset` «por las dudas» te diría
> que migres cuando no hay a dónde.

> [!TIP]
>
> **Qué mirar en tu cliente:** loguear la presencia de esas dos cabeceras cuesta
> una línea y es la forma de enterarte sin leer un blog. Si algún día aparecen,
> tenés seis meses.

## El changelog

### 2026-07-27 · El prefijo de las API keys pasa de `fya_` a `emi_`

El producto se llamaba FacturaYa y pasó a llamarse Emissa. Con eso:

* Las claves **nuevas** nacen `emi_test_…` / `emi_live_…`.
* La cabecera de modo en las respuestas pasó de `X-Facturaya-Mode` a
  **`X-Emissa-Mode`**.

> [!TIP]
>
> **Ninguna clave dejó de funcionar.** La autenticación resuelve por **hash del
> secreto completo**, no por el prefijo: el prefijo es metadato de presentación
> y no participa de validar nada. No hubo migración de datos, y **las claves
> `fya_` siguen autenticando sin plazo de vencimiento**.

> [!WARNING]
>
> **Lo que sí se rompió**, y conviene decirlo: si tu código validaba el formato
> de la clave con un `^fya_`, o leía la cabecera `X-Facturaya-Mode`, eso dejó de
> funcionar. El renombre de una cabecera de respuesta es exactamente lo que la
> política de arriba prohíbe hacer sin aviso.

> [accordion] Cómo está protegido que las claves viejas sigan andando
>
> Hay una prueba de regresión, y la prueba está verificada por mutación. Poniendo la
> «validación razonable» que alguien podría agregar:
>
> ```js theme={null}
> if (!rawKey.startsWith('emi_')) return null;
> ```
>
> el caso falla enseguida:
>
> ```
> ● validate › una key con el prefijo HEREDADO sigue autenticando
>   expect(received).not.toBeNull()
>   Received: null
> ```
>
> Sin esa prueba, ese `if` de una línea desconectaría en silencio a todo integrador
> que no haya rotado su clave, y el resto de la suite seguiría en verde.

### 2026-07-26 · Las API keys se mandan en `X-API-Key`

Antes viajaban en `Authorization: Bearer <key>`. Ahora van en su propia cabecera.

Es una **ruptura del lado del pedido**, y es la de mayor impacto de las dos. Lo que
la hace tolerable es que **no falla en silencio**: el camino viejo devuelve un
`401` que dice exactamente qué hacer.

> [accordion] La respuesta del camino viejo
>
> ```json theme={null}
> {
>   "statusCode": 401,
>   "errorCode": "API_KEY_WRONG_HEADER",
>   "message": "Las API keys van en el header X-API-Key, no en Authorization. Usá: X-API-Key: emi_...",
>   "details": "La key llego en Authorization; va en X-API-Key desde la version 1"
> }
> ```
>
> Está medida. No es un «token inválido» genérico: nombra la cabecera correcta.

## Por qué esas dos rupturas fueron posibles

**Porque ocurrieron antes del primer cliente.** En julio de 2026 no había un solo
integrador externo, así que el costo de romper era cero y el beneficio —un
contrato coherente con el nombre del producto y una cabecera de autenticación que
no se confunde con un JWT— era permanente.

> [!WARNING]
>
> **Bajo la política que rige ahora, ninguna de las dos sería admisible sin seis
> meses de aviso.** Renombrar una cabecera de respuesta y cambiar dónde viaja la
> credencial están las dos en la columna de «no se puede».

Un changelog que arranca vacío es un changelog en el que no se confía: o el
producto no cambió nunca, o los cambios no se anotaron. Estos dos están acá porque
pasaron.

## Lo que no está versionado, y por qué

No todo el backend es `/v1`:

| Superficie | ¿Versionada? | Para quién |
| - | - | - |
| `/v1/*` | **Sí**, con esta política | Tu integración |
| `/health`, `/ready`, `/metrics` | No | Operación del servicio |
| `/openapi.json` | No | Descubrimiento: lo lee quien todavía no sabe qué versión usar |
| La superficie interna del panel | **No, y sin promesas** | El panel. No la uses |

> [!WARNING]
>
> La última es la que importa: hay endpoints que el panel usa y que **no tienen
> política de compatibilidad**. No están en [la referencia](https://www.emissa.com.ar/docs/api-reference) a
> propósito. Si encontrás uno, **no lo integres**: puede cambiar sin aviso
> porque nadie prometió lo contrario.

## Qué sigue

> [card] [Todos los errores](https://www.emissa.com.ar/docs/guias/errores.md)
>
> Ramificá por código, no por texto.

> [card] [Referencia de la API](https://www.emissa.com.ar/docs/api-reference)
>
> El contrato de `/v1`, generado desde el código.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.