Saltar al contenido principal

​
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:
EstadoDescripciónComportamiento
activeVersión totalmente compatibleRespuestas normales con el encabezado X-API-Version
deprecatedAún funcional pero programada para su retiradaLas respuestas incluyen encabezados de aviso de obsolescencia
sunsetRetirada del servicioDevuelve 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.
EncabezadoDescripción
DeprecationConforme a RFC 8594 - Fecha en que la versión quedó obsoleta
SunsetConforme a RFC 8594 - Fecha en que la versión será retirada
X-Deprecated-MessageMensaje 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:
  1. La versión anterior se marca como obsoleta
  2. Recibirás encabezados de aviso durante un periodo de obsolescencia recomendado de 6 meses
  3. 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

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')
  });
}
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: { }
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
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