Implementar el embed firmado

El embed firmado permite precargar datos del cliente y adjuntar metadata sin confiar en parámetros modificables por el navegador.

Obtener la configuración

El owner debe abrir Agenda → Configuración → Calendario embebido. Desde ahí copia el código, revela el secreto y, después de validar la integración, activa Exigir firma.

El secreto de producción solo puede vivir en tu backend o secret manager. No lo incluyas en JavaScript del navegador, HTML, aplicaciones móviles ni repositorios.

Parámetros aceptados

Parámetro	Uso
`embed=1`	Activa la vista embebida; no se firma
`prefill_name`	Precarga el nombre
`prefill_email`	Precarga el email
`prefill_phone`	Precarga el teléfono
`metadata_<clave>`	Guarda un dato externo en la reserva
`exp`	Timestamp Unix de vencimiento opcional
`sig`	HMAC-SHA256 en hexadecimal minúscula

Las claves de metadata se normalizan a minúsculas, admiten a-z, 0-9, _ y -, y se recortan a 40 caracteres. Se guardan hasta 20 claves, con valores de hasta 500 caracteres y un máximo total serializado de 4 KB. Los valores que no cumplen se descartan. Los datos prefill_* solo se fuerzan en el backend cuando la firma es válida. Sin firma pueden verse bloqueados en la interfaz, pero el visitante puede alterar la URL antes de abrirla y el backend no los considera datos confiables.

Construir la cadena canónica

Conservá solamente prefill_*, metadata_* y exp.
Convertí cada valor a string. Omití valores nulos.
Ordená los pares por nombre de clave ascendente.
Aplicá percent-encoding RFC 3986 a cada clave y valor por separado: solo A-Z a-z 0-9 - . _ ~ quedan sin escapar y el hexadecimal va en mayúscula.
Uní los pares como clave=valor con &.

No incluyas embed ni sig.

exp=1753900000
metadata_internal_id=ORD-1234
[email protected]
prefill_name=Juan Pérez

La cadena canónica es:

exp=1753900000&metadata_internal_id=ORD-1234&prefill_email=juan%40acme.com&prefill_name=Juan%20P%C3%A9rez

Calculá HMAC-SHA256(secreto, cadena_canónica) y agregá el digest hexadecimal como sig. Con el secreto mi-secreto, la firma del ejemplo es:

407a8a40d71bdf1d690b65219033cfa29a7869c40318244bdcf1fff8e1c2f4ba

Generar una URL en Node.js

const crypto = require('crypto');

const rfc3986 = (value) =>
  encodeURIComponent(value).replace(
    /[!'()*]/g,
    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
  );

const buildSignedEmbedUrl = (agendaUuid, secret, input) => {
  const params = Object.fromEntries(
    Object.entries(input)
      .filter(([key, value]) =>
        value !== null &&
        value !== undefined &&
        (key === 'exp' || key.startsWith('prefill_') || key.startsWith('metadata_')))
      .map(([key, value]) => [key, String(value)]),
  );

  const canonical = Object.keys(params)
    .sort()
    .map((key) => `${rfc3986(key)}=${rfc3986(params[key])}`)
    .join('&');
  const sig = crypto.createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');
  const query = new URLSearchParams({ embed: '1', ...params, sig });

  return `https://turnito.app/c/${encodeURIComponent(agendaUuid)}?${query}`;
};

Generar una URL en Python

import hashlib
import hmac
from urllib.parse import quote, urlencode


def build_signed_embed_url(agenda_uuid: str, secret: str, input_params: dict) -> str:
    params = {
        key: str(value)
        for key, value in input_params.items()
        if value is not None
        and (
            key == "exp"
            or key.startswith("prefill_")
            or key.startswith("metadata_")
        )
    }
    canonical = "&".join(
        f"{quote(key, safe='')}={quote(params[key], safe='')}"
        for key in sorted(params)
    )
    sig = hmac.new(
        secret.encode("utf-8"),
        canonical.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    query = urlencode({"embed": "1", **params, "sig": sig})
    return f"https://turnito.app/c/{agenda_uuid}?{query}"

Definir vencimiento

Mandá exp como timestamp Unix en segundos y firmalo junto con los demás parámetros. Si está vencido o no es un entero válido, Turnito rechaza la reserva. Usá ventanas cortas, de minutos u horas.

Interpretar la validación

Firma válida: Turnito fuerza los datos precargados y guarda la metadata normalizada.
Firma inválida o vencida: la reserva se rechaza.
Firma ausente con Exigir firma activo: la reserva se rechaza cuando la URL incluye parámetros firmables.
Embed sin prefill_*, metadata_* ni exp: no exige firma y funciona como un calendario común.

Probar la URL

Este probador calcula la firma en tu navegador. Usalo únicamente con un secreto descartable recién generado y antes de publicar la integración. Cuando termines, regenerá el secreto y guardá el nuevo solo en tu backend.

Nunca pegues en el probador un secreto que ya esté en producción.

Diagnosticar una firma inválida

Compará, en este orden:

El conjunto exacto de parámetros firmados.
El orden alfabético de las claves.
El percent-encoding RFC 3986 de claves y valores.
El timestamp exp en segundos.
El secreto vigente de esa agenda.

Si regenerás el secreto, todas las URLs firmadas con el anterior dejan de funcionar.

Primeros pasos

Panel

Agendas

Reservas

Clientes

Presencia pública

Integraciones

Cobros

Notificaciones

Cuenta y soporte

API

Obtener la configuración

Parámetros aceptados

Construir la cadena canónica

Generar una URL en Node.js

Generar una URL en Python

Definir vencimiento

Interpretar la validación

Probar la URL

Diagnosticar una firma inválida

​Obtener la configuración

​Parámetros aceptados

​Construir la cadena canónica

​Generar una URL en Node.js

​Generar una URL en Python

​Definir vencimiento

​Interpretar la validación

​Probar la URL

​Diagnosticar una firma inválida

Obtener la configuración

Parámetros aceptados

Construir la cadena canónica

Generar una URL en Node.js

Generar una URL en Python

Definir vencimiento

Interpretar la validación

Probar la URL

Diagnosticar una firma inválida