Ajustes

API y Webhooks

Qué son la API y los webhooks de Salonnare, y paso a paso cómo crear una clave API y configurar un webhook.

6 min de lectura6 apartadosTambién en 8 idiomas más
En Ajustes (13 artículos)
En esta página

Con la API y los webhooks conectas tu salón con otro software, como tu programa de contabilidad, tu propia web o un panel hecho a medida. No necesitas ser desarrollador para entender lo que hacen; esta página lo explica y muestra cómo crear una clave y un webhook.

Aún no disponible

Esta función todavía aparece como Próximamente en la app: aún no puedes crear claves API ni webhooks. Si abres Ajustes > Avanzado > API y Webhooks, solo ves un aviso de que la función está en camino. Esta página describe cómo funciona en cuanto la función se active para tu salón.

¿Qué es una API?

Una API es un acuerdo que permite que dos programas se comuniquen. Donde tú abres una lista de citas en la app, otro programa puede obtener esos mismos datos mediante la API, de forma automática y sin intervención. Por ejemplo: tu programa de contabilidad recoge tus citas cada noche, o tu web muestra tus servicios y precios directamente desde Salonnare.

El acceso se hace con una clave API: un código secreto que demuestra que una petición viene de tu salón. Trata esa clave como una contraseña.

Crear una clave API

Solo un administrador puede crear y eliminar claves.

  1. Paso 1: Abre API y Webhooks y haz clic en Nueva clave

    Ve a Ajustes > Avanzado > API y Webhooks. En la pestaña Claves API (1), haz clic en Nueva clave (2).

    La pestaña Claves API con el botón Nueva clave resaltado (Ampliar imagen)
  2. Paso 2: Ponle un nombre a la clave y elige qué puede leer

    Escribe un Nombre reconocible, por ejemplo el nombre de la integración (1). En ¿Qué puede leer esta clave? marca solo los datos que necesita la integración (2): Citas, Clientes, Tratamientos o Empleados. Si la clave debe dejar de funcionar después de un día concreto, elige una fecha en Caduca. Haz clic en Crear (3).

    Una clave API solo puede obtener datos, nunca cambiar nada. Los Clientes son datos personales: actívalo solo si tu socio de integración los necesita de verdad. Una web que muestra tus tratamientos y precios tiene suficiente con Tratamientos y Empleados.

    La ventana Nueva clave API con el nombre, los permisos de lectura y el botón Crear resaltados (Ampliar imagen)
  3. Paso 3: Copia la clave

    La clave completa (1) solo se muestra una vez. Haz clic en el botón de copiar (2) y pasa la clave a tu socio de integración, o guárdala en un gestor de contraseñas. Después cierra la ventana.

    La ventana Clave API creada con la clave y el botón de copiar resaltados (Ampliar imagen)
  4. Paso 4: Tu clave en la lista

    En la lista ves el nombre, el principio de la clave, qué puede leer, cuándo se usó por última vez y cuándo caduca (1). Con Renovar (2) obtienes una clave nueva con el mismo nombre y los mismos permisos; eliges cuánto tiempo sigue funcionando la antigua (deja de funcionar ya, 24 horas o 7 días), para que tu socio de integración tenga tiempo de cambiar. Con Revocar (3) una clave deja de funcionar al momento.

    La lista de claves API con la nueva clave y los botones Renovar y Revocar resaltados (Ampliar imagen)

¿Qué es un webhook?

Un webhook es lo contrario de la API. En lugar de que un programa pregunte continuamente si hay novedades, Salonnare envía él mismo un mensaje a una dirección (URL) en cuanto ocurre algo. Salonnare puede enviar estos siete eventos:

  • booking.created: se añade una cita nueva: en la app, a través de tu página de reservas online o el widget, a través de Google Reserve, o en cuanto se confirma una solicitud de reserva (también cada cita que crea una serie periódica)
  • booking.updated: un empleado modifica una cita en la app (también un cambio de estado a completada o no presentado)
  • booking.cancelled: un empleado cancela una cita en la app
  • payment.received: un empleado cobra en la caja
  • client.created: un empleado crea un cliente en la app
  • client.updated: un empleado modifica los datos de un cliente en la app
  • client.deleted: un empleado elimina un cliente en la app. La notificación solo contiene el número de cliente; después, Salonnare conserva las notificaciones anteriores sobre ese cliente sin nombre ni datos de contacto
