Autenticación

Cada pedido lleva la clave en la cabecera Authorization. Nunca la pongas en la URL: quedaría en historiales y registros.

GET /api/v1/catalogo HTTP/1.1
Host: turnovapp.com
Authorization: Bearer tnv_pk_TU_CLAVE_PUBLICA

Clave pública (navegador)

• Va a la vista de cualquiera en el JavaScript de tu sitio: por eso solo da acceso a lo que tu página de reservas ya muestra, y a crear reservas.
• Funciona solo desde los orígenes permitidos de la clave. El servidor compara la cabecera Origin antes de ejecutar nada: un pedido desde otro origen, o sin Origin, responde 403 ORIGEN_NO_PERMITIDO.
• Los orígenes se cargan como https://dominio (sin camino). Se acepta http:// solo para localhost y 127.0.0.1.
• No puede leer reservas ya hechas: eso trae datos de la clienta.

CORS

El navegador manda primero un preflight OPTIONS sin la clave. Turnova responde 204 con Access-Control-Allow-Origin igual a tu origen exacto (nunca *) si ese origen está cargado en alguna clave pública activa, y 403 sin cabeceras CORS si no. Las cabeceras permitidas son Authorization, Content-Type e Idempotency-Key; se expone Retry-After. No se usan cookies.

Clave secreta (servidor)

• Guardala en una variable de entorno de tu servidor y no la mandes nunca al navegador.
• Si un pedido con clave secreta trae cabecera Origin (es decir, sale de un navegador), responde 403 CLAVE_SECRETA_EN_NAVEGADOR.
• Es la única que puede tener el permiso reservas:leer.

// Node 18+ (Next.js route handler, Express, etc.)
const res = await fetch("https://turnovapp.com/api/v1/reservas/" + compraId, {
  headers: { Authorization: `Bearer ${process.env.TURNOVA_CLAVE_SECRETA}` },
});

Plan del negocio

La API funciona mientras el negocio tenga el plan Enterprise. Si cambia a otro plan, las claves no se borran, pero todo pedido responde 403 PLAN_SIN_API con upgrade_url hasta que vuelva a Enterprise.

Errores de acceso