A veces alguien quiere conectar algo con Stippa. Quien te hace la web y quiere rehacer el formulario de reserva con tu propia imagen, un gestor con un script que saca los ingresos, o un servicio como Zapier que manda un mensaje en cuanto entra una cita. Esa persona te pide entonces una clave de API.
Esta página es para ti, no para esa persona. No hace falta que sepas cómo funciona por dentro para tomar la decisión correcta. Lo que necesita el desarrollador está en la documentación para desarrolladores, que está en inglés.
¿Qué es una clave de API?
Un texto largo y secreto que empieza por stp_live_. Quien la tenga puede hacer en nombre de tu
negocio exactamente aquello que hayas marcado al crearla, y nada más.
Tres cosas importan más que la técnica:
- Una clave pertenece a tu negocio. Nunca puede llegar a los datos de otro negocio, ni siquiera por error.
- Una clave no es un inicio de sesión. No lleva ninguna contraseña y con ella nadie entra en la app. Solo sirve para la integración.
- Una clave es un secreto, como la llave del local. Quien la tenga puede usarla. Por eso existe el resto de esta página.
¿Cuándo necesito una?
Solo cuando alguien te la pida. Para el uso normal de Stippa nunca hace falta una clave de API: el widget de reservas, el calendario, los correos y el perfil público funcionan todos sin ella.
Casos típicos en los que sí hace falta:
- Quien te hace la web quiere integrar la reserva por completo en tu propio sitio, en lugar de usar el widget estándar.
- Alguien quiere pasar tus citas por su cuenta a una hoja de cálculo o a un programa de contabilidad.
- Quieres un aviso en Slack, Teams o Zapier en cuanto alguien reserva.
¿Qué plan necesito?
| Lo que quieres | A partir de |
|---|---|
| Leer datos: citas, clientes, servicios, disponibilidad | Groei |
| Dejar crear o modificar datos, y los webhooks | Pro |
Si vuelves a un plan inferior, la clave sigue existiendo. Lo único es que dejan de funcionar los permisos que tu plan ya no da. Si más adelante subes otra vez, la integración vuelve a funcionar al momento, sin que nadie tenga que configurar nada.
Crear una clave
Las claves están en la aplicación Dev, que aparece en el selector de aplicaciones de arriba a la izquierda en cuanto activas el módulo API access.
Activa el módulo
Ve a Administración > Módulos y activa API access. La aplicación Dev aparece después en el selector.
Ve a Dev > Claves
Haz clic en Nueva clave.
Ponle un nombre que sigas entendiendo dentro de un año
Ni «prueba» ni «clave 2», sino «Web de Jansen Webdesign» o «Integración contabilidad». Si algún día tienes que revocar algo, el nombre es lo único por lo que sabrás de quién es cada clave.
Marca solo lo necesario
Hay combinaciones preparadas. Si dudas, elige Solo lectura: esa no puede cambiar nada. Añadir permisos después ya no se puede, pero crear una segunda clave sí, y ese es el orden seguro.
Copia la clave al momento
Ves la clave entera una sola vez, justo después de crearla. Después, Stippa solo guarda una forma cifrada y tampoco nosotros podemos volver a enseñarla. Si la pierdes, la revocas y creas otra.
Pasar una clave con seguridad
Mandarla una vez por correo y olvidarse es la forma en que esto suele salir mal: un buzón se puede buscar durante años, se comparte y se va con la persona a su siguiente trabajo.
- Pásala por un canal que borre, o por el gestor de contraseñas que el desarrollador ya usa.
- No la pongas nunca en un mensaje público, en un ticket ni en un documento compartido.
- Crea una clave propia para cada parte. Dos empresas con la misma clave significa que rompes la integración de las dos si tienes que revocar una.
- Pide una fecha de fin si el encargo es temporal. Puedes hacer que una clave caduque, y así nadie tiene que acordarse después.
Revocar una clave
Ve a Dev > Claves y elige Revocar en la clave que corresponda. Vale al momento: la siguiente petición con esa clave se rechaza. Revocar no se puede deshacer, así que la integración tendrá que recibir después una clave nueva.
Revoca en cualquier caso:
- cuando termine la colaboración con quien hizo la web o con la agencia;
- cuando la clave haya acabado en algún sitio donde no debía;
- cuando ya no sepas para qué sirve una clave. Una clave que nadie sabe ubicar no debería estar activa.
Si dudas de si una clave sigue usándose, mira primero en Dev > Registro. Ahí ves, petición a petición, cuándo entró algo y si salió bien. Una clave que lleva meses sin aparecer ahí la puedes revocar con tranquilidad.
Los webhooks: la dirección contraria
Una clave deja que alguien saque datos de ti. Un webhook hace lo contrario: Stippa manda un mensaje a una dirección web en cuanto pasa algo, por ejemplo cuando se reserva o se cancela una cita. Eso es lo que necesita una integración con Slack o con Zapier. Los webhooks están en la suscripción Pro y se configuran en Dev > Webhooks.
Una dirección de webhook merece el mismo cuidado que una clave. En cada suceso, Stippa manda a esa dirección los datos correspondientes, con los nombres, los correos y los teléfonos de tus clientes. Quien pueda fijar la dirección puede, por tanto, desviar ese flujo a otro sitio. Acepta una dirección solo de alguien en quien confíes, y revisa la lista si ya no sabes quién ha configurado qué.
Si una dirección sigue sin responder, Stippa lo intenta unas cuantas veces más y después desactiva el punto de entrega por su cuenta, para no estar mandando cosas a una dirección muerta para siempre. Lo ves como un aviso encima de la lista, con un botón para volver a activarlo en cuanto el destinatario funcione otra vez.
Preguntas frecuentes
¿Alguien puede entrar en Stippa con mi clave? No. Una clave solo sirve para la integración y no da acceso a la app, ni a tu cuenta, ni a tu suscripción.
¿Puede una clave llegar a los datos de otro negocio? No. La clave decide ella misma de qué negocio se trata; no hay ningún ajuste con el que se pudiera señalar otro.
No veo la aplicación Dev. El módulo API access está desactivado, tu suscripción es Starter, o eres empleado. La aplicación la ven los propietarios y los administradores.
Mi desarrollador pide documentación. Mándale a la documentación para desarrolladores. Está en inglés y tiene todo lo que necesita, con ejemplos incluidos.