Desarrollo

Desarrollo reúne las credenciales y los avisos con los que un sitio habla con la API. Tiene tres pestañas: Claves del navegador, Tokens del servidor y Webhooks.

Claves del navegador

Van en el código de la página, como el ID de Google Analytics. Reportan visitas y, si lo permites, entregan los envíos del formulario. Son públicas por diseño: lo que las protege es el origen.

Pulsa Emitir clave.
Escribe los orígenes autorizados: esquema más dominio, sin ruta, separados por comas. Solo desde ahí se aceptan visitas.
Marca qué puede hacer: medir visitas, recibir formularios, mostrar catálogo, recibir pedidos, recibir reservas o consultar las apps activas.
Pulsa Emitir y copia. El código que aparece debajo ya lleva la clave.

Se pega antes de </body>; en WordPress, en el editor de temas o en un plugin de insertar código en el pie. Si el sitio cambia de dominio, edita los orígenes o emite otra clave.

Merez cuenta visitas, visitantes únicos, rutas y de dónde llegan. No guarda datos personales: el visitante lleva un id anónimo de cookie propia. No hay título de página, conversiones ni duración de sesión; eso es de Google Analytics. Los latidos duplicados del mismo minuto cuentan una vez y los rastreadores se descartan.

Las habilidades se quitan y se ponen mientras la clave esté activa. Una clave sin ninguna no autoriza nada: el panel pide revocarla. Revocar corta al instante; si el formulario la usaba, deja de entrar todo. El código del chat del sitio crea su propia clave, Chat del sitio, con la habilidad de recibir formularios.

Tokens del servidor

Son las credenciales secretas con las que el servidor del sitio habla con Merez. Nunca van en el navegador: si el código lo descarga el visitante, va una clave del navegador.

Se emiten con un nombre que diga para qué son y dónde viven, y una o más habilidades. El nombre es lo único que se ve después. La habilidad * significa «todo lo habilitado, también lo que se habilite en el futuro»; va sola, nunca mezclada con concretas.

Habilidad	Qué permite
`track`	Latido de visitas
`leads`	Enviar leads desde el sitio
`catalog`	Leer productos y categorías
`blog`	Leer entradas y categorías
`project-log`	Leer la bitácora publicada
`certifications`	Verificar un certificado
`integrations`	Leer los IDs públicos de GA4 y Meta
`training`	Entrar y recuperar la clave de un aprendiz
`orders`	Crear un pedido y marcarlo pagado
`site`	Leer los datos de contacto de la empresa
`pages`	Leer las páginas publicadas
`fiscal`	Reportar la emisión de un documento
`documents`	Leer un documento sin guardarlo

Caducan: sin fecha, nacen con una caducidad por defecto. La lista muestra el último uso. Revocar corta al instante y no se deshace; el panel no deja revocar el token con el que estás llamando.

Webhooks

Avisan a tu sitio cuando su contenido cambia, con un Deploy Hook de Vercel, una revalidación o una llamada genérica. Eliges qué avisa: blog, catálogo, bitácora o sitio; sin marcar ninguno, de todo. El secreto HMAC es opcional y no aplica al Deploy Hook. Hay historial de entregas y reconstrucción nocturna de los webhooks activos. El sitio sirve la versión anterior hasta que la nueva está lista.

Qué ve un integrador

La API vive en https://api.merez.co/api/v1 y usa Authorization: Bearer <token>. Un token pertenece a un sitio y solo abre ese sitio. Cada ruta comprueba el módulo contratado y la habilidad del token; GET /site es la excepción y solo mira la habilidad. Un 403 dice cuál falló; un 401 es que no llegó credencial.

La respuesta es JSON sin envoltorio data, con sobre de paginación; las claves de un 422 son nombres de campo. El contrato solo crece.

En un sitio estático, la clave del navegador sustituye al token en el alta de leads: va como site_key en el cuerpo. No abre el resto de la API: solo sus familias.

Qué rompe

Una clave con orígenes que no incluyen el dominio real no reporta nada y el formulario no entra.
Un token en el navegador queda publicado. Se revoca aquí.
Revocar es inmediato y no se deshace: emite el reemplazo antes.
* no se combina con habilidades concretas: el servidor rechaza la mezcla.

Errores frecuentes

Síntoma	Causa	Qué hacer
No se ven visitas	La clave no incluye el origen real	Editar orígenes o emitir otra
El formulario no entrega	Clave revocada o sin `leads`	Revisar clave y habilidad
El token da 403	Le falta la habilidad o el módulo	Añadir la habilidad o encender el módulo
Perdí el token	Solo se muestra al emitirlo	Emitir otro y revocar el viejo