Versiones

La API se versiona por fecha, como Stripe. Cada respuesta dice en el encabezado Fiscalisto-Version en qué versión se escribió:

HTTP/1.1 200 OK
Fiscalisto-Version: 2026-10-24

Hoy hay una sola versión, 2026-10-24.

Qué es una versión nuevaCopiar enlace a esta sección

Lo que no rompe nada llega sin versión nueva, en la que ya usa: rutas, campos, eventos, parámetros opcionales y códigos de error nuevos. Escriba su integración para que ignore los campos que no conoce (los SDKs ya lo hacen).

Una versión nueva es para lo que sí cambiaría lo que ya funciona: un campo que cambia de nombre o de significado, o que deja de existir. Cada una se anuncia en Cambios y por correo en Avisos por correo, con lo que cambió y cómo adaptarse.

Qué versión recibeCopiar enlace a esta sección

1. La de la solicitud, si manda el encabezado Fiscalisto-Version. Los SDKs mandan la versión para la que se hicieron, así que un SDK siempre recibe lo que espera.
2. La de su cuenta, si no lo manda (por ejemplo con curl). Su cuenta queda en la versión más reciente del día en que la creó, y no se mueve sola.

Una versión que no existe responde 400 con api_version_invalid y la lista de las que hay.

curl https://api.fiscalisto.com/v1/account \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -H "Fiscalisto-Version: 2026-10-24"

GET /v1/account dice la de su cuenta (api_version) y la más reciente (latest_api_version).

Moverse a una versión nuevaCopiar enlace a esta sección

1. Lea en Cambios qué cambió.
2. Pruébela en modo de pruebas mandando Fiscalisto-Version con la nueva fecha (o actualice el SDK).
3. Cuando todo funcione, mueva su cuenta: lo que llama sin encabezado y los webhooks sin versión propia pasan a la nueva.

curl https://api.fiscalisto.com/v1/account \
  -H "Authorization: Bearer $FISCALISTO_API_KEY" \
  -d '{ "api_version": "2026-10-24" }' \
  -H "Content-Type: application/json"

Se cambia con una llave de la cuenta con todos los permisos (no con una de solo lectura, restringida a emisores ni de un entorno de prueba), y queda en Desarrolladores › Actividad. Puede volver a la anterior de la misma forma.

WebhooksCopiar enlace a esta sección

Cada evento trae api_version, la versión en la que se escribió su data.object. Un endpoint recibe sus eventos en la versión de su cuenta, o en la suya propia si la tiene (api_version al crearlo o cambiarlo con POST /v1/webhook_endpoints/{id}; null vuelve a la de la cuenta).

Para mover los webhooks sin cortes: cree un segundo endpoint con la versión nueva, adapte su código para recibir las dos, y borre el viejo.

En los SDKsCopiar enlace a esta sección

Cada SDK trae la versión para la que se hizo y la manda en cada solicitud. Para pedir otra, o ninguna (la de la cuenta):

const fiscalisto = new Fiscalisto("fk_test_…", { apiVersion: "2026-10-24" }); // null: la de la cuenta

fiscalisto = Fiscalisto("fk_test_…", api_version="2026-10-24")  # None: la de la cuenta

$fiscalisto = new Fiscalisto('fk_test_…', ['api_version' => '2026-10-24']); // null: la de la cuenta

client, err := fiscalisto.NewClient("fk_test_…", fiscalisto.WithAPIVersion("2026-10-24")) // "": la de la cuenta

var client = new FiscalistoClient(ClientOptions.builder().apiKey("fk_test_…").apiVersion("2026-10-24").build());

var client = new FiscalistoClient("fk_test_…", new FiscalistoClientOptions { ApiVersion = "2026-10-24" });

Una respuesta guardada por idempotencia se repite tal como se contestó la primera vez, en esa versión.