Recursos para desarrolladores

Añadir un widget de búsqueda en su sitio web o blog para enviar a tus visitantes directamente a nuestro sistema de reservas.

El Widget de búsqueda fue desarrollado para tener una mirada neutral y estandarizada, mezclando suavemente a tu página y facilitar el reconocimiento por parte de sus visitantes.

Para obtener los mejores resultados, aplique el widget de búsqueda en la parte superior de la página, en una barra lateral.

Si su sitio web se basa en la plataforma WordPress.org Hemos creado un plugin para facilitar la incorporación Widget de búsqueda.

Para instalarlo, descargarlo página del plugin en WordPress.org ; o - A través de la interfaz administrativa - haga clic en "Plugins" / "Crear Nuevo" del menú y buscar "pousadinhas". Asegúrese de seleccionar el plugin " Pousadinhas Search Widget "!

Si su sitio web se basa en la plataforma Joomla! Hemos creado un plugin para facilitar la incorporación Widget de búsqueda.

Para instalarlo, descargarlo aquí y - a través de la interfaz de administración - hacer clic en "Extensiones" menu / "Instalar / Desinstalar" continuar con la instalación. Para obtener más información, visite página del plugin en el directorio de extensiones Joomla.org .

Si tiene la intención de utilizarlo "in situ" - es decir, sin el acoplamiento hasta el borde de la ventana - añade el siguiente {pousadinhas} el contenido deseado.


a) Configuración

A continuación, utiliza el buscador de la izquierda para configurar el Widget de búsqueda y previsualizar el resultado en el panel derecho.

Opciones WidgetAvance
Procesamiento de ...
Seleccione el destino de búsquedas realizadas con el widget.?
Desactive esta opción para que los campos de fecha no se inicializan con valores predeterminados.?
Seleccione el idioma de su página.?
Seleccione la esquina de la pantalla en la que desea acoplar el widget.?
Marque esta opción si hay limitación de espacio en el diseño de su página.?
Si la página es segura (protocolo https), debe seleccionar esta opción.?

b) Implementación

Paso 1. El siguiente código debe ser insertado en su página, justo encima de la etiqueta </HEAD> cerrar cabecera.

Paso 2. El siguiente código debe ser insertado en su página, exactamente donde desea que aparezca el widget de búsqueda.

1. Registro de aplicación

Para utilizar el El Pousadinhas API es necesario que la aplicación cliente se ha registrado en nuestra plataforma. Por favor, póngase en contacto con nosotros vía e-mail recursos@pousadinhas.com.br y proporcionar el nombre y una descripción detallada de la aplicación o integración que quieren desarrollar, indicando las características que va a utilizar.

2. Elaboración y aprobación

Con la aprobación de su solicitud de registro de solicitud, vamos a crear una cuenta para usted en nuestro entorno de pruebas y expediremos acceder a las credenciales para su uso en el desarrollo.

Completado el desarrollo, es necesario ponerse en contacto con nosotros de nuevo, con instrucciones para acceder a la aplicación, por lo que nuestro equipo puede realizar pruebas. Sólo después de la aprobación de la solicitud, expediremos acceso credenciales para el entorno de producción.

3. Credenciales de acceso

Las credenciales de acceso de las aplicaciones cliente en nuestra plataforma se componen de dos elementos de información:

  • client_id - Identificador de la aplicación cliente, público;
  • client_secret - El secreto de la aplicación cliente, privado;

Credenciales de acceso no se pueden utilizar para el acceso directo El Pousadinhas API . Pero son necesarias para obtener un token de acceso ( access_token ), Con el mecanismo de autenticación de API; a continuación, esta señal se utiliza para acceder a la API.

La aplicación cliente debe mantener client_secret en absoluto secreto y deberá solicitar la devolución de la misma cuando se produzca algún supuesto compromiso.

En el caso de las aplicaciones que se desplegarán en los dispositivos no son de confianza (por ejemplo, aplicaciones móviles), la client_secret DEBE MANTENERSE eclipsado. Además, la aplicación cliente debe solicitar al usuario hacer la actualización se aplica cada vez que hay una indicación del cambio de error client_secret .

4. El cifrado de datos

Todas las solicitudes y respuestas enviados y recibidos en tanto mecanismo de autenticación y API, utilizan codificación UTF-8.

5. Mecanismo de autenticación

El mecanismo de autenticación El Pousadinhas API se basa en la norma OAuth 2.0 . Todo el acceso a la API se debe realizar con un token de acceso ( access_token ) Previamente obtenidos a través de este mecanismo.

