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.
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.
-
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).
(Ampliar imagen) -
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.
(Ampliar imagen) -
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.
(Ampliar imagen) -
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.
(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 apppayment.received: un empleado cobra en la cajaclient.created: un empleado crea un cliente en la appclient.updated: un empleado modifica los datos de un cliente en la appclient.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
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
-
Paso 1: Abre la pestaña Webhooks
Ve a Ajustes > Avanzado > API y Webhooks y haz clic en la pestaña Webhooks.
(Ampliar imagen) -
Paso 2: Haz clic en Nuevo webhook
Haz clic en Nuevo webhook.
(Ampliar imagen) -
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).
(Ampliar imagen) -
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.
(Ampliar imagen) -
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.
(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.