Solo lo que ocurre en la app

Cada evento procede de una acción de un empleado en la app. Una reserva en línea mediante tu página de reservas o Google, un cliente que cancela por su cuenta, una lista de espera convertida, una serie recurrente, un bono y un cliente que se da de alta por su cuenta en la página de reservas no envían ningún aviso. Tu socio de integración los recupera consultando periódicamente la lista de citas.

Configurar un webhook

  1. Paso 1: Abre la pestaña Webhooks

    Ve a Ajustes > Avanzado > API y Webhooks y haz clic en la pestaña Webhooks.

    API y Webhooks con la pestaña Webhooks resaltada (Ampliar imagen)
  2. Paso 2: Haz clic en Nuevo webhook

    Haz clic en Nuevo webhook.

    La pestaña Webhooks con el botón Nuevo webhook resaltado (Ampliar imagen)
  3. Paso 3: Escribe la dirección y elige los eventos

    En URL, escribe la dirección que te ha dado tu socio de integración; empieza por https:// (1). Marca los eventos a los que debe reaccionar la integración (2 y 3). Activo está activado de forma predeterminada. Haz clic en Guardar (4).

    La ventana Nuevo webhook con la URL, dos eventos marcados y el botón Guardar resaltados (Ampliar imagen)
  4. Paso 4: Copia el secreto

    Salonnare firma cada mensaje con un secreto, para que el destinatario pueda comprobar que viene realmente de tu salón. El secreto (1) solo se muestra una vez: cópialo (2) y pásalo a tu socio de integración.

    La ventana Secreto del webhook con el secreto y el botón de copiar resaltados (Ampliar imagen)
  5. Paso 5: Probar y consultar los avisos

    El webhook aparece ahora en la lista (1). Con Probar (3), Salonnare envía al momento un mensaje de prueba y ves si llegó. En Avisos (4) ves cada aviso con su estado (entregado, se volverá a intentar o fallido) y sus intentos; allí puedes reenviar un aviso fallido con Reenviar. Si has perdido el secreto, haz clic en Nuevo secreto (2); el antiguo deja de funcionar, así que también hay que actualizar el lado receptor.

    El webhook en la lista con los botones Nuevo secreto, Probar y Avisos resaltados (Ampliar imagen)

¿Y si...

... la prueba no llega? Salonnare indica entonces que la dirección no respondió o qué código de error devolvió el destinatario. Revisa la dirección y pregunta a tu socio de integración por qué su lado rechaza el mensaje.

... un aviso no llega alguna vez? Salonnare lo vuelve a intentar: después de aproximadamente 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas y 24 horas. Cada intento lleva el mismo número de aviso, para que el receptor reconozca un aviso que llega dos veces. Si ningún intento funciona y en ese tiempo tampoco llegó nada más, Salonnare desactiva el webhook y te avisa con una notificación. Lo vuelves a activar editándolo y activando Activo. Los avisos fallidos los reenvías en Avisos con Reenviar.

... se rechaza la dirección? Un webhook debe apuntar a una dirección pública. Salonnare rechaza direcciones de una red interna o privada, localhost y direcciones que no empiezan por https://, con un mensaje que indica el problema.

... sospechas que una clave se ha filtrado? Elimínala de inmediato con la papelera y crea una nueva.

Trabajar de forma segura

  • No compartas nunca públicamente las claves API ni los secretos de webhook (tampoco en un correo normal, una captura de pantalla ni en código en línea).
  • Da a una integración solo los permisos que necesita.
  • Elimina las claves y los webhooks que ya no uses.

¿Eres desarrollador y buscas los detalles técnicos (autenticación, endpoints, campos, firmas)? Consulta la API Reference. Esa página está en inglés, porque está escrita para desarrolladores.

¿Te ha sido útil?

Tu respuesta nos ayuda a mejorar las guías.

¿Sigues sin solución?

Soporte: lun-vie respuesta en 24 a 48 horas (Pro: en 24 horas) · fines de semana y festivos: en 24 horas si es urgente, si no, el siguiente día laborable

Contáctanos