Versionado y deprecaciones

Versiones #

El API está en la versión mayor v1, que va en la ruta (/v1/gateway/...). Dentro de v1 solo se hacen cambios compatibles.
Los SDK siguen SemVer alineado con el API: la versión mayor del SDK es la mayor del API (1.x habla con v1). Todos están hoy en 1.1.0 (changelog).

Cambios compatibles (pueden llegar sin aviso) #

Operaciones, módulos y eventos de webhook nuevos.
Campos nuevos en las respuestas y en el resource de los webhooks (la version del evento no cambia).
Parámetros opcionales nuevos.
Valores nuevos en enumeraciones de respuesta (estados, categorías).

Escribe tu integración para tolerarlos: ignora campos que no conoces, no valides el catálogo de eventos contra una lista cerrada y trata los estados desconocidos como “pendiente de revisar”.

Cambios incompatibles #

Quitar o renombrar campos u operaciones, volver obligatorio un parámetro o cambiar un tipo exige una nueva versión mayor (/v2) o, dentro de v1, un proceso de deprecación con fecha de retiro.

Cómo te enteras de una deprecación #

Una operación deprecada sigue funcionando, pero responde con cabeceras RFC 8594:

HTTP
Deprecation: true
Sunset: Sat, 31 Oct 2027 23:59:59 GMT
Link: </v1/gateway/...>; rel="successor-version"

Los cinco SDK detectan esas cabeceras y registran un solo aviso por operación (no uno por llamada), para que lo veas en tus logs antes de la fecha de retiro:

SDK	Dónde aparece el aviso
Python	Logger `compense_gateway` (nivel `WARNING`)
JavaScript / TS	`logger.warn` (por defecto `console`)
PHP	El logger PSR-3 que pases en `logger:`; si no, un `E_USER_DEPRECATED` silenciado (Laravel y Symfony lo envían a su canal de deprecaciones)
.NET	`ILogger`, categoría `Compense.Sdk`
Go	`WithLogger` (por defecto `slog.Default()`)

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("compense_gateway").setLevel(logging.WARNING)   # aquí llegan los avisos

const client = new CompenseClient({
  apiKey: process.env.COMPENSE_API_KEY!,
  logger: { warn: (msg: string) => myLogger.warn({ source: "compense" }, msg) },
});

$client = new CompenseClient(apiKey: getenv('COMPENSE_API_KEY'), logger: $psr3Logger);

builder.Logging.AddFilter("Compense.Sdk", LogLevel.Warning);
builder.Services.AddCompense(builder.Configuration.GetSection("Compense"));

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil))))

curl -sI "https://sandbox.dev.compense.co/gw/v1/gateway/health/" -H "X-API-Key: $COMPENSE_API_KEY" \
  | grep -iE '^(deprecation|sunset|link):'

Alerta sobre los avisos

Crea una alerta en tu plataforma de logs para los avisos de deprecación de Compense: es la forma más barata de no enterarte de un retiro el día que ocurre.

Deprecaciones vigentes #

Qué	Desde	Reemplazo
Rutas sin prefijo de versión `/gateway/...`	v1	`/v1/gateway/...` (los SDK ya usan las nuevas)
SDK Python 1.0: `fx.quote/convert(from_currency=, to_currency=)`	1.1.0	`sell_currency=`, `buy_currency=`
SDK Python 1.0: `test_clocks.create(name=)`, `test_clocks.advance(by_seconds=)`	1.1.0	`create(frozen_time=)`, `advance(delta_seconds=)`
SDK Python 1.0: `sandbox.trigger_webhook`	1.1.0	`webhooks.endpoints.send_test`
SDK Python 1.0: `sandbox.simulate.wallet_transfer_advance` / `credit_disburse_advance`	1.1.0	`simulate.wallet_transfer` / `simulate.credit_disbursement`

Los nombres antiguos del SDK de Python siguen funcionando con un DeprecationWarning hasta la 2.0.

Los SDK de JavaScript, PHP, .NET y Go empezaron en 1.1.0 y solo traen los nombres del contrato.