Hasta {MAX_KEYS} datos. Las claves se pasan a minúsculas y admiten letras,
números, guiones y guiones bajos.
setSigning(e.target.checked)} />
{signing &&
Usá solamente un secreto descartable recién generado. Acá se usa
dentro de tu navegador y no se envía a ningún lado, pero deja de estar confinado
a tu servidor. Cuando termines, regeneralo desde{' '}
Agenda → Configuración → Calendario embebido y guardá el nuevo
únicamente en tu backend.
setSecret(e.target.value)} placeholder="pegá tu secreto de firma" aria-label="Secreto de firma" />
Texto que se firma
{canonical || 'todavía no hay datos para firmar'}
Las claves van ordenadas alfabéticamente y cada clave y valor usa
percent-encoding RFC 3986. Es el mismo texto que tiene que armar tu servidor.
{sig &&
sig = {sig}
}
}
Enlace resultante
{url || 'escribí el uuid de tu agenda para generar el enlace'}
;
};
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_` | 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
1. Conservá solamente `prefill_*`, `metadata_*` y `exp`.
2. Convertí cada valor a string. Omití valores nulos.
3. Ordená los pares por nombre de clave ascendente.
4. 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.
5. Uní los pares como `clave=valor` con `&`.
No incluyas `embed` ni `sig`.
```text theme={null}
exp=1753900000
metadata_internal_id=ORD-1234
prefill_email=juan@acme.com
prefill_name=Juan Pérez
```
La cadena canónica es:
```text theme={null}
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:
```text theme={null}
407a8a40d71bdf1d690b65219033cfa29a7869c40318244bdcf1fff8e1c2f4ba
```
## Generar una URL en Node.js
```js theme={null}
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
```python theme={null}
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:
1. El conjunto exacto de parámetros firmados.
2. El orden alfabético de las claves.
3. El percent-encoding RFC 3986 de claves y valores.
4. El timestamp `exp` en segundos.
5. El secreto vigente de esa agenda.
Si regenerás el secreto, todas las URLs firmadas con el anterior dejan de funcionar.