Conceptos básicos
Qué es el acceso automático
Una agencia que ya ha iniciado sesión en tu web entra al portal de reservas con un solo clic, sin volver a escribir su usuario y su contraseña.
Tu servidor pide un código de acceso temporal al portal y redirige el navegador de la agencia con ese código. Las credenciales viajan de servidor a servidor, nunca a través del navegador.
Qué mejora respecto al método anteriorEl acceso antiguo enviaba usuario y contraseña en la dirección (
?utilizador=…&senha=…), de modo que quedaban en el historial del navegador, en los registros del servidor y en la cabecera Referer. Con este sistema solo viaja un código de un solo uso que caduca en 90 segundos.¿Buscas cómo se usa el portal?Este manual es solo para la integración técnica. El funcionamiento del portal (búsquedas, tarifas, reservas) está en el manual de usuario de Orbis Hoteles Pro.
ImportanteEl código caduca en 90 segundosPídelo en el momento en que la agencia pulsa el enlace y redirige de inmediato. No lo guardes ni lo reutilices: solo sirve una vez.
Configuración
Tus datos de acceso
| Dato | Valor |
|---|---|
| Dirección de tu portal | El dominio desde el que accedéis al portal de reservas. En los ejemplos de este manual aparece como https://tu-portal.ejemplo.com. |
| Endpoint | Siempre POST /api/sso/token, sobre esa misma dirección. |
| Clave de API | Te la enviamos por un canal seguro. Se muestra una sola vez: guárdala en el momento. |
| IP autorizada | La dirección IP pública desde la que saldrán las peticiones de tu servidor. Nos la indicas tú y la damos de alta antes de empezar. |
AtenciónLas peticiones deben salir desde la IP autorizadaDesde cualquier otra dirección la petición se rechaza con un error
403. Si vuestra IP de salida va a cambiar, avisadnos antes para añadir la nueva.La clave de API es un secretoDebe estar solo en tu servidor: nunca en código JavaScript, en el HTML ni en un repositorio público. Si sospechas que se ha visto comprometida, avísanos y la regeneramos.
Procedimiento
Cómo funciona, en cuatro pasos
Tu servidor pide el códigoLlamada
POST /api/sso/token con la clave de API y las credenciales de la agencia.El portal respondeDevuelve una dirección con el código incluido y su tiempo de validez.
Tu web redirigeEnvías el navegador de la agencia a esa dirección.
El portal abre la sesiónValida el código y las credenciales, y la agencia entra directamente.
Dónde colocar el enlaceEn cualquier punto de tu web donde la agencia ya esté identificada: un botón del panel, un enlace del menú o un acceso directo. El paso 1 se ejecuta cuando la agencia lo pulsa, no antes.
Integración
Paso 1: pedir el código de acceso
Para qué sirve
Obtener la dirección a la que redirigir el navegador de la agencia.
Cuándo se llama
En el momento en que la agencia pulsa el enlace, desde tu servidor.
La petición es POST, con la clave de API en la cabecera Authorization y el cuerpo en formato JSON:
POST /api/sso/token HTTP/1.1
Host: tu-portal.ejemplo.com
Authorization: Bearer TU_CLAVE_DE_API
Content-Type: application/json
{
"username": "usuario-de-la-agencia",
"password": "contrasena-de-la-agencia",
"redirect": "/"
}
| Campo | Obligatorio | Qué contiene |
|---|---|---|
| username | Sí | Usuario de la agencia en el motor de reservas. Máximo 100 caracteres. |
| password | Sí | Contraseña de la agencia. Máximo 200 caracteres. |
| redirect | No | Ruta interna del portal a la que llegar tras entrar. Debe empezar por / y no puede ser una dirección completa. Por defecto, /. |
Si todo es correcto, la respuesta es un 200 con esta forma:
{
"ok": true,
"url": "https://tu-portal.ejemplo.com/autologin?token=a1b2c3…",
"expires_in": 90
}
Error típicoLa petición agota el tiempo de esperaEl portal valida las credenciales contra el motor de reservas antes de emitir el código, así que la respuesta puede tardar unos segundos. Configura un tiempo de espera de al menos 20 segundos.
Integración
Paso 2: redirigir el navegador
Para qué sirve
Llevar a la agencia al portal con la sesión ya abierta.
Cuándo se hace
Inmediatamente después de recibir la respuesta correcta.
Redirige el navegador al valor del campo url tal y como llega, sin modificarlo ni añadirle parámetros:
header('Location: ' . $datos['url']);
exit;
Verificación en dos pasosSi la agencia tiene activada la verificación en dos pasos, el portal le pedirá su código de confirmación después del acceso automático. Es el comportamiento previsto y no indica ningún fallo en la integración.
Integración
Códigos de error
Cuando algo falla, la respuesta trae "ok": false y un campo error con un código estable.
{
"ok": false,
"error": "invalid_credentials",
"message": "Utilizador ou senha da agência rejeitados."
}
| HTTP | error | Qué significa y qué hacer |
|---|---|---|
| 400 | bad_request | Faltan campos obligatorios o redirect no es una ruta válida. Revisa la petición. |
| 401 | invalid_api_key | La clave de API falta o no es correcta. Revisa la cabecera Authorization. |
| 403 | ip_not_allowed | La petición no sale desde la IP autorizada. Avísanos para revisarlo. |
| 422 | invalid_credentials | El motor de reservas rechazó el usuario o la contraseña. Informa a la agencia. |
| 429 | too_many_attempts | Demasiados intentos fallidos. Espera lo que indique la cabecera Retry-After. |
| 503 | unavailable | El motor de reservas no está disponible. Vuelve a intentarlo más tarde. |
ImportanteUsa el campo error, no el mensajeEl campo
error es estable y es el que debe gobernar tu lógica. El campo message es texto de diagnóstico y no debe mostrarse tal cual a la agencia: redacta tú el aviso según el código recibido.Integración
Ejemplo completo en PHP
Función lista para adaptar. Devuelve la dirección de destino o el código de error.
const ORBIS_PORTAL = 'https://tu-portal.ejemplo.com';
const ORBIS_API_KEY = 'TU_CLAVE_DE_API';
function orbis_autologin($username, $password, $redirect = '/') {
$ch = curl_init(ORBIS_PORTAL . '/api/sso/token');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . ORBIS_API_KEY,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'username' => $username,
'password' => $password,
'redirect' => $redirect,
]),
]);
$cuerpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$datos = json_decode($cuerpo, true);
if ($status !== 200 || empty($datos['ok']) || empty($datos['url'])) {
error_log('Orbis SSO: HTTP ' . $status . ' - ' . ($datos['error'] ?? 'sin_codigo'));
return ['ok' => false, 'error' => $datos['error'] ?? 'unknown'];
}
return ['ok' => true, 'url' => $datos['url']];
}
$r = orbis_autologin($usuario_agencia, $clave_agencia, '/');
if (!$r['ok']) {
// Redacta el aviso segun $r['error'] y no redirijas.
return;
}
header('Location: ' . $r['url']);
exit;
Equivalente en otros lenguajesLa integración es una llamada HTTP corriente: cualquier cliente que permita enviar una cabecera y un cuerpo JSON sirve igual. Lo único imprescindible es que la llamada salga del servidor, nunca del navegador.
Criterio
Buenas prácticas
Pide el código al pulsar
No lo generes al cargar la página ni lo dejes preparado: caduca en 90 segundos y solo sirve una vez.
No guardes nada en caché
Ni la respuesta de la API ni la dirección con el código deben almacenarse en ninguna caché intermedia.
Registra los fallos
Guarda el código HTTP y el campo error en tu registro. Es lo primero que te pediremos si hay que diagnosticar algo.
No reintentes en bucle
Tras un error de credenciales, no repitas la llamada automáticamente: el portal aplica un límite de intentos por usuario.
Antes de poner en producción
- La clave de API está solo en el servidor, fuera del código público.
- Las peticiones salen desde la IP autorizada.
- El tiempo de espera de la llamada es de 20 segundos o más.
- Cada código de error tiene su mensaje redactado para la agencia.
- La redirección ocurre justo después de recibir la respuesta.
- Los fallos quedan registrados con el código HTTP y el campo error.
Soporte
Problemas frecuentes
La respuesta es 401 aunque la clave parece correcta.Comprueba que la cabecera sea exactamente
Authorization: Bearer <clave>, con un espacio entre Bearer y la clave, y que no se haya colado ningún espacio o salto de línea al copiarla.La respuesta es 403 desde el servidor de producción.La petición no sale desde la IP autorizada. Es habitual cuando hay varios servidores de salida o un proxy por delante. Indícanos la IP real desde la que salen las peticiones.
Al abrir la dirección aparece la pantalla de acceso del portal.El código ya se había usado o habían pasado más de 90 segundos. Cada clic debe generar un código nuevo; no reutilices la dirección ni permitas que se abra dos veces.
La agencia entra, pero le piden un código de confirmación.Tiene activada la verificación en dos pasos. Es el comportamiento correcto: el acceso automático ahorra escribir las credenciales, no sustituye al segundo factor.
La llamada tarda varios segundos.Es normal: el portal valida las credenciales contra el motor de reservas antes de emitir el código. Si supera los 20 segundos de forma habitual, avísanos.
¿Sigue sin funcionar?Escribe a tu contacto habitual en Pipeline Software indicando: la fecha y la hora de la petición, el código HTTP recibido, el valor del campo
error y la IP desde la que se hizo la llamada. Con esos cuatro datos podemos localizarla en nuestros registros.