Crear una clave API

Una API es una puerta en la parte trasera de su cuenta. Donde usted hace clic en su panel de gestión, otro programa puede pasar por esa puerta y recuperar directamente sus datos: sus productos, sus precios, sus plazas libres, sus ventas.

Resulta útil cuando quiere, por ejemplo:

• mostrar en su propia web qué visitas guiadas tienen aún plazas esta semana;
• que su contable descargue automáticamente sus cifras de facturación;
• conectar su lista de socios con otro programa.

Quien construya esa integración —su desarrollador web, su programa de contabilidad, un amigo que sabe programar— necesita dos cosas de usted: la dirección y una clave. Encontrará ambas en una sola pantalla.

Conviene saberlo: la API forma parte de un plan superior. En un plan más pequeño Acceso API no aparece en su menú; si aun así llega a la pantalla, verá una explicación y un botón Ir a la suscripción, no claves.

Dónde ir

En el menú de la izquierda, abra Ajustes → Acceso API. Solo el rol Propietario ve esta pantalla.

Arriba hay dos pestañas: Claves y Webhooks. Este artículo trata de la primera; los webhooks se explican en Configurar webhooks.

En la pestaña Claves verá tres bloques:

1. La conexión — la dirección y la descripción técnica. Estos son los dos datos que entrega a quien construye la integración.
2. Nueva clave — aquí crea una.
3. Claves — lo que ya existe y cuándo se usó por última vez.

Crear una clave

Paso 1. Póngale un nombre. No su propio nombre, sino el de lo que hay al otro lado: «nuestra web», «contabilidad», «boletín». Ese nombre es solo para usted. Aparecerá en la lista, junto a «último uso». Dentro de un año seguirá sabiendo qué clave corresponde a qué —y cuál puede revocar sin problema.

Paso 2. Marque lo que puede hacer la clave. Bajo ¿Qué puede hacer esta clave? están los permisos, o scopes en jerga. Lectura ya viene marcado:

Permiso	Lo que puede hacer el programa
Lectura	Consultar su catálogo, precios, plazas libres, descuentos, tarjetas regalo y abonos anuales — y también sus pedidos, entradas, escaneos y compradores, con su nombre y su dirección de correo.
Escritura	Crear pedidos, cobrarlos, cancelarlos y reembolsarlos, solicitar una factura, anular y reenviar entradas, registrar accesos, y emitir, canjear o renovar tarjetas regalo y abonos anuales.
Webhooks	Hacer que enviemos un aviso a una dirección suya en cuanto ocurra algo.
Pagado externamente	Marcar un pedido como pagado sin proveedor de pagos (transferencia, efectivo). Solo funciona junto con Escritura.

Marque solo lo que realmente haga falta. Una web que únicamente debe mostrar qué plazas quedan libres se conforma con Lectura. Si esa clave recibe además Escritura, un fallo en esa web puede crear o reembolsar pedidos que usted no quiere.

Sea especialmente prudente con Pagado externamente: quien lo tiene puede emitir entradas sin que entre dinero. Délo solo a una caja o a una contabilidad que usted gestione.

Debe marcar al menos un permiso. Una clave sin permisos no podría hacer nada, y ese es el tipo de fallo más difícil de localizar —por eso la pantalla la rechaza.

Paso 3 (opcional). Ponga una fecha de caducidad. Si deja vacío el campo Caduca el (opcional), la clave sigue funcionando hasta que usted la revoque. Si indica una fecha, todavía funciona ese día y después se detiene sola. La fecha debe estar en el futuro. Práctico cuando deja que alguien mire de forma temporal: después no tendrá que acordarse.

Paso 4 (opcional). Clave de prueba. Marque Clave de prueba (sandbox) para quien todavía está construyendo. Una clave así lee los mismos datos que una normal. Si además tiene Escritura, solo crea pedidos de prueba: nunca pasan por su proveedor de pagos, no cuentan en su facturación y se eliminan automáticamente al cabo de 24 horas. Así una errata no puede provocar un pago ni un reembolso reales. Una clave de prueba no puede configurar webhooks.

Atención: hasta que se elimina, un pedido de prueba sí retiene una plaza real, y el correo de confirmación se envía de verdad. Haga las pruebas con un producto o una franja horaria creados para ello.

Reconocerá una clave de prueba por el principio: empieza por pv_test_ en lugar de pv_live_.

Paso 5. Haga clic en «Crear clave».

La clave solo se ve una vez

Justo después de crearla, la clave aparece en un recuadro. Es la única vez que la verá.

Cópiela ahora y entréguela de inmediato. Si actualiza la página, habrá desaparecido.

No es una molestia sino una protección. No guardamos su clave: solo conservamos una especie de huella que nos permite reconocerla, pero no releerla. Si alguien llegara algún día a nuestra base de datos, aun así no tendría acceso a sus datos. La contrapartida es que nosotros tampoco podemos volver a mostrársela.

¿La ha perdido? No pasa nada: cree una nueva y revoque la antigua.

Trate una clave como una llave

Quien tenga la clave puede hacer lo que esté marcado en ella —sin contraseña y sin abrir su cuenta. Por tanto:

• no la envíe por un chat de grupo corriente donde quedará a la vista;
• no la ponga en el código visible de su web;
• dé a cada integración su propia clave. Así podrá revocar una sin romper las demás, y en la lista verá cuál sigue en uso.

Revocar una clave

En la lista, haga clic en Revocar junto a la clave y confirme.

A partir de ese momento deja de funcionar. La fila permanece en la lista con la marca «Revocada»: así siempre podrá consultar después qué integración existía y cuándo.

Revoque una clave cuando:

• deje de usar la herramienta que la utilizaba;
• la haya perdido o ande suelta por ahí;
• se marche alguien que la tenía.

La creación y la revocación de una clave también quedan en el registro de actividad de quien lo hizo (Ajustes → Empleados, esa persona, pestaña Actividad), con el momento. La clave en sí nunca aparece ahí.

¿Cuándo se usó por última vez?

Debajo de cada clave se indica cuándo se recuperó algo con ella por última vez. Si lleva meses diciendo «aún no utilizada», probablemente ya no haya nada conectado. Revóquela sin miedo: una puerta que nadie usa no tiene por qué quedarse abierta.

Qué entrega a quien construye la integración

Tres cosas:

1. la dirección de la API del bloque La conexión;
2. la descripción técnica (el enlace que termina en openapi.json) —un desarrollador ve de inmediato todo lo que es posible;
3. la clave en sí y los permisos que ha marcado.

No necesita nada más.

¿Y después?

Ya tiene la dirección y la clave. Lo que viene después es trabajo de quien construye la integración — y a esa persona le reenvía el portal para desarrolladores. Allí está la referencia completa, con ejemplos de código en cuatro lenguajes y un archivo que se importa directamente en Postman o Insomnia.

• ¿Qué es una API, y la necesito? — si primero quiere saber de qué va todo esto.
• Webhooks — avisar a su web de que se ha vendido algo, sin que tenga que seguir preguntándolo.
• Configurar webhooks — la pestaña Webhooks de esta misma pantalla, paso a paso.