Guía de versionado de la API

La API de Firma utiliza versionado basado en encabezados mediante el encabezado X-API-Version. Esto te permite especificar qué versión de la API quieres usar, con avisos de obsolescencia automáticos y un proceso de retirada estructurado.

Cómo especificar una versión

Incluye el encabezado X-API-Version en tu solicitud:

curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);

import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)

Si se omite el encabezado X-API-Version, la API utiliza de forma predeterminada la versión estable actual (actualmente 1).

Ciclo de vida de una versión

Cada versión de la API pasa por tres etapas:

Estado	Descripción	Comportamiento
active	Versión totalmente compatible	Respuestas normales con el encabezado `X-API-Version`
deprecated	Aún funcional pero programada para su retirada	Las respuestas incluyen encabezados de aviso de obsolescencia
sunset	Retirada del servicio	Devuelve el error `410 Gone`

Encabezados de respuesta

Para versiones activas

X-API-Version: 1

Para versiones obsoletas

Cuando una versión queda obsoleta, se incluyen los siguientes encabezados en cada respuesta:

X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.

Encabezado	Descripción
`Deprecation`	Conforme a RFC 8594 - Fecha en que la versión quedó obsoleta
`Sunset`	Conforme a RFC 8594 - Fecha en que la versión será retirada
`X-Deprecated-Message`	Mensaje de aviso legible para humanos

Respuestas de error

Encabezado de versión no válido

// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}

Versión no admitida

// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}

Versión retirada (sunset)

// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}

Política de cambios incompatibles

Los cambios incompatibles solo se introducen en incrementos de versión mayor (por ejemplo, v1 → v2). Los cambios compatibles, como nuevos campos opcionales o nuevos endpoints, no requieren una nueva versión.

Cuando se publica una nueva versión mayor:

La versión anterior se marca como obsoleta
Recibirás encabezados de aviso durante un periodo de obsolescencia recomendado de 6 meses
Tras la fecha de retirada, la versión antigua devuelve 410 Gone

¿Qué constituye un cambio incompatible?

Los cambios incompatibles incluyen:

Eliminar o renombrar campos existentes
Cambiar tipos de campos o reglas de validación
Eliminar endpoints
Cambiar los requisitos de autenticación
Modificar los límites de tasa de forma significativa

Los cambios compatibles incluyen:

Añadir nuevos campos opcionales
Añadir nuevos endpoints
Añadir nuevos valores de enumeración (si tu cliente gestiona los valores desconocidos correctamente)
Mejorar los mensajes de error

Buenas prácticas

Comprueba siempre los encabezados de obsolescencia

Implementa comprobaciones automatizadas en el código de tu cliente de la API para detectar los encabezados Deprecation y Sunset. Registra avisos cuando estos encabezados estén presentes.

const response = await fetch(url, options);

if (response.headers.get('Deprecation')) {
  console.warn('API Deprecation Warning:', {
    deprecation: response.headers.get('Deprecation'),
    sunset: response.headers.get('Sunset'),
    message: response.headers.get('X-Deprecated-Message')
  });
}

Especifica la versión de forma explícita

En lugar de depender de la versión predeterminada, especifica siempre el encabezado X-API-Version de forma explícita. Esto evita cambios incompatibles inesperados cuando cambia la versión predeterminada.

// Bien - versión explícita
headers: { 'X-API-Version': '1' }

// Evitar - depende del valor predeterminado
headers: { }

Suscríbete a las actualizaciones del registro de cambios

Mantente informado sobre los próximos cambios suscribiéndote al registro de cambios o a los anuncios de la API. Esto te da aviso anticipado de:

Nuevas publicaciones de versiones
Calendarios de obsolescencia
Cambios incompatibles
Guías de migración

Prueba las nuevas versiones con antelación

Cuando se anuncie una nueva versión, prueba tu integración con ella mucho antes de la fecha de retirada de la versión antigua. Esto te da tiempo para:

Identificar cambios incompatibles en tu implementación
Actualizar tu código y dependencias
Probar a fondo en un entorno de pruebas
Desplegar con confianza antes de la fecha límite

Estado de la versión actual

La versión activa actual es v1 y no hay ninguna obsolescencia programada por el momento.

Cuando se publiquen nuevas versiones o se anuncien calendarios de obsolescencia, esta guía se actualizará con las fechas específicas y la información de migración.

Recursos relacionados

Autenticación

Aprende sobre la autenticación con Clave API y los tokens JWT

Guía de configuración completa

Comienza con la API de Firma

Webhooks

Configura notificaciones de webhook para eventos

Referencia de API

Explora todos los endpoints de la API

Guías de Inicio

Guías avanzadas

Versionado de la API

Guía de versionado de la API

Cómo especificar una versión

Ciclo de vida de una versión

Encabezados de respuesta

Para versiones activas

Para versiones obsoletas

Respuestas de error

Encabezado de versión no válido

Versión no admitida

Versión retirada (sunset)

Política de cambios incompatibles

¿Qué constituye un cambio incompatible?

Buenas prácticas

Estado de la versión actual

Recursos relacionados

Autenticación

Guía de configuración completa

Webhooks

Referencia de API

​Guía de versionado de la API

​Cómo especificar una versión

​Ciclo de vida de una versión

​Encabezados de respuesta

​Para versiones activas

​Para versiones obsoletas

​Respuestas de error

​Encabezado de versión no válido

​Versión no admitida

​Versión retirada (sunset)

​Política de cambios incompatibles

​¿Qué constituye un cambio incompatible?

​Buenas prácticas

​Estado de la versión actual

​Recursos relacionados

Autenticación

Guía de configuración completa

Webhooks

Referencia de API

Guía de versionado de la API

Cómo especificar una versión

Ciclo de vida de una versión

Encabezados de respuesta

Para versiones activas

Para versiones obsoletas

Respuestas de error

Encabezado de versión no válido

Versión no admitida

Versión retirada (sunset)

Política de cambios incompatibles

¿Qué constituye un cambio incompatible?

Buenas prácticas

Estado de la versión actual

Recursos relacionados