Las rutinas de la obtención y renovación de credenciales de acceso se realiza a través de POST tipo solicitudes a la siguiente URL:

https://www.pousadinhas.com.br/oauth2/token?idioma=es

Las credenciales de la aplicación deben ser informados de estas solicitudes a través de URL de autenticación básica, oa través de las variables POST client_id y client_secret .

Los tipos de subvención ( grant_type ) Apoyado por el mecanismo de autenticación OAuth 2.0 implementado son: client_credentials , password y refresh_token . Por favor, consulte las instrucciones OAuth 2.0 para los parámetros adicionales para cada tipo de subvención.

En caso de éxito el mecanismo de autenticación devuelve el código 200 y el resultado en formato JSON, que contiene el token de acceso ( access_token ), Su validez ( expires_in ) El alcance de acceso ( scope ) Y, opcionalmente, una sustitución de tokens ( refresh_token ).

En caso de error el mecanismo de autenticación devuelve el código 400 y el resultado en formato JSON, que contiene el código OAuth 2.0 error ( error ) Y una descripción de error más detallado en Inglés ( error_description ).

Conseguir un token de acceso

Para obtener un token de acceso se requiere presentar una solicitud POST a la URL de autenticación utilizando los tipos de subvención client_credentials o password .

Por tipo de subvención client_credentials Usted puede obtener un token para acceder a la plataforma de datos públicos.

Por tipo de subvención password Usted puede obtener un token para acceder a los datos públicos y la plataforma de datos de usuario cuyo acceso credenciales fueron proporcionados en la solicitud.

En la concesión de password Además de la señal de acceso, también se devuelve una renovación de contadores ( refresh_token ) Para ser almacenados por la aplicación y se utiliza para obtener un nuevo token de acceso para que el token de acceso en uso expire.

Cuando la solicitud se hace la solicitud en nombre de un usuario autenticado, debe utilizar el token de acceso obtenida mediante la concesión password . Esto debe ser observado incluso cuando los datos de acceso se pueden obtener también a través de una muestra obtenida a través del tipo de subvención client_credentials .

En ningún caso, la aplicación debe almacenar las credenciales de acceso proporcionadas por persistentemente usuario. La aplicación debe asegurarse de que las credenciales suministradas por el usuario se descartan inmediatamente después de la autenticación y no están incluidos por error en los registros o en virtud de archivos de depuración.

El tipo de subvención password sólo se libera al cliente de la plataforma de aplicaciones socio dado el alto nivel de confianza requerido por los usuarios a proporcionar sus credenciales de acceso.

Renovación de un token de acceso

Para un token nuevo acceso, que sustituirá a un token expirado, usted debe presentar una petición POST a la URL de autenticación utilizando el tipo de subvención refresh_token .

Para obtener una nueva señal de acceso, la renovación viejo símbolo será derogada y debe ser sustituido por nuevo token actualización emitida.

Antes de cualquier acceso El Pousadinhas API , La aplicación cliente debe comprobar primero la validez del token de acceso, renovación si es necesario. El uso de un token expirado genera un error en la llamada a la API (código 401), que también debe ser tratado, mediante la obtención de un nuevo token y el reintento posterior.

6. Estructura API

Acceso El Pousadinhas API se calcula utilizando la siguiente URL base:

https://www.pousadinhas.com.br/api/v2/?idioma=es

La estructura de las direcciones URL de acceso API de la base de URL, sigue un patrón que se divide en 4 grados:

  • /collection - El acceso a la colección de objetos;
  • /collection/{id} - El acceso a un objeto de colección por identificador;
  • /collection/{id}/property - El acceso a una propiedad de un objeto de la colección por el identificador y el nombre de la propiedad;
  • /collection/name - Acceso a una operación relacionada con uno o más objetos de la colección;

La El Pousadinhas API sigue los principios REST y patrones de acceso de protocolo HTTP. La accesibilidad se organiza de la siguiente manera:

  • Peticiones GET para leer los objetos;
  • Peticiones PUT para escribir objetos;
  • Peticiones POST para crear objetos;
  • BORRAR solicitudes de eliminación de objetos;

Ver la lista completa de los Recursos API .

7. Formato de datos

La El Pousadinhas API trabajar con formato JSON y JSONP opcionalmente para peticiones GET tipo (devuelto cuando se hace uso del parámetro callback ).

Todas las solicitudes de devolución, además de código HTTP apropiado, un objeto JSON con campos sequintes:

  • meta - Contiene el código de retorno HTTP ( code ) Y, en caso de error, la descripción del error en Inglés ( error_detail ) Y mensajes de error en el idioma establecido en la solicitud ( error_messages ) Que indica el campo que está asociado con el error;
  • data - Contiene los datos solicitados;
  • caching - Contiene el objeto clave de identificación ( hashkey ) Y el tiempo de caducidad de datos ( expires_in ) Se utiliza para optimizar el tráfico entre la aplicación cliente y el El Pousadinhas API en el GET y PUT tipo solicitudes;

POST y PUT solicitudes, que deberán presentar el contenido de la solicitud en formato JSON en el cuerpo de la solicitud e informará al encabezado "Content-Type" y "application / json".

8. Datos Caching

La El Pousadinhas API implementa un mecanismo de caché sencillo inspirado en el mecanismo de caché nativo del protocolo HTTP.

En las peticiones GET y PUT, para informar al parámetro hashkey (O de cabecera If-None-Match ) El servicio comparará con la tecla resultado control y devolverlo solamente cuando no coincide; el consiguiente ahorro de la información de tráfico a la aplicación cliente.

Estas solicitudes el servicio devuelve el campo caching que contiene la clave de objeto hash para ser devuelto ( hashkey ) Y los datos de tiempo de caducidad ( expires_in ). En caso de que la solicitud ha sido hecha con el encabezado If-None-Matchesta información se devuelve a través del encabezado Etag y la directiva max-age del encabezado Cache-Control, respectivamente.

Cuando hay correspondencia entre la tecla de almohadilla e informó a la clave hash devuelto, el servicio devuelve el código 304 y omite el campo data .

La aplicación cliente no debe presentar una segunda petición GET, a la misma API URL, con exactamente los mismos parámetros cuando los datos no se cumplan de acuerdo con el campo expires_in .

9. Paginación

Los datos de localización a través de la API deben realizarse utilizando los parámetros de URL offset y limit . Parámetro offset establece el punto de página inicial. Parámetro limit ajusta el tamaño de la página. Para ir a la página siguiente de resultados, envíe la misma solicitud de aplicación pero aumentando el valor del campo offset el valor del campo limit .

Para traer todos los datos utilizan el tamaño de página*Señalando que debe evitarse para los datos de tamaño arbitrario.

10. Ordenación

Los resultados de las solicitudes de la API se pueden pedir mediante el parámetro de URL sortby . Este parámetro define qué campos se deben utilizar con el fin, según el orden en que se especifican. El uso del sufijo "-" hace que la especie que ocurre en un orden decreciente.

Por ejemplo, sortby=price-,name ordenará una colección de datos de entrada para el precio, mayor a menor, y si dos objetos tienen el mismo precio, el nombre del objeto.

11. Filtro Campos

A través del parámetro fields puede definir los campos a ser devueltos por la API.

Es posible definir no sólo los campos para filtrar el objeto devuelto sino también los objetos referenciados por este último con la profundidad arbitraria. También puede establecer el número de objetos a devolver las colecciones que conforman el objeto. Campo id de los objetos siempre se devuelve y no necesita ser especificada.

Por ejemplo, fields=name,place{name,photos(10)},photos(10){id} harán los campos id , name , place.id y place.name , Y el campo 10 id fotos del destino y posada.

Para llevar a todos los objetos en un uso de la colección * , Tomando nota de que esto se debe evitar a las colecciones de tamaño arbitrario.

12. Ejecución de la simulación

A través de El Pousadinhas API Puede simular la ejecución (marcha en seco) de la POST / PUT sin modificar realmente las peticiones de datos, pero es posible detectar errores de validación. Para esto simplemente especifica la variable de URL dryrun=1 en la solicitud.

13. Parámetros estándar

La El Pousadinhas API apoya algunos parámetros patrón de URL (variables GET) que se aplican simétricamente a los diversos servicios de la API.

  • access_token - Esta variable debe contener el token de acceso válido obtenido a través del mecanismo de autenticación OAuth 2.0 ;
  • callback - Esta variable especifica el nombre de la función que se utilizará en la declaración en formato JSONP se limita a obtener el tipo de peticiones;
  • hashkey - Esta variable contiene la clave hash esperado a los datos, si el valor coincide con el valor a devolver, los datos no se envía de vuelta al cliente;
  • fields - Esta variable describe la estructura de datos para ser devuelto, indicando jerárquicamente los campos a ser devueltos;
  • dryrun - Esta variable establece que el método POST / PUT sólo debe simular la solicitud sin cambiar realmente los datos; útil para la prueba y también la validación de datos antes de su presentación;
  • sortby - Esta variable especifica qué campos de la colección que deberían utilizarse para ordenar el resultado;
  • offset - Esta variable especifica el punto de partida de paginación;
  • limit - Esta variable especifica el tamaño de la página;

14. Limitación de las solicitudes de velocidad

Para evitar abusos, El Pousadinhas API mantiene un registro de acceso a la API que se debe hacer dentro de la pre-establecido de cuotas de la aplicación cliente.

La cuota varía según el tipo de solicitud y token de acceso, que puede variar también por el servicio API. OBTENER tipo solicitudes tiene una dimensión superior que solicita el tipo de POST / PUT / BORRAR. Acceso a través del token obtenido mediante la concesión client_credentials entrar en la aplicación de la cuota, siendo compartida por todas las instancias. Tiene acceso a través del token obtenido mediante la concesión password entrar en la cuota del usuario, siendo compartida por otras aplicaciones cliente que utilizan la misma.

El tamaño de la cuota y el número de solicitudes restantes se presentan en el retorno de cada petición API a través de las cabeceras X-RateLimit-Limit y X-RateLimit-Remaining Respectivamente.

Para superar la cuota, la API devolverá al código de aplicación de cliente 429 y, en la cabecera Retry-After El número de segundos que la aplicación espera antes de enviar un nuevo intento.

La aplicación cliente debe mostrar al usuario un temporizador cuando se está esperando debido a la explosión de la cuota, lo que permite la cancelación de la operación. También se recomienda que la aplicación cliente sugiere que el usuario inicie sesión para remediar la restricción temporal de cuota, si no encuentra autenticado.

Los límites a la aplicación de solicitudes de velocidad pueden ser revisados ​​caso por solicitud a nuestro equipo.

15. Ubicación

La ubicación, en cuanto a idioma, divisa y zona horaria, las llamadas deEl Pousadinhas APIdebe realizarse a través de los siguientes parámetros de URL (GET variables):

  • language-Esta variable indica el idioma que se utilizará en los mensajes devueltos por la API;
  • currency-Esta variable indica la moneda que se utilizará en el precio devuelto por la API;
  • timezone-Esta variable indica la zona horaria que se utilizarán en las codificaciones de fecha/hora devueltas por la API;

ElEl Pousadinhas APIsiempre devuelve los datos según estos parámetros, independientemente de la configuración de la cuenta de usuario asociada con el token de acceso usado en la solicitud.

16. Códigos de retorno

A continuación se muestra una lista de los códigos de retorno para el éxito o el error devuelto por la API y de las situaciones en que se encuentran:

  • 200 - El éxito en la implementación de la operación;
  • 201 - El éxito en la creación de un nuevo objeto;
  • 304 - El éxito en la implementación de la operación, pero el hash objeto informado clave coincidió y los datos fueron omitidos;
  • 400 - No es seguro el acceso HTTP; Parámetros obligatorios o variables no declaradas; Parámetros o variables adicionales no reconocidos; Parámetros o variables no válidos; No existe el objeto o no válido JSON; Actualización de campo que permite sólo lectura; De recorrido de prueba no se admite;
  • 401 - La falta de señal de acceso; Acceso no válido simbólico, caducado o revocado; Acceso denegado la solicitud;
  • 403 - Permisos insuficientes para hacer la solicitud;
  • 404 - Recursos (colección, objeto, etc.) allí;
  • 405 - Tipo de solicitudes no se admite;
  • 409 - Error al crear / actualizar / eliminación de un objeto;
  • 429 - Superado el acceso de las cuotas;

17. Acceso a la consola

Para familiarizarse con el El Pousadinhas API , Visita Consola API impulsado por Apigee.

Las Pruebas de Medio Ambiente POUSADINHAS.COM.BR entorno ficticio es totalmente autónomo e idéntico en funcionalidad para el entorno de producción. A través de ella, usted puede probar todas las funcionalidades de nuestra plataforma de una forma totalmente aislada de la realidad y sin afectar a su funcionamiento.

Si usted está interesado en acceder a nuestro entorno de prueba, por favor envíe un correo electrónico a recursos@pousadinhas.com.br identificación y descripción de las razones de su solicitud.