Autenticación y firmas API
Cada solicitud a la API de Xeni debe incluir una firma válida en el encabezado Authorization. Esto se aplica a todos los productos API: hoteles, automóviles, vuelos, actividades, complejos turísticos, ofertas y contenido. Las firmas se generan utilizando su clave y secreto API y caducan después de 30 minutos. Este artículo cubre cómo generar, usar y actualizar firmas.
Cómo funciona la autenticación
- Envía su clave API, secreto y una marca de tiempo Unix al punto final de generación de firma.
- La API devuelve una firma (un token JWT firmado).
- Incluye esta firma en el encabezado
Authorizationde todas las llamadas API posteriores. - Cuando la firma está a punto de caducar, generas una nueva.
Generando una firma
Punto final
POST /identity/v2/auth/generate
Cuerpo de solicitud
| Parámetro | Tipo | Requerido | Descripción | XENIKBP H20
|---|---|---|---|
apikey | string | Sí | Su API Xeni clave. |
secret XENIKBPH_39__ | string | Sí | Su API Xeni secreto. |
marca de tiempo | entero | Sí | Actual Marca de tiempo de Unix en segundos (no milisegundos). |
Solicitud de ejemplo
POST https://api.travelapi.ai/identity/v2/auth/generateContent-Type: application/json
{ "api_key": "eb8c1638-7fde-48f3-98fe-7ea8d06327d7", "secret": "your-secret-here", "timestamp": 1700000000}
Ejemplo de respuesta
{
"signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Usando la firma
Pase la firma como valor del encabezado Authorization en cada llamada API:
GET /api/v2/{product}/endpoint
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Caducidad de la firma
Las firmas son válidas por 30 minutos desde el momento en que se generan. Después de eso, cualquier llamada a la API que utilice una firma caducada devolverá un error de autenticación.
Recomendado: estrategia de actualización automática
Para evitar interrupciones durante las sesiones activas, recomendamos actualizar su firma proactivamente en lugar de esperar a que caduque. Un patrón común:
- Almacenar la firma y la hora en que se generó.
- Verifique la antigüedad de la firma antes de cada llamada a la API (o en un temporizador recurrente).
- Si a la firma le quedan menos de 5 minutos, genera una nueva.
Ejemplo: Lógica de actualización automática (JavaScript)
class SignatureManager { constructor(apiKey, secret, baseUrl) { this.apiKey = apiKey; this.secret = secret; this.baseUrl = baseUrl; this.signature = null; this.expiresAt = null; }
async generateSignature() { const response = await fetch(${this.baseUrl}/identity/v2/auth/generate, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ api_key: this.apiKey, secret: this.secret, timestamp: Math.floor(Date.now() / 1000) }) });
const data = await response.json(); this.signature = data.signature; this.expiresAt = Date.now() + (30 60 1000); // 30 minutes return this.signature; }
needsRefresh() { if (!this.signature || !this.expiresAt) return true; // Refresh if less than 5 minutes remaining return (this.expiresAt - Date.now()) < (5 60 1000); }
async getSignature() { if (this.needsRefresh()) { await this.generateSignature(); } return this.signature; }}
Ejemplo: lógica de actualización automática (Python)
import timeimport requests
class SignatureManager: def init(self, apikey, secret, baseurl): self.apikey = apikey self.secret = secret self.baseurl = baseurl self.signature = None self.expires_at = 0
def generatesignature(self): response = requests.post( f"{self.baseurl}/identity/v2/auth/generate", json={ "apikey": self.apikey, "secret": self.secret, "timestamp": int(time.time()) } ) data = response.json() self.signature = data["signature"] self.expires_at = time.time() + (30 * 60) # 30 minutes return self.signature
def needsrefresh(self): if not self.signature: return True return (self.expiresat - time.time()) < (5 * 60) # 5-min threshold
def getsignature(self): if self.needsrefresh(): self.generate_signature() return self.signature
Errores de autenticación comunes
| HTTP Estado | Causa | Resolución |
|---|---|---|
401 | Falta o Autorización encabezado | Asegúrese de incluir la firma en el encabezado. |
401 | Expirado firma | Generar una nueva firma. Las firmas caducan después de 30 minutos. |
401 | Clave API no válida o secret | Verifique que sus credenciales sean correctas y active. |
400 | La marca de tiempo está demasiado lejos del servidor time | Asegúrese de que el reloj de su sistema sea preciso. Utilice Math.floor(Date.now() / 1000) o equivalente. |
Mejores prácticas de seguridad- Nunca exponga su secreto de API en el código del lado del cliente. Toda la generación de firmas debe realizarse en el lado del servidor.
- Almacene las credenciales de forma segura. Utilice variables de entorno o un administrador de secretos; nunca codifique las credenciales en los archivos fuente.
- Rote los secretos con regularidad. Comuníquese con su representante de cuenta Xeni para rotar su secreto de API.
- Supervise los errores 401. Un aumento en los errores de autenticación puede indicar que las credenciales están comprometidas.