# Documentación de StampyWallet > La documentación de StampyWallet, la tarjeta de fidelidad en Apple Wallet y Google Wallet para comercios de proximidad: la guía del comerciante, el servidor MCP y sus herramientas, la API y los webhooks, y el skill «tarjetas bonitas». Este archivo reúne todas las páginas de https://stampywallet.com/es/docs/ en texto. En caso de duda, la página en línea es la que vale. --- # Bienvenido a la documentación de StampyWallet StampyWallet es una tarjeta de fidelidad en Apple Wallet y Google Wallet, sin aplicación. Aquí tienes todo lo necesario para crearla, escanearla en el mostrador y gestionarla desde un asistente de IA o tu TPV. - [Guía del comerciante](https://stampywallet.com/es/docs/guia/crear-tu-tarjeta/) : Crear tu tarjeta, escanearla, hacer que tus clientes vuelvan. - [MCP y asistentes de IA](https://stampywallet.com/es/docs/mcp/conectar/) : Claude, ChatGPT, Cursor: conectar y usar cada herramienta. - [API y webhooks](https://stampywallet.com/es/docs/api/) : Conectar StampyWallet con tu TPV, tu web o Zapier. - [skill.md](https://stampywallet.com/es/docs/skill/) : Enseñar a tu asistente a diseñar tarjetas bonitas. ## Inicio rápido 1. **Crea tu tarjeta.** El nombre de tu comercio, tu tipo de tarjeta, tus recompensas: unos minutos en [stampywallet.com](site:#inscription), 30 días de prueba. 2. **Pon el cartel en el mostrador.** Tus clientes escanean el QR y la tarjeta llega a su Wallet, sin aplicación. 3. **Escanea en cada visita.** Con tu móvil: la tarjeta del cliente se actualiza sola. ## Por dónde empezar - Vas a abrir tu cuenta: [Crear tu tarjeta en 5 minutos](https://stampywallet.com/es/docs/guia/crear-tu-tarjeta/) y luego [Los tipos de tarjeta](https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/). - Estás en el mostrador: [Escanear una tarjeta](https://stampywallet.com/es/docs/guia/escanear/) y [Tu equipo](https://stampywallet.com/es/docs/guia/equipo/). - Quieres que tus clientes vuelvan: [Mensajes y notificaciones](https://stampywallet.com/es/docs/guia/mensajes/), [Tarjetas regalo y bonos](https://stampywallet.com/es/docs/guia/tarjetas-regalo-y-bonos/), [Reseñas de Google](https://stampywallet.com/es/docs/guia/resenas-google/). - Trabajas con una IA: [conectar Claude, ChatGPT o Cursor](https://stampywallet.com/es/docs/mcp/conectar/) y el [skill «tarjetas bonitas»](https://stampywallet.com/es/docs/skill/). - Conectas un TPV o una herramienta: [la API y los webhooks](https://stampywallet.com/es/docs/api/). > **Consejo :** esta documentación también existe en texto plano para los asistentes de IA, en [/llms.txt](llms.txt) y [/docs/llms-full.txt](llms-full.txt). ## Preguntas frecuentes **¿Mis clientes tienen que instalar una aplicación?** No. La tarjeta se añade a Apple Wallet o a Google Wallet, que ya están en su móvil, al escanear el QR de tu cartel. Sin Wallet, el cliente recibe su tarjeta por correo, con un enlace a una tarjeta web. **¿Qué precio tiene StampyWallet al mes?** El plan Esencial cuesta 20 € sin IVA al mes para un local, el plan Crecimiento 40 € sin IVA al mes (mensajes automáticos, SMS, reseñas de Google, API, TPV y webhooks) y el plan Red desde 90 € sin IVA al mes. Los primeros 30 días son gratis, con todas las funciones de Crecimiento y sin permanencia. **¿Necesito un desarrollador?** No. La tarjeta, el escaneo en el mostrador y los mensajes se configuran en tu espacio StampyWallet, sin código. La API solo sirve para conectar un TPV o un programa, y para Square, Shopify, SumUp, Zettle, Zapier, Make y n8n, la página [Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/) da los ajustes paso a paso. **¿Necesito una tableta o un lector en el mostrador?** No. El escaneo se hace con el móvil del comercio, un iPhone o un Android, y cada miembro del equipo tiene su propio acceso. Source : https://stampywallet.com/es/docs/ --- # Crear tu tarjeta en 5 minutos Abrir tu cuenta, elegir tu tipo de tarjeta, personalizarla, probarla en tu móvil e imprimir el cartel del mostrador. ## 1. Abrir tu cuenta En [stampywallet.com](site:#inscription), escribe tu correo: te llega un código de seis cifras, sin contraseña que inventar. También puedes continuar con Google o con Apple. La prueba dura **30 días**, con todas las funciones del plan Crecimiento. Se pide una tarjeta bancaria para empezarla y no se cobra nada durante la prueba; se cancela en un clic. ## 2. Tu comercio Tres preguntas: - **El nombre del comercio**, impreso en la parte superior de la tarjeta. - **Eres**: cafetería, panadería, restaurante, uñas y pestañas, centro de estética, barbería, tienda u otro. Esta elección propone recompensas, un sello y unos colores adaptados. - **Tu logo**, opcional (PNG o JPEG). ## 3. Elegir el tipo de tarjeta Tres tipos, cada uno mostrado en dos diseños, ya con tu nombre y tus colores: | Tipo | El cliente gana | Ideal para | |---|---|---| | **Sellos** | Una recompensa al cabo de N visitas | Cafeterías, panaderías, barberías | | **Varias recompensas** | Recompensas cada vez mejores en la misma tarjeta | Centros de estética, uñas, restaurantes | | **Puntos** | Puntos en cada visita, según lo que gasta | Tickets que varían mucho | El detalle de cada tipo: [Los tipos de tarjeta](https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/). ## 4. Personalizarla La siguiente pantalla muestra la tarjeta en directo mientras la ajustas: - **Tus recompensas**: hasta ocho, cada una con una foto o un icono. - **La forma** de la tarjeta, **el color** y **el logo**. - **Proponer a tus clientes dejar su número**, para los SMS y las reseñas de Google. Luego todo se puede cambiar en cualquier momento en **Tu tarjeta**: cada cambio se guarda solo y llega a los móviles de tus clientes. ## 5. Probarla en tu móvil «Tu tarjeta está lista»: añade la tarjeta de prueba a tu propio móvil y toca **Sellar**. Llega un sello de verdad, con su notificación, como le pasaría a un cliente. ## 6. Imprimir el cartel En **Cartel**, descarga el código QR de registro: - **Expositor de mostrador (A5)** o **Formato pequeño (A6)**, en PDF listo para imprimir; - **solo el QR**, en PNG o SVG, para una carta, un escaparate o Canva; - **Enviármelo por correo**, para imprimirlo desde otro dispositivo. El cartel lleva a la página pública de tu tarjeta, `stampywallet.com/rejoindre/`. Este enlace puede volverse legible (`/rejoindre/le-fournil`) en **Tu tarjeta › El enlace**, para una bio de Instagram o un folleto. Cambiarlo no rompe nada: los carteles ya impresos siguen funcionando. ## Lo que ve tu cliente Escanea el cartel con la cámara de su móvil y se abre una página con su tarjeta: - **Añadir a Apple Wallet** o **Añadir a Google Wallet**: su móvil le propone primero el que corresponde; - o **recibir su tarjeta por correo**, con un enlace a una tarjeta web. Sin aplicación y sin cuenta que crear. Por defecto, solo se pide su nombre. > **Lo que le pides al cliente :** en **Tu tarjeta › Registro de clientes**, cada campo es «No se pide», «Opcional» u «Obligatorio»: nombre, apellido, cumpleaños (el día y el mes, nunca el año), correo, teléfono. Pide solo lo que te sirva: el cumpleaños para el mensaje de cumpleaños, el correo o el teléfono para las reseñas de Google y los SMS. > **Consejo :** ¿quieres que una IA diseñe la tarjeta por ti, con las fotos de tu comercio? Mira el [skill «tarjetas bonitas»](https://stampywallet.com/es/docs/skill/) y la herramienta [`concevoir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/). ## Preguntas frecuentes **¿Necesito una tarjeta bancaria para la prueba?** Sí, se pide una tarjeta bancaria para empezar la prueba de 30 días. No se cobra nada durante la prueba, y cancelas con un clic. **¿La tarjeta funciona en iPhone y en Android?** Sí. En iPhone va a Apple Wallet; en Android, a Google Wallet: la página de registro propone primero el que corresponde. Un cliente sin Wallet puede recibir su tarjeta por correo, con un enlace a una tarjeta web. **¿Puedo cambiar mi tarjeta después de lanzarla?** Sí, en cualquier momento en **Tu tarjeta**. Cada cambio se guarda solo y llega a los móviles de tus clientes. **¿Qué datos se piden a mis clientes?** Por defecto, solo su nombre. En **Tu tarjeta › Registro de clientes**, el apellido, el cumpleaños (día y mes, nunca el año), el correo y el teléfono pueden ser «No se pide», «Opcional» u «Obligatorio». **¿Mis carteles impresos siguen funcionando si cambio el enlace?** Sí. Volver legible el enlace en **Tu tarjeta › El enlace** no rompe nada: los carteles ya impresos siguen funcionando. Source : https://stampywallet.com/es/docs/guia/crear-tu-tarjeta/ --- # Los tipos de tarjeta Una tarjeta de StampyWallet funciona según uno de tres modos, sellos, varias recompensas (niveles) o puntos, y cada modo se presenta en varias formas. ## ¿Qué modo elegir? | Modo | El cliente gana | Ideal para | |---|---|---| | `tampons` | Un sello por visita y una recompensa al final | Cafeterías, panaderías, barberías | | `paliers` | Varias recompensas cada vez mejores, en el mismo contador | Centros de estética, uñas, floristerías, restaurantes | | `points` | Puntos en cada visita, según el importe o el servicio | Tiendas de alimentación, vinotecas, tickets variables | > **Nota :** puedes cambiar de modo más adelante, en **Tu tarjeta › Cambiar de tipo**. Ningún cliente pierde su progreso: sus sellos se quedan en su tarjeta (en puntos, cuentan como puntos). Tu diseño y tus colores también se mantienen. ## Sellos El clásico de la tarjeta de cartón: un sello por visita, una recompensa al final y la tarjeta vuelve a empezar. El número de casillas va de 2 a 50. ![Una tarjeta de sellos de cafetería, generada por StampyWallet](https://stampywallet.com/assets/img/blog/cartes/cafe-tampons-en.webp "Una tarjeta de sellos, tal como aparece en el Wallet del cliente.") Cuatro formas: **casillas** (la cuadrícula), **sin casillas** (sellos dispersos), **objetos** (grandes objetos con sombra, ideal con la foto de tu producto) y **círculos**. ## Varias recompensas (niveles) Hasta ocho recompensas en el mismo contador, por ejemplo un café a las 5 visitas, un cruasán a las 10 y un desayuno a las 20. Cada nivel tiene su umbral, su texto y su foto o su icono. ![Una tarjeta de panadería con varias recompensas](https://stampywallet.com/assets/img/blog/cartes/boulangerie-paliers-en.webp "Una tarjeta por niveles: cada recompensa en su umbral, con su foto.") Cinco formas además de los sellos: **camino** (una ruta en la que cada visita hace avanzar al cliente), **vitrina** (las recompensas una al lado de otra), **medallas**, **relleno** (la próxima recompensa en grande, que se va coloreando) y **anillo**. ```text title="Pedírselo a la IA" Diseña la tarjeta de la Boulangerie Lemaire por niveles: - 5 visitas: un cruasán - 10 visitas: una baguette tradicional - 20 visitas: un roscón de Reyes ``` ```json title="JSON (concevoir_carte)" { "nom": "Boulangerie Lemaire", "mode": "paliers", "paliers": [ { "a": 5, "recompense": "Un cruasán" }, { "a": 10, "recompense": "Una baguette tradicional" }, { "a": 20, "recompense": "Un roscón de Reyes" } ] } ``` ## Puntos Puntos en cada visita, cuando el ticket varía mucho de un cliente a otro. Las recompensas se consiguen al llegar a ciertos umbrales de puntos, con las mismas cinco formas que los niveles. ![Una tarjeta de puntos de un salón de té](https://stampywallet.com/assets/img/blog/cartes/the-points-en.webp "Una tarjeta de puntos: la barra avanza según lo que gasta el cliente.") En **Tu tarjeta › Más ajustes › Los puntos**: - **Puntos por visita**: el valor propuesto por defecto en el escáner. - **Valores rápidos**: hasta seis atajos, que se ponen con un gesto en el mostrador. - **Nombre de tus puntos**: «puntos», «semillas», «estrellas»… - **Según el importe del ticket**: un número de puntos por euro; escribes el total del ticket en el mostrador y el cálculo se hace solo. > **Atención :** en modo puntos, el valor se elige en el mostrador en cada escaneo, o llega solo desde tu TPV con la [API](https://stampywallet.com/es/docs/api/anadir-visita/). ## Los estilos Seis colecciones visten la tarjeta: **Esencial**, **Café clásico**, **Botánico**, **Trattoria**, **Taller** y **Pase** (como un pase de Apple Wallet: logo en grande, fondo liso). Cada una propone varias paletas, y el color también puede ser libre. ## Las reglas En **Tu tarjeta › Más ajustes › Reglas**: - **Sellos de regalo al darse de alta**: de 0 a 5. Una tarjeta ya empezada da ganas de terminarla. - **Validez de una recompensa**: nunca caduca, o 1, 2, 3, 6 o 12 meses después de ganarla. - **Un sello por cada…**: un importe (por ejemplo un sello por cada 10 €). Escribes el total del ticket en el mostrador. - **Dos contadores**: una gama premium con su propio objetivo y su recompensa; eliges «normal» o «premium» en el escáner. ## Preguntas frecuentes **¿Qué diferencia hay entre sellos, niveles y puntos?** Con los sellos, cada visita da un sello y la tarjeta llena da una recompensa, y luego vuelve a empezar. Con los niveles, hasta ocho recompensas cada vez mejores se reparten en el mismo contador. Con los puntos, el cliente gana puntos según el importe o el servicio, y las recompensas se consiguen al llegar a ciertos umbrales de puntos. **¿Puedo cambiar de tipo de tarjeta más adelante?** Sí, en **Tu tarjeta › Cambiar de tipo**. Ningún cliente pierde su progreso: sus sellos se quedan en su tarjeta y cuentan como puntos en el modo puntos. Tu diseño y tus colores también se quedan. **¿Cuántas casillas puede tener una tarjeta de sellos?** De 2 a 50 casillas. **¿Se puede dar un sello según el importe del ticket?** Sí. La regla **Un sello por cada…** da, por ejemplo, un sello por cada 10 €: escribes el total del ticket en el mostrador. En el modo puntos, **Según el importe del ticket** da un número de puntos por euro. **¿Los tres tipos están incluidos en el plan Esencial?** Sí. Sellos, puntos y recompensas por niveles están incluidos en todos los planes, desde Esencial. Source : https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/ --- # Escanear una tarjeta en el mostrador Poner un sello o puntos, entregar una recompensa, deshacer un error, encontrar a un cliente sin cámara y seguir sin conexión. El escaneo se hace desde el móvil del comercio, un iPhone o un Android, sin lector ni tableta. Cada miembro del equipo tiene su propio acceso ([Tu equipo](https://stampywallet.com/es/docs/guia/equipo/)). ## Poner un sello 1. **Abre Escanear.** La cámara se abre enseguida. 2. **Apunta a la tarjeta del cliente**, en su móvil (no al cartel). 3. **Comprueba la pantalla «Tarjeta leída»**: el nombre y el progreso, por ejemplo 7 → 8 de 10. 4. **Toca «Poner el sello».** La tarjeta del cliente se actualiza en su Wallet. «No es este cliente» cancela la lectura. ![El escaneo de una tarjeta en el mostrador](https://stampywallet.com/assets/img/step-scan.webp "El móvil del comercio lee la tarjeta en el Wallet del cliente.") **Varios sellos de golpe**: antes de apuntar, ajusta el número con − y +, hasta 50. Si tu tarjeta cuenta por importe («un sello por cada 10 €»), escribe mejor el total del ticket. El valor vuelve a 1 después de cada escaneo. ## Poner puntos En una tarjeta de puntos, elige el valor antes de apuntar: el valor por defecto, un valor rápido o «…» para otro. Con la regla «según el importe del ticket», cambia a **Importe** y escribe el total: los puntos se calculan solos. ## Entregar una recompensa Cuando una visita hace ganar una recompensa, la pantalla muestra **Recompensa conseguida**: - **Entregada**: la das ahora; - **Más tarde**: se queda en la tarjeta del cliente, lista para su próxima visita. Si hay varias recompensas que entregar, se propone la siguiente enseguida. ## Deshacer un error Justo después de un escaneo, la barra inferior propone **Deshacer**. - El propietario y los encargados pueden deshacer en cualquier momento el último sello de un cliente o una recompensa entregada. - Un empleado puede deshacer su propia acción durante **5 minutos**. - Solo se puede deshacer la última visita. Un sello cuya recompensa ya se ha entregado se deshace después de la recompensa. - Se puede indicar un motivo (tarjeta equivocada, escaneada dos veces, cantidad equivocada, entregada por error). La anulación queda registrada a tu nombre. ## El doble escaneo Por defecto, dos visitas del mismo cliente con menos de un minuto y medio de diferencia solo cuentan una vez: «Ya se ha sellado hace un momento». Ajusta este plazo en **Ajustes › El mostrador › Dos visitas del mismo cliente**: contar siempre, una por minuto, por cinco minutos, por hora o por media jornada. ## Sin cámara: buscar un cliente **Buscar un cliente** encuentra una tarjeta por el nombre, el apellido, el correo, el teléfono o el código impreso bajo el QR. La misma búsqueda también encuentra las tarjetas regalo (por su código) y los bonos. Después, el sello pasa por la misma pantalla de confirmación. ## Sin conexión Si la red no responde, el sello se guarda en el móvil («Sello guardado, pendiente de confirmar») y sale en cuanto vuelve la conexión, sin duplicados. El escáner se abre incluso sin conexión, y la búsqueda de clientes funciona con la lista guardada en el móvil. > **Atención :** entregar una recompensa y deshacer una visita requieren conexión. > **Consejo :** instala el escáner como una aplicación: el navegador lo propone («Instalar la app») y después se abre con un gesto, a pantalla completa. ## El cumpleaños en el mostrador Cuando es el cumpleaños del cliente, la pantalla siempre lo indica. Si hay un regalo de cumpleaños abierto en su tarjeta, aparece con el botón **Oferta usada** (o dos botones cuando el cliente elige su regalo). Consulta [Mensajes y notificaciones](https://stampywallet.com/es/docs/guia/mensajes/#anniversaire). Source : https://stampywallet.com/es/docs/guia/escanear/ --- # Tu equipo Invitar a tus empleados y encargados, lo que puede hacer cada rol y seguir los sellos que pone cada uno. Equipo ilimitado en todos los planes. Tantas cuentas como personas en el mostrador, sin coste extra, en todos los planes. Cada uno escanea desde su propio móvil, con su propio acceso. ## Los roles | Acción | Propietario | Encargado | Empleado | |---|---|---|---| | Sellar una tarjeta, entregar una recompensa | Sí | Sí | Sí | | Ver las cifras y los clientes | Sí | Sí | No | | Escribir a los clientes | Sí | Sí | No | | Cambiar la tarjeta y los ajustes | Sí | Sí | No | | Invitar, retirar, gestionar la suscripción | Sí | No | No | Un empleado solo ve **Escanear** y su cuenta, además de las tarjetas regalo y los bonos cuando el comercio los vende. Un comercio siempre conserva al menos un propietario. ## Invitar a alguien 1. **Abre Tu equipo › Invitar a alguien** (solo el propietario). 2. **Elige el rol**: empleado o encargado. Añade una referencia si quieres («Julie, por la mañana»). 3. **Envía**: con su correo, la invitación sale por correo; sin correo, **Crear el enlace** y luego **Copiar el enlace**, para enviarlo como quieras. Una invitación es válida **catorce días**. Puedes reenviarla o retirarla mientras no se haya usado. Una invitación de encargado enviada a un correo solo se acepta con ese correo. ## Cambiar un rol, retirar a alguien En **Tu equipo**, cambia el rol de un miembro o retira su acceso: sus sesiones se cierran al instante. ## La actividad por persona **Ver la actividad por persona** muestra, en 7 o 30 días, los sellos puestos, las recompensas entregadas y las anulaciones de cada miembro. > **Consejo :** desde un asistente de IA conectado, la herramienta [`equipe`](https://stampywallet.com/es/docs/mcp/herramientas/equipe/) lista el equipo, invita y cambia los roles, siempre con tu aprobación. Source : https://stampywallet.com/es/docs/guia/equipo/ --- # Mensajes y notificaciones Escribir a tus clientes en la pantalla de bloqueo de su móvil, dirigirte a un grupo, programar un envío y dejar que los recordatorios, el aviso a los clientes perdidos y el cumpleaños salgan solos. Una tarjeta en el Wallet puede mostrar una notificación en la pantalla de bloqueo del cliente. Es gratis, en todos los planes, y es lo que hace que vuelvan. ## Enviar un mensaje En **Notificaciones › Enviar un mensaje**: - **180 caracteres** como máximo, con una vista previa de lo que verá el cliente. Tres plantillas para empezar. - **Un mensaje al día** por comercio, para no cansar a tus clientes. - Antes del envío, la pantalla indica cuántos clientes lo recibirán: los que tienen la tarjeta en un Wallet. Una tarjeta web (recibida por correo) no recibe notificaciones. **A quién**: a todos tus clientes, en todos los planes. Con el plan Crecimiento, a un grupo: los que no vienen desde hace 30, 60 o 90 días, los que están cerca de la recompensa, los que cumplen años este mes, los mejores clientes (el 20 % que más viene), los nuevos. **Programar** (Crecimiento): elige el día y la hora del envío, hasta 60 días antes, entre las 7:00 y las 22:00, en la hora del comercio. Un mensaje programado se puede modificar, cancelar o enviar enseguida. ## Los mensajes automáticos Plan Crecimiento, en **Ajustes**: | Mensaje | Cuándo sale | Por defecto | |---|---|---| | Solo falta un sello | Solo falta una visita para la recompensa | Activado | | Tu recompensa está aquí | El cliente acaba de ganar una recompensa | Activado | | El recordatorio | Un cliente habitual deja de venir | Activado | | El cumpleaños | El día del cumpleaños del cliente | Activado | Los dos recordatorios salen después de la visita, con el retraso elegido: enseguida, 30 minutos, 1 hora (por defecto), 3 horas o al día siguiente. ### El recordatorio a los clientes perdidos de vista Un cliente habitual está «perdido de vista» cuando su ausencia supera su propio ritmo de visitas o, sin historial suficiente, el plazo de tu comercio (propuesto según tu sector y ajustable). Solo cuentan los días de apertura: declara tus vacaciones y días de cierre en **Ajustes › Tus cierres** para que nadie reciba un recordatorio a tu vuelta. Un recordatorio por ausencia; su texto (180 caracteres) se puede modificar. ### El cumpleaños Para activarlo, pide el cumpleaños en el registro ([lo que le pides al cliente](https://stampywallet.com/es/docs/guia/crear-tu-tarjeta/)). Ese día, el cliente recibe un mensaje y su regalo, válido 30 días: - **solo un mensaje**; - **un descuento** del 1 al 90 % en cada compra durante 30 días; - **2x1**, una vez; - **a elegir por el cliente**, entre el descuento y el 2x1, elegido en el mostrador. Un mensaje por persona y por año, si el cliente se registró antes de su cumpleaños. En el mostrador, el escáner muestra el regalo con el botón **Oferta usada**. ## Las horas de silencio Por defecto, ningún mensaje automático llega entre las 21:00 y las 9:00. Un envío que cae en esa franja se aplaza, no se pierde. ## Notificación, SMS, correo - **La notificación de Wallet** es gratuita e ilimitada, en todos los planes. - **El SMS** (Crecimiento) toma el relevo cuando la tarjeta no está en un Wallet, para los clientes que han dejado su número: se incluyen 200 SMS al mes, repartidos a lo largo del mes, con una reserva para los mensajes importantes. Sin SMS los domingos, los festivos ni fuera de las 8:00 a 20:00, nunca más de tres por semana al mismo número y nunca promociones a quien las ha rechazado. - **El correo** sirve de respaldo para las reseñas de Google y el cumpleaños. El canal se ajusta por tipo de mensaje en **Ajustes › Mensajes y SMS**: automático (recomendado), solo notificación, SMS de respaldo, SMS primero o correo de respaldo. ## Lo que han conseguido tus mensajes Con el plan Crecimiento, uno de cada diez clientes, elegido al azar, no recibe ni las promociones ni el recordatorio. Siete días después de cada mensaje, el **informe** compara quién ha vuelto en cada grupo: la diferencia es lo que el mensaje ha aportado de verdad. ## El resumen del lunes Cada lunes por la mañana, el propietario recibe por correo el resumen de la semana: sellos, clientes nuevos, recompensas y los clientes perdidos de vista. No hay resumen en una semana sin actividad. > **Consejo :** desde un asistente de IA conectado: [`envoyer_message`](https://stampywallet.com/es/docs/mcp/herramientas/envoyer_message/) para un mensaje, [`regler_automatismes`](https://stampywallet.com/es/docs/mcp/herramientas/regler_automatismes/) para los automáticos, [`fermetures`](https://stampywallet.com/es/docs/mcp/herramientas/fermetures/) para las vacaciones. Source : https://stampywallet.com/es/docs/guia/mensajes/ --- # Tarjetas regalo y bonos Vender tarjetas regalo y bonos prepagados en el mostrador, enviarlos al Wallet y descontarlos al escanear. Dos productos del plan Crecimiento que viven en el Wallet igual que la tarjeta de fidelidad. En ambos casos, **cobras en tu caja, como siempre**: StampyWallet no gestiona el pago ni vende nada en línea. ## Las tarjetas regalo ![Dos tarjetas regalo de StampyWallet](https://stampywallet.com/assets/img/blog/cartes/cadeaux-duo-es.webp "Una tarjeta regalo de producto y una tarjeta regalo de importe, con los colores del comercio.") ### Preparar la venta En **Tarjetas regalo › Ajustes**: - **productos**, con su precio y su foto (hasta 24); - **importes** (hasta 8), y si quieres, un importe libre; - **la validez**: 3, 6 o 12 meses tras la venta. Luego **Poner a la venta**. La tarjeta regalo toma el logo y los colores de tu tarjeta de fidelidad. ### Vender 1. **Cobra** en tu caja. 2. **Vender una tarjeta regalo**: el producto o el importe, «Para», «De parte de», una nota. Un empleado también puede vender. 3. **Entrégala**: un QR para escanear, un enlace para compartir (WhatsApp, SMS), o StampyWallet la envía por SMS o por correo. Quien la recibe la añade a Apple Wallet o Google Wallet, o la guarda en su página web. ### Usarla en el mostrador Escanea la tarjeta regalo o busca su código de 8 caracteres: - una tarjeta **de producto**: **Entregar**, y queda usada; - una tarjeta **de importe**: **Cobrar** el importe deseado; se muestra el saldo antes y después, y el saldo se actualiza en el Wallet. Una tarjeta ya vendida se sigue aceptando en todos los planes, aunque dejes de vender. ## Los bonos prepagados Diez sesiones, diez cafés, cinco tratamientos: el cliente paga por adelantado y cada visita descuenta una unidad. - De 1 a 100 unidades, con la palabra que elijas (sesión, tratamiento, café…). - Hasta 12 modelos de bono, válidos 1, 2, 3, 6 o 12 meses, o sin límite. - Venta: cobra y luego **Ya he cobrado, crear el bono**. El cliente recibe su bono en su Wallet. - En el mostrador: **Descontar 1 sesión** (o tu unidad). El último descuento se puede deshacer durante 24 horas. - El Wallet avisa al cliente una semana antes del vencimiento y cuando le quedan pocas unidades. Source : https://stampywallet.com/es/docs/guia/tarjetas-regalo-y-bonos/ --- # Reseñas de Google Pedir una reseña de Google a cada cliente en el momento adecuado, con un enlace directo a tu ficha, sin filtrar ni recompensar, siguiendo las reglas de Google. Con el plan Crecimiento, StampyWallet pide una reseña de Google a tus clientes en el momento en que están más contentos: con su primera recompensa o tras unas cuantas visitas. ## Cómo funciona - **El mismo mensaje para todos**, con el enlace directo a tu ficha de Google. - **Sin nota intermedia**, sin filtrar a los clientes según su opinión y **sin ninguna recompensa** a cambio de una reseña: son las reglas de Google y StampyWallet las sigue. - **Una solicitud por cliente**, una sola vez. ## Activarlo 1. **Pega tu enlace de reseñas de Google** en **Reseñas de Google**. Sin él, no sale nada. Lo encuentras en tu ficha de Google, botón «Pedir reseñas». 2. **Pide el correo o el teléfono** en el registro ([Crear tu tarjeta](https://stampywallet.com/es/docs/guia/crear-tu-tarjeta/)): la solicitud sale por SMS o por correo. 3. **Elige el momento**: con la primera recompensa (por defecto) o tras un número de visitas (3 por defecto). 4. **Elige el retraso** tras la visita: enseguida, 30 minutos, 1 hora, 3 horas (por defecto) o al día siguiente. Se aplican las horas de silencio. > **Nota :** la notificación de Wallet no lleva enlace. Por eso la solicitud sale primero por SMS (dentro de tu presupuesto de 200 SMS al mes) o por correo, según tu ajuste en **Ajustes › Mensajes y SMS**. El enlace también está en el reverso de la tarjeta del cliente. ## Las cifras La pantalla **Reseñas de Google** muestra las solicitudes enviadas y los clics hacia Google en los últimos 30 días. > **Consejo :** desde un asistente de IA conectado, la herramienta [`avis_google`](https://stampywallet.com/es/docs/mcp/herramientas/avis_google/) lee estas cifras y ajusta la solicitud. Source : https://stampywallet.com/es/docs/guia/resenas-google/ --- # Conectar un asistente de IA El servidor MCP de StampyWallet conecta Claude, ChatGPT, Cursor o un agente con tu tarjeta de fidelidad. Una dirección, ninguna clave, y nada cambia sin tu aprobación. StampyWallet habla el **Model Context Protocol** (MCP), el estándar que permite a un asistente de IA usar herramientas. Una vez conectado, puedes pedir en la conversación: «diséñame una tarjeta de fidelidad», «¿cuántos clientes han venido este mes?», «avisa a mis clientes habituales de que cierro el lunes». ## La dirección del servidor ```text title="Servidor MCP" https://app.stampywallet.com/mcp ``` HTTP «streamable», respuestas JSON, sin estado. Es lo único que tienes que darle a tu asistente. **Claude** **Configuración › Conectores › Añadir conector personalizado**, pega la dirección. Paso a paso: [Claude](https://stampywallet.com/es/docs/mcp/claude/). **ChatGPT** **Configuración › Aplicaciones y conectores**, modo desarrollador, **Crear**, pega la dirección. Paso a paso: [ChatGPT](https://stampywallet.com/es/docs/mcp/chatgpt/). **Cursor y agentes** ```json title=".cursor/mcp.json" { "mcpServers": { "stampywallet": { "url": "https://app.stampywallet.com/mcp" } } } ``` Paso a paso, y Claude Code: [Cursor y agentes](https://stampywallet.com/es/docs/mcp/cursor/). ## Sin cuenta, y luego con tu cuenta El servidor ofrece dos familias de herramientas en la misma dirección: - **Sin cuenta**: [`concevoir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/) diseña una tarjeta a imagen de un comercio, [`simuler_fidelite`](https://stampywallet.com/es/docs/mcp/herramientas/simuler_fidelite/) calcula lo que cuesta, y [`creer_commerce`](https://stampywallet.com/es/docs/mcp/herramientas/creer_commerce/) la pone en marcha y devuelve un enlace para convertirse en su propietario. No se pide ninguna conexión. - **Con tu cuenta**: tus cifras, tus clientes, tus mensajes, las reseñas de Google, los ajustes de la tarjeta, el cartel, el equipo. En la primera llamada, el asistente abre la página de inicio de sesión de StampyWallet (OAuth): inicias sesión, eliges el comercio y autorizas el acceso. En la pantalla de autorización, puedes marcar **solo lectura**: el asistente lee tus cifras y tus ajustes, pero no puede cambiar nada. Los accesos se gestionan en **Ajustes › Tus datos › Asistentes conectados**, donde cada asistente se desconecta con un clic. | Alcance | Lo que permite | |---|---| | `stampy.lecture` | Leer tus cifras, tus clientes (nombres), tus ajustes y tu tarjeta | | `stampy.ecriture` | Actuar por ti: mensajes a los clientes, ajustes, tarjeta, equipo, siempre con tu aprobación en la conversación | ## Nada cambia sin tu aprobación Las herramientas que escriben aceptan un parámetro `confirmer`, `false` por defecto. Llamadas así, no hacen nada: devuelven una **vista previa** (el texto exacto de un mensaje y el número de destinatarios, el antes y el después de un ajuste). El asistente te la enseña y solo vuelve a llamar a la herramienta con `confirmer: true` después de tu «sí». > **Atención :** dos cosas solo se hacen en el mostrador, escaneando la tarjeta del cliente: **poner sellos** y **entregar recompensas**. Ninguna herramienta MCP lo hace. Para ponerlos desde un TPV, existe la [API](https://stampywallet.com/es/docs/api/anadir-visita/). ## Las herramientas | Herramienta | Cuenta | Efecto | |---|---|---| | [`concevoir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/) | Sin | Solo lectura | | [`simuler_fidelite`](https://stampywallet.com/es/docs/mcp/herramientas/simuler_fidelite/) | Sin | Solo lectura | | [`creer_commerce`](https://stampywallet.com/es/docs/mcp/herramientas/creer_commerce/) | Sin | Escribe (confirmar) | | [`tableau_de_bord`](https://stampywallet.com/es/docs/mcp/herramientas/tableau_de_bord/) | Con | Solo lectura | | [`rentabilite`](https://stampywallet.com/es/docs/mcp/herramientas/rentabilite/) | Con | Solo lectura | | [`meilleurs_moments`](https://stampywallet.com/es/docs/mcp/herramientas/meilleurs_moments/) | Con | Solo lectura | | [`chercher_clients`](https://stampywallet.com/es/docs/mcp/herramientas/chercher_clients/) | Con | Solo lectura | | [`fiche_client`](https://stampywallet.com/es/docs/mcp/herramientas/fiche_client/) | Con | Solo lectura | | [`envoyer_message`](https://stampywallet.com/es/docs/mcp/herramientas/envoyer_message/) | Con | Escribe (confirmar) | | [`historique_messages`](https://stampywallet.com/es/docs/mcp/herramientas/historique_messages/) | Con | Solo lectura | | [`regler_automatismes`](https://stampywallet.com/es/docs/mcp/herramientas/regler_automatismes/) | Con | Escribe (confirmar) | | [`fermetures`](https://stampywallet.com/es/docs/mcp/herramientas/fermetures/) | Con | Escribe (confirmar) | | [`avis_google`](https://stampywallet.com/es/docs/mcp/herramientas/avis_google/) | Con | Escribe (confirmar) | | [`voir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/voir_carte/) | Con | Solo lectura | | [`modifier_carte`](https://stampywallet.com/es/docs/mcp/herramientas/modifier_carte/) | Con | Escribe (confirmar) | | [`fiche_commerce`](https://stampywallet.com/es/docs/mcp/herramientas/fiche_commerce/) | Con | Escribe (confirmar) | | [`affichette`](https://stampywallet.com/es/docs/mcp/herramientas/affichette/) | Con | Solo lectura | | [`envoyer_affichette`](https://stampywallet.com/es/docs/mcp/herramientas/envoyer_affichette/) | Con | Escribe (confirmar) | | [`equipe`](https://stampywallet.com/es/docs/mcp/herramientas/equipe/) | Con | Escribe (confirmar) | Las herramientas que requieren una cuenta también respetan tu rol (un empleado no tiene acceso a ninguna; [`equipe`](https://stampywallet.com/es/docs/mcp/herramientas/equipe/) está reservada al propietario) y tu plan (algunas cifras y las reseñas de Google requieren Crecimiento). ## Probar a mano El servidor responde a cualquier cliente MCP, o a `curl`: ```bash title="curl" curl https://app.stampywallet.com/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` Sin cuenta, las llamadas están limitadas por dirección IP: por encima del límite, el servidor pide esperar unos minutos. ## Preguntas frecuentes **¿Necesito una clave para conectar el servidor MCP?** No, ninguna clave. Las herramientas sin cuenta funcionan enseguida; para tus cifras y tus clientes, el asistente te pide conectar tu cuenta StampyWallet en la primera llamada. **¿Funciona con ChatGPT gratis?** Por parte de StampyWallet, no hay nada que pagar para conectar el servidor, y las herramientas sin cuenta están abiertas a todos. Por parte de ChatGPT, el conector se crea en modo desarrollador, y el acceso a ese modo depende de tu plan de ChatGPT. Si el tuyo no lo ofrece, Claude, Cursor o cualquier otro cliente MCP se conectan a la misma dirección. **¿El asistente puede cambiar algo sin mi aprobación?** No. Las herramientas que escriben devuelven primero una vista previa, y el asistente solo las vuelve a llamar con `confirmer: true` después de tu «sí». También puedes autorizar solo la lectura. **¿El asistente puede poner sellos?** No. Poner sellos y dar recompensas se hace solo en el mostrador, escaneando la tarjeta del cliente. Desde un TPV, lo hace la [API](https://stampywallet.com/es/docs/api/anadir-visita/). **¿Cómo corto el acceso de un asistente?** En **Ajustes › Tus datos › Asistentes conectados**: cada asistente se corta con un clic. Source : https://stampywallet.com/es/docs/mcp/conectar/ --- # Conectar Claude Añadir StampyWallet como conector personalizado en Claude (web, escritorio y móvil) y luego conectar tu cuenta. 1. **Abre Claude** (claude.ai o la aplicación de escritorio) y luego **Configuración › Conectores**. 2. **Añadir conector personalizado.** Nombre: `StampyWallet`. Dirección: `https://app.stampywallet.com/mcp`. 3. **Actívalo en una conversación**, desde el menú de herramientas bajo el campo de texto. 4. **Pide**: «Diseña la tarjeta de fidelidad de mi cafetería, Le Petit Zinc, 8 cafés comprados, el 9.º gratis.» Claude llama a [`concevoir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/) y te enseña la tarjeta. 5. **Para tus cifras y tus clientes**, Claude te propone iniciar sesión: se abre la página de StampyWallet, eliges el comercio y autorizas el acceso. En un plan de equipo, añadir un conector personalizado puede estar reservado a los administradores de la organización. ## Con el skill Añade también el [skill «tarjetas bonitas»](https://stampywallet.com/es/docs/skill/): Claude buscará las fotos reales del comercio y propondrá al menos doce versiones de la tarjeta, de todos los tipos. ## Ejemplos de peticiones - «¿Cuántos clientes han venido este mes, y es mejor que el mes pasado?» ([`tableau_de_bord`](https://stampywallet.com/es/docs/mcp/herramientas/tableau_de_bord/)) - «¿Quiénes son mis clientes habituales que ya no vienen?» ([`chercher_clients`](https://stampywallet.com/es/docs/mcp/herramientas/chercher_clients/)) - «Avisa a todos mis clientes de que cierro del 24 al 31 de diciembre.» ([`fermetures`](https://stampywallet.com/es/docs/mcp/herramientas/fermetures/)) - «Pasa mi tarjeta a niveles: un café a las 5, un cruasán a las 10.» ([`modifier_carte`](https://stampywallet.com/es/docs/mcp/herramientas/modifier_carte/)) Source : https://stampywallet.com/es/docs/mcp/claude/ --- # Conectar ChatGPT Añadir el servidor MCP de StampyWallet como conector en ChatGPT y luego conectar tu cuenta de StampyWallet. 1. **Abre ChatGPT en la web** y luego **Configuración › Aplicaciones y conectores**. 2. **Activa el modo desarrollador** en la configuración avanzada (según tu plan, puede estar reservado a los administradores del espacio de trabajo). 3. **Crea un conector.** Nombre: `StampyWallet`. Dirección del servidor MCP: `https://app.stampywallet.com/mcp`. Autenticación: OAuth. 4. **En una conversación**, añade StampyWallet desde el menú «+» y pide: «Diseña la tarjeta de fidelidad de mi panadería.» 5. **Para tus cifras y tus clientes**, ChatGPT muestra **Iniciar sesión**: se abre la página de StampyWallet, eliges el comercio y autorizas el acceso. > **Nota :** en ChatGPT, algunas herramientas se muestran con una pantalla propia (la tarjeta generada, las cifras). Las mismas herramientas funcionan en cualquier otro sitio en texto y en datos. ## En un Proyecto de ChatGPT Pega el contenido del [skill.md](https://stampywallet.com/es/docs/skill/) en las instrucciones de un Proyecto: cada conversación del proyecto seguirá el método de las tarjetas bonitas. Source : https://stampywallet.com/es/docs/mcp/chatgpt/ --- # Conectar Cursor y los agentes Declarar el servidor MCP de StampyWallet en Cursor, Claude Code, VS Code o cualquier agente compatible con MCP. Cualquier cliente MCP que hable HTTP «streamable» se conecta con la misma dirección: `https://app.stampywallet.com/mcp`. La conexión a la cuenta pasa por OAuth (registro dinámico, PKCE): el cliente abre la página de StampyWallet en tu navegador con la primera herramienta que lo necesite. **Cursor** En **Cursor Settings › MCP › Add new MCP server**, o en el archivo del proyecto: ```json title=".cursor/mcp.json" { "mcpServers": { "stampywallet": { "url": "https://app.stampywallet.com/mcp" } } } ``` **Claude Code** ```bash title="Terminal" claude mcp add --transport http stampywallet https://app.stampywallet.com/mcp ``` Después, `/mcp` en Claude Code para conectarte a tu cuenta. **VS Code** ```json title=".vscode/mcp.json" { "servers": { "stampywallet": { "type": "http", "url": "https://app.stampywallet.com/mcp" } } } ``` **Otro agente** Declara un servidor MCP remoto de tipo HTTP en la dirección `https://app.stampywallet.com/mcp`. Los metadatos OAuth se publican en `https://app.stampywallet.com/.well-known/oauth-protected-resource`. ## Un agente que diseña tarjetas Dale al agente la dirección directa del skill, `https://stampywallet.com/es/docs/skill.md`, y pide: «Lee este skill y luego diseña las tarjetas de fidelidad de este comercio: [nombre, ciudad, enlace de Instagram].» Consulta [skill.md](https://stampywallet.com/es/docs/skill/). Source : https://stampywallet.com/es/docs/mcp/cursor/ --- # concevoir_carte Sin cuenta · Solo lectura. Diseña una tarjeta de fidelidad de StampyWallet (Apple Wallet y Google Wallet) para un comercio, sin cuenta y sin guardar nada. Úsala cuando alguien quiera una tarjeta de fidelidad, fidelizar a sus clientes o ver cómo sería su tarjeta. Todos los parámetros son opcionales: sin ellos, se propone una tarjeta adaptada al sector. El logo (logo_url) y la foto de cada recompensa (paliers[].image_url) se pasan por su dirección https; se muestran en la vista previa, sin guardarse. Vuelve a llamar a la herramienta con los ajustes devueltos, modificados, para afinar. Cuando la persona esté satisfecha, propón creer_commerce con los mismos ajustes. ## Parámetros - `nom` (string, ≤ 80 caracteres, opcional) : Nombre del comercio, impreso en la parte superior de la tarjeta. - `metier` (enum, opcional) : Tipo de comercio. Elige un estilo, un sello y una recompensa inicial adaptados cuando no se indican. «autre»: centros de estética, uñas, floristerías, peluquerías, tiendas de alimentación… Valores : cafe, boulangerie, restaurant, autre. - `mode` (enum, opcional) : tampons: una recompensa en un umbral (lo más sencillo). paliers: varias recompensas en la misma tarjeta (p. ej. 5 y 10). points: el comerciante introduce un número de puntos en cada visita (tickets variables). Valores : tampons, paliers, points. - `recompense` (string, ≤ 120 caracteres, opcional) : La recompensa (modo tampons). Se ignora si se indica «paliers». - `tampons` (integer, 2…30, opcional) : Número de visitas para conseguir la recompensa (modo tampons), de 2 a 30. - `paliers` (array, ≤ 6, opcional) : Las recompensas y sus umbrales (modos paliers y points). De menor a mayor. - `paliers[].a` (integer, 1…1000000, obligatorio) : Umbral: número de sellos (o de puntos en modo points) para conseguir este nivel. - `paliers[].recompense` (string, ≤ 120 caracteres, obligatorio) : Lo que recibe el cliente, tal como se imprime en la tarjeta. P. ej. «Un café gratis». - `paliers[].icone` (enum, opcional) : Icono del nivel (por defecto: cadeau). Valores : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `paliers[].image_url` (string, ≤ 2000 caracteres, opcional) : Foto de la recompensa, por su dirección https (PNG, JPEG o WebP, 5 MB como máximo, 64 px de lado como mínimo). Recortada cuando es posible, ocupa el lugar del icono en la tarjeta: en gris antes de ganarla y en color después. Se dibuja en los modos paliers y points. - `collection` (enum, opcional) : Estilo de la tarjeta: original (sobrio), cafe (marco fino), botanique (cursiva, follaje), trattoria (festoneado), atelier (moderno), pass (como un pase de Apple Wallet: logo en grande, sellos como objetos con sombra, fondo liso). Valores : original, cafe, botanique, trattoria, atelier, pass. - `palette` (integer, 0…3, opcional) : Paleta de la colección: 0, 1 o 2 (cada colección propone tres; pass propone una cuarta, 3). Se ignora si se indica «couleur». - `couleur` (string, opcional) : Color de fondo libre, en hexadecimal. La tinta (texto) se elige automáticamente para que siga siendo legible. - `tampon` (enum, opcional) : El signo que se pone en cada visita. «rond»: el punto simple. Belleza: etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Comida: cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Varios: feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valores : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `tampons_bienvenue` (integer, 0…5, opcional) : Sellos de regalo al registrarse el cliente (0 a 5). 1 por defecto: una tarjeta empezada da ganas de terminarla. - `nom_des_points` (string, ≤ 20 caracteres, opcional) : Modo points: cómo se llaman los puntos («puntos», «semillas», «estrellas»…). - `forme_paliers` (enum, opcional) : Modo paliers: el dibujo de la tarjeta. tampons (por defecto): los sellos en cuadrícula, cada recompensa en el lugar del sello de su umbral. O una de las cinco formas de los puntos, que entonces cuenta sellos: medailles (una barra y una medalla por recompensa), vitrine (las recompensas una al lado de otra, cada una con su barra), remplissage (la próxima recompensa en grande, que se va coloreando), chemin (una ruta en S en la que cada sello hace avanzar el cursor), anneau (una barra circular alrededor de la próxima recompensa). Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : tampons, medailles, vitrine, remplissage, chemin, anneau. - `forme_points` (enum, opcional) : Modo points: el dibujo de la tarjeta. medailles (por defecto): una barra gruesa y una medalla grande por recompensa. vitrine: las recompensas una al lado de otra, cada una con su barra pequeña. remplissage: la próxima recompensa en grande, que se va coloreando. chemin: una ruta en S, con las recompensas como etapas. anneau: una barra circular alrededor de la próxima recompensa, con la lista al lado. Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : medailles, vitrine, remplissage, chemin, anneau. - `forme` (enum, opcional) : El dibujo de la tarjeta, en una palabra (sustituye a forme_points y forme_paliers). Modos points y paliers: medailles (una barra y una medalla grande por recompensa), vitrine (las recompensas una al lado de otra, cada una con su barra), remplissage (la próxima recompensa en grande, que se va coloreando), chemin (una ruta en S, cada visita hace avanzar el cursor), anneau (una barra circular alrededor de la próxima recompensa). Modos tampons y paliers: la disposición de los sellos, grille (por defecto), libre (dispersos), objets (grandes objetos con sombra, ideal con una foto), cercles. En paliers, una disposición mantiene los sellos y pone cada recompensa en el lugar del sello de su umbral. Una de las cinco formas sin modo indicado pasa la tarjeta a modo paliers. Valores : medailles, vitrine, remplissage, chemin, anneau, grille, libre, objets, cercles. - `encre` (string, opcional) : Color del texto de la tarjeta, en hexadecimal (por defecto: elegido para que se lea bien sobre el fondo). - `accent` (string, opcional) : Color de acento: los sellos puestos, las barras, las etiquetas, en hexadecimal (por defecto: el de la colección). - `logo_url` (string, ≤ 2000 caracteres, opcional) : Logo del comercio, por su dirección https (PNG, JPEG o WebP, 5 MB como máximo): su foto de perfil de Instagram sirve. Recortado cuando es posible, se coloca en la parte superior de la tarjeta; si no se indican couleur, palette, encre ni accent, la tarjeta toma los colores del logo. - `variantes` (boolean, opcional) : true: genera también las tres paletas de la colección elegida, para proponer una elección. Por defecto : false. - `tampons_poses` (integer, 0…1000000, opcional) : Sellos ya puestos en la vista previa, para enseñar una tarjeta empezada (por defecto: sellos de bienvenida + 2). ## Ejemplo Prompt : « Diseña la tarjeta de fidelidad de la Boulangerie Lemaire: 10 visitas, la 10.ª baguette gratis, estilo pase, con su logo. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "concevoir_carte", "arguments": { "nom": "Boulangerie Lemaire", "metier": "boulangerie", "mode": "tampons", "tampons": 10, "recompense": "La 10.ª baguette gratis", "collection": "pass", "logo_url": "https://example.com/logo-lemaire.png", "variantes": true } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/ --- # simuler_fidelite Sin cuenta · Solo lectura. Estima lo que cuesta una tarjeta de fidelidad de sellos (la recompensa en relación con el ticket) y cuántas visitas de más la hacen rentable. Úsala para elegir una recompensa y un número de visitas, o cuando alguien se pregunta si una tarjeta merece la pena. Sin cuenta. ## Parámetros - `panier_moyen` (number, 0.5…10000, obligatorio) : Gasto medio de un cliente por visita, en euros. - `cout_recompense` (number, 0…10000, obligatorio) : Lo que cuesta la recompensa AL COMERCIANTE (precio de coste, no precio de venta), en euros. - `tampons` (integer, 2…30, obligatorio) : Visitas para conseguir la recompensa. - `tampons_bienvenue` (integer, 0…5, opcional) : Sellos de regalo al registrarse. Por defecto : 1. - `marge` (number, 1…100, opcional) : Margen bruto sobre un ticket, en porcentaje (por defecto 65 %, típico en hostelería y servicios). Por defecto : 65. - `clients_fideles` (integer, 1…100000, opcional) : Clientes que cogerían la tarjeta cada mes (por defecto 60). Por defecto : 60. - `visites_par_mois` (number, 0.1…60, opcional) : Visitas al mes de un cliente fiel hoy (por defecto 2). Por defecto : 2. - `comparer` (array, ≤ 5, opcional) : Otros números de visitas que comparar (p. ej. [6, 10, 12]). ## Ejemplo Prompt : « Mi ticket medio es de 6 €, un café me cuesta 0,40 €. ¿Cuánto cuesta una tarjeta de 10 visitas, y es mejor con 8 o con 12? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "simuler_fidelite", "arguments": { "panier_moyen": 6, "cout_recompense": 0.4, "tampons": 10, "comparer": [ 8, 12 ] } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/simuler_fidelite/ --- # creer_commerce Sin cuenta · Escribe (confirmar). Crea el comercio en StampyWallet con la tarjeta diseñada (mismos parámetros que concevoir_carte) y devuelve un enlace personal para convertirse en su propietario: la persona hace clic, inicia sesión con su correo y lo encuentra todo listo (tarjeta, QR para imprimir, prueba gratuita). El logo (logo_url) y la foto de cada recompensa (paliers[].image_url), pasados por su dirección https, se colocan en la tarjeta. Sin cuenta. Llámala primero con confirmer=false para enseñar el resumen, y luego con confirmer=true cuando la persona haya dicho que sí. ## Parámetros - `nom` (string, ≤ 80 caracteres, obligatorio) : Nombre del comercio, impreso en la parte superior de la tarjeta. - `metier` (enum, opcional) : Tipo de comercio. Elige un estilo, un sello y una recompensa inicial adaptados cuando no se indican. «autre»: centros de estética, uñas, floristerías, peluquerías, tiendas de alimentación… Valores : cafe, boulangerie, restaurant, autre. - `mode` (enum, opcional) : tampons: una recompensa en un umbral (lo más sencillo). paliers: varias recompensas en la misma tarjeta (p. ej. 5 y 10). points: el comerciante introduce un número de puntos en cada visita (tickets variables). Valores : tampons, paliers, points. - `recompense` (string, ≤ 120 caracteres, opcional) : La recompensa (modo tampons). Se ignora si se indica «paliers». - `tampons` (integer, 2…30, opcional) : Número de visitas para conseguir la recompensa (modo tampons), de 2 a 30. - `paliers` (array, ≤ 6, opcional) : Las recompensas y sus umbrales (modos paliers y points). De menor a mayor. - `paliers[].a` (integer, 1…1000000, obligatorio) : Umbral: número de sellos (o de puntos en modo points) para conseguir este nivel. - `paliers[].recompense` (string, ≤ 120 caracteres, obligatorio) : Lo que recibe el cliente, tal como se imprime en la tarjeta. P. ej. «Un café gratis». - `paliers[].icone` (enum, opcional) : Icono del nivel (por defecto: cadeau). Valores : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `paliers[].image_url` (string, ≤ 2000 caracteres, opcional) : Foto de la recompensa, por su dirección https (PNG, JPEG o WebP, 5 MB como máximo, 64 px de lado como mínimo). Recortada cuando es posible, ocupa el lugar del icono en la tarjeta: en gris antes de ganarla y en color después. Se dibuja en los modos paliers y points. - `collection` (enum, opcional) : Estilo de la tarjeta: original (sobrio), cafe (marco fino), botanique (cursiva, follaje), trattoria (festoneado), atelier (moderno), pass (como un pase de Apple Wallet: logo en grande, sellos como objetos con sombra, fondo liso). Valores : original, cafe, botanique, trattoria, atelier, pass. - `palette` (integer, 0…3, opcional) : Paleta de la colección: 0, 1 o 2 (cada colección propone tres; pass propone una cuarta, 3). Se ignora si se indica «couleur». - `couleur` (string, opcional) : Color de fondo libre, en hexadecimal. La tinta (texto) se elige automáticamente para que siga siendo legible. - `tampon` (enum, opcional) : El signo que se pone en cada visita. «rond»: el punto simple. Belleza: etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Comida: cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Varios: feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valores : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `tampons_bienvenue` (integer, 0…5, opcional) : Sellos de regalo al registrarse el cliente (0 a 5). 1 por defecto: una tarjeta empezada da ganas de terminarla. - `nom_des_points` (string, ≤ 20 caracteres, opcional) : Modo points: cómo se llaman los puntos («puntos», «semillas», «estrellas»…). - `forme_paliers` (enum, opcional) : Modo paliers: el dibujo de la tarjeta. tampons (por defecto): los sellos en cuadrícula, cada recompensa en el lugar del sello de su umbral. O una de las cinco formas de los puntos, que entonces cuenta sellos: medailles (una barra y una medalla por recompensa), vitrine (las recompensas una al lado de otra, cada una con su barra), remplissage (la próxima recompensa en grande, que se va coloreando), chemin (una ruta en S en la que cada sello hace avanzar el cursor), anneau (una barra circular alrededor de la próxima recompensa). Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : tampons, medailles, vitrine, remplissage, chemin, anneau. - `forme_points` (enum, opcional) : Modo points: el dibujo de la tarjeta. medailles (por defecto): una barra gruesa y una medalla grande por recompensa. vitrine: las recompensas una al lado de otra, cada una con su barra pequeña. remplissage: la próxima recompensa en grande, que se va coloreando. chemin: una ruta en S, con las recompensas como etapas. anneau: una barra circular alrededor de la próxima recompensa, con la lista al lado. Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : medailles, vitrine, remplissage, chemin, anneau. - `forme` (enum, opcional) : El dibujo de la tarjeta, en una palabra (sustituye a forme_points y forme_paliers). Modos points y paliers: medailles (una barra y una medalla grande por recompensa), vitrine (las recompensas una al lado de otra, cada una con su barra), remplissage (la próxima recompensa en grande, que se va coloreando), chemin (una ruta en S, cada visita hace avanzar el cursor), anneau (una barra circular alrededor de la próxima recompensa). Modos tampons y paliers: la disposición de los sellos, grille (por defecto), libre (dispersos), objets (grandes objetos con sombra, ideal con una foto), cercles. En paliers, una disposición mantiene los sellos y pone cada recompensa en el lugar del sello de su umbral. Una de las cinco formas sin modo indicado pasa la tarjeta a modo paliers. Valores : medailles, vitrine, remplissage, chemin, anneau, grille, libre, objets, cercles. - `encre` (string, opcional) : Color del texto de la tarjeta, en hexadecimal (por defecto: elegido para que se lea bien sobre el fondo). - `accent` (string, opcional) : Color de acento: los sellos puestos, las barras, las etiquetas, en hexadecimal (por defecto: el de la colección). - `logo_url` (string, ≤ 2000 caracteres, opcional) : Logo del comercio, por su dirección https (PNG, JPEG o WebP, 5 MB como máximo): su foto de perfil de Instagram sirve. Recortado cuando es posible, se coloca en la parte superior de la tarjeta; si no se indican couleur, palette, encre ni accent, la tarjeta toma los colores del logo. - `panier_moyen` (number, 0.5…10000, opcional) : Gasto medio de un cliente, en euros (sirve para las estimaciones del panel). - `langue` (enum, opcional) : Idioma de los textos devueltos. Por defecto, el del comercio. Valores : fr, en, es. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Es perfecta, pon en marcha esta tarjeta para la Boulangerie Lemaire. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "creer_commerce", "arguments": { "nom": "Boulangerie Lemaire", "metier": "boulangerie", "mode": "tampons", "tampons": 10, "recompense": "La 10.ª baguette gratis", "collection": "pass", "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/creer_commerce/ --- # tableau_de_bord Con cuenta · Solo lectura. Las cifras de fidelidad del comercio en el periodo que elijas: visitas en caja, clientes que han venido, clientes nuevos, tasa de retorno, recompensas ganadas y entregadas, facturación estimada, con una curva por día, semana o mes y, si hace falta, la comparación con el periodo anterior de la misma duración. Úsala para «¿cómo va este mes?», «¿cuántos clientes en agosto?», «¿va subiendo?». Para la lista de clientes, usa chercher_clients; para saber si la tarjeta es rentable, rentabilite. ## Parámetros - `periode` (enum, opcional) : Periodo analizado, en días de la zona horaria del comercio, con hoy incluido en los periodos en curso (ce_mois = del día 1 a hoy). «personnalisee» usa du/au. Por defecto derniers_30_jours. Valores : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Por defecto : "derniers_30_jours". - `du` (string (date), opcional) : Primer día incluido (AAAA-MM-DD). Basta con indicarlo: el periodo pasa a «personnalisee». - `au` (string (date), opcional) : Último día incluido (AAAA-MM-DD). Por defecto: hoy. - `comparer` (boolean, opcional) : Añade la variación respecto al periodo de la misma duración justo anterior (p. ej. los 30 días anteriores a los últimos 30 días). Por defecto : true. - `indicateurs` (array, ≤ 9, opcional) : Indicadores que devolver, en este orden. Por defecto: todos. taux_retour = parte de los clientes que vinieron en el periodo y que ya habían venido antes; chiffre_estime = visitas × ticket medio declarado (una estimación, no una caja). Valores : passages, clients_venus, nouveaux_clients, taux_retour, passages_par_client, recompenses_gagnees, recompenses_offertes, chiffre_estime, total_clients. - `courbe` (enum, opcional) : Lo que traza la curva. Por defecto passages. Valores : passages, clients_venus, nouveaux_clients, recompenses_gagnees, recompenses_offertes, aucune. Por defecto : "passages". - `granularite` (enum, opcional) : Paso de la curva. auto (por defecto): día hasta 2 meses, semana hasta ~9 meses, mes a partir de ahí. Valores : auto, jour, semaine, mois. Por defecto : "auto". ## Ejemplo Prompt : « ¿Cómo va este mes, comparado con el mes pasado? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "tableau_de_bord", "arguments": { "periode": "ce_mois", "comparer": true } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/tableau_de_bord/ --- # rentabilite Con cuenta · Solo lectura · Plan Crecimiento. Dice si la tarjeta de fidelidad es rentable, en el periodo que elijas: parte de los clientes que vuelven, visitas de vuelta y lo que representan en euros (estimación: visitas × ticket medio), ritmo mediano entre dos visitas, recompensas entregadas y su coste si se indica, recompensas pendientes de entregar y resultado del recordatorio automático. El ticket medio y el coste de una recompensa se pueden ajustar para rehacer el cálculo. Úsala para «¿merece la pena?», «¿cuánto me aporta?», «¿vuelven mis clientes?». Para las cifras brutas de un periodo, tableau_de_bord. ## Parámetros - `periode` (enum, opcional) : Periodo analizado, en días de la zona horaria del comercio, con hoy incluido en los periodos en curso (ce_mois = del día 1 a hoy). «personnalisee» usa du/au. Por defecto derniers_90_jours. Valores : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Por defecto : "derniers_90_jours". - `du` (string (date), opcional) : Primer día incluido (AAAA-MM-DD). Basta con indicarlo: el periodo pasa a «personnalisee». - `au` (string (date), opcional) : Último día incluido (AAAA-MM-DD). Por defecto: hoy. - `panier_moyen` (number, 0.1…10000, opcional) : Ticket medio en euros para este cálculo. Por defecto: el declarado en los ajustes del comercio. - `cout_recompense` (number, 0…10000, opcional) : Lo que cuesta UNA recompensa al comerciante (precio de coste), en euros. Sin él, el coste de las recompensas no se calcula. - `comparer` (boolean, opcional) : Añade el periodo de la misma duración justo anterior, para ver si mejora. Por defecto : false. ## Ejemplo Prompt : « ¿Es rentable mi tarjeta de fidelidad? Una recompensa me cuesta 1,20 €. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "rentabilite", "arguments": { "periode": "derniers_90_jours", "cout_recompense": 1.2 } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/rentabilite/ --- # meilleurs_moments Con cuenta · Solo lectura · Plan Crecimiento. Muestra cuándo vienen los clientes: media de visitas por día de la semana, reparto por hora o las franjas (día + hora) con más afluencia, en el periodo que elijas y en la hora local del comercio. También puede contar las altas de clientes nuevos. Úsala para «¿cuál es mi mejor día?», «¿a qué hora tengo más gente?», «¿cuándo lanzar una oferta para llenar un hueco?». ## Parámetros - `par` (enum, opcional) : jour_semaine (por defecto): media por lunes, martes…; heure: total por hora del día; creneau: las combinaciones día + hora con más afluencia. Valores : jour_semaine, heure, creneau. Por defecto : "jour_semaine". - `mesure` (enum, opcional) : passages (por defecto) o nouveaux_clients (altas en la tarjeta). Valores : passages, nouveaux_clients. Por defecto : "passages". - `jours` (array, ≤ 7, opcional) : Para par=heure o creneau: quedarse solo con estos días de la semana (p. ej. ["samedi"]). Valores : lundi, mardi, mercredi, jeudi, vendredi, samedi, dimanche. - `periode` (enum, opcional) : Periodo analizado, en días de la zona horaria del comercio, con hoy incluido en los periodos en curso (ce_mois = del día 1 a hoy). «personnalisee» usa du/au. Por defecto derniers_90_jours. Valores : aujourdhui, hier, derniers_7_jours, derniers_30_jours, derniers_90_jours, derniers_12_mois, cette_semaine, semaine_derniere, ce_mois, mois_dernier, cette_annee, annee_derniere, depuis_le_debut, personnalisee. Por defecto : "derniers_90_jours". - `du` (string (date), opcional) : Primer día incluido (AAAA-MM-DD). Basta con indicarlo: el periodo pasa a «personnalisee». - `au` (string (date), opcional) : Último día incluido (AAAA-MM-DD). Por defecto: hoy. - `limite` (integer, 1…50, opcional) : Para par=creneau: número de franjas devueltas (por defecto 10). Por defecto : 10. ## Ejemplo Prompt : « ¿A qué hora tengo más gente los sábados? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "meilleurs_moments", "arguments": { "par": "heure", "jours": [ "samedi" ] } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/meilleurs_moments/ --- # chercher_clients Con cuenta · Solo lectura. Lista los clientes del comercio según un segmento (habituales, perdidos de vista, a un sello de la recompensa, recompensa por entregar, nuevos, inactivos, que nunca han vuelto) combinado con filtros: nombre, sellos en la tarjeta, número de visitas, fecha de registro, fecha de última visita, tipo de wallet; ordenados y paginados. Devuelve para cada uno un identificador, el nombre y la inicial del apellido, las visitas, la última visita y el estado de la tarjeta, nunca correo ni teléfono. Úsala para «¿quiénes son mis mejores clientes?», «¿quién no ha vuelto?», «¿quién está cerca de su recompensa?», o para encontrar el identificador de un cliente antes de fiche_client. ## Parámetros - `segment` (enum, opcional) : Grupo de partida, definido como en la aplicación. tous (por defecto); habitues = al menos 4 visitas en los últimos 60 días; perdus = han venido al menos 4 veces y faltan desde hace más de una vez y media su ritmo habitual (mediana de los intervalos entre sus visitas) o, sin historial suficiente, desde hace más que el plazo del comercio; vacaciones y días de cierre no cuentan; presque = solo les falta un sello para la recompensa; recompense_prete = una recompensa ganada, aún no entregada y no caducada; nouveaux = registrados en los últimos 30 días; inactifs = ninguna visita desde hace más que el plazo del comercio, en días naturales, sea cual sea su número de visitas; un_seul_passage = una visita como máximo: registrados pero nunca han vuelto. Valores : tous, habitues, perdus, presque, recompense_prete, nouveaux, inactifs, un_seul_passage. Por defecto : "tous". - `recherche` (string, ≤ 60 caracteres, opcional) : Fragmento del nombre o del apellido (se ignoran acentos y mayúsculas). - `tampons_min` (integer, ≥ 0, opcional) : Sellos como mínimo en la tarjeta actual. - `tampons_max` (integer, ≥ 0, opcional) : Sellos como máximo en la tarjeta actual. - `visites_min` (integer, ≥ 0, opcional) : Visitas como mínimo desde el registro (sin contar los sellos de bienvenida). - `visites_max` (integer, ≥ 0, opcional) : Visitas como máximo desde el registro. - `inactif_depuis_jours` (integer, 1…3650, opcional) : Ninguna visita desde hace al menos N días naturales (un cliente que nunca ha venido cuenta desde su registro). - `actif_depuis_jours` (integer, 1…3650, opcional) : Al menos una visita en los últimos N días. - `inscrit_depuis` (string (date), opcional) : Registrado ese día o después (AAAA-MM-DD). - `inscrit_avant` (string (date), opcional) : Registrado ese día o antes (AAAA-MM-DD). - `derniere_visite_depuis` (string (date), opcional) : Última visita ese día o después (AAAA-MM-DD). - `derniere_visite_avant` (string (date), opcional) : Última visita ese día o antes (AAAA-MM-DD). Excluye a quienes nunca han venido. - `wallet` (enum, opcional) : Dónde guarda el cliente su tarjeta. aucun = página web, sin wallet. Valores : tous, apple, google, aucun. Por defecto : "tous". - `tri` (enum, opcional) : Orden de los resultados. Por defecto derniere_visite (los más recientes primero). Valores : derniere_visite, visites, visites_90j, tampons, recompenses, inscription, prenom. Por defecto : "derniere_visite". - `ordre` (enum, opcional) : auto (por defecto): descendente, salvo prenom (A→Z). Valores : auto, asc, desc. Por defecto : "auto". - `limite` (integer, 1…100, opcional) : Número máximo de resultados. Por defecto : 25. - `decalage` (integer, ≥ 0, opcional) : Número de resultados que saltar (paginación). Por defecto : 0. ## Ejemplo Prompt : « ¿Quiénes son mis clientes habituales que ya no vienen? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "chercher_clients", "arguments": { "segment": "perdus", "tri": "visites", "limite": 20 } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/chercher_clients/ --- # fiche_client Con cuenta · Solo lectura. El historial de UN cliente: fecha de registro, wallet usado, número de visitas y ritmo de visita, visitas mes a mes, tarjeta actual, recompensas ganadas, entregadas y por entregar, últimas visitas con fecha. Se busca por su identificador (dado por chercher_clients) o por su nombre, seguido si acaso de la inicial del apellido («Maëlle P.»); si coinciden varios clientes, se devuelve la lista de candidatos para elegir. Úsala para «¿cuándo vino Zoé por última vez?», «¿cuántas veces ha venido Louis?». No da ni correo ni teléfono. ## Parámetros - `id` (string, opcional) : Identificador del cliente (UUID), tal como lo devuelve chercher_clients. Tiene prioridad sobre prenom. - `prenom` (string, ≤ 60 caracteres, opcional) : Nombre del cliente, seguido si acaso de la inicial o del apellido («Maëlle P.»). Se ignoran acentos y mayúsculas. - `historique_limite` (integer, 0…200, opcional) : Número de visitas recientes que detallar (por defecto 15). Por defecto : 15. - `inclure_offerts` (boolean, opcional) : true: el historial muestra también los sellos regalados (bienvenida, reseña), marcados como tales. Por defecto false: solo las visitas reales. Por defecto : false. - `mois` (integer, 1…36, opcional) : Número de meses en la curva de visitas (por defecto 12). Por defecto : 12. ## Ejemplo Prompt : « ¿Cuándo vino Zoé por última vez? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "fiche_client", "arguments": { "prenom": "Zoé" } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/fiche_client/ --- # envoyer_message Con cuenta · Escribe (confirmar). Envía una notificación a la pantalla de bloqueo de los clientes (a través de su tarjeta de Apple Wallet o Google Wallet). Úsala para anunciar una novedad, una oferta, un evento o hacer que vuelvan los clientes. La audiencia es configurable (todos, habituales, perdidos de vista, casi en la recompensa, nuevos, recompensa por recoger, inactivos) y se combina con filtros (días sin visita, sellos en la tarjeta, visitas, fecha de registro). Texto de 180 caracteres como máximo, enviado tal cual. Un solo mensaje al día por comercio. Llámala primero con confirmer=false: la vista previa da el texto exacto, el número de destinatarios y cuántos pueden recibirlo de verdad, sin enviar nada. Llámala con confirmer=true solo tras la aprobación explícita de la persona: un mensaje enviado no se puede recuperar. Para los mensajes automáticos (recordatorio, cumpleaños, avisos), usa regler_automatismes. ## Parámetros - `texte` (string, ≤ 180 caracteres, obligatorio) : El texto exacto de la notificación, 180 caracteres como máximo. En el móvil va precedido del nombre del comercio: no hace falta repetirlo. - `audience` (enum, opcional) : Quién recibe el mensaje. tous = todos los clientes; habitues = 4 visitas o más en 60 días; perdus = habituales cuya ausencia supera una vez y media su ritmo habitual, o el plazo del comercio si no hay historial suficiente (la definición de la pantalla Clientes); presque = solo falta un sello para la recompensa; nouveaux = registrados en los últimos 30 días (o desde inscrit_depuis); recompense_prete = una recompensa ganada, aún no recogida; inactifs = cualquier cliente sin visitas desde hace inactif_depuis_jours días de apertura (por defecto el plazo del comercio), habitual o no. Cualquier audiencia distinta de tous, o cualquier filtro, requiere la función «notificaciones segmentadas». Valores : tous, habitues, perdus, presque, nouveaux, recompense_prete, inactifs. Por defecto : "tous". - `inactif_depuis_jours` (integer, 1…730, opcional) : Filtro: sin visitas desde hace al menos N días de APERTURA (los días de cierre y las vacaciones no cuentan). - `actif_depuis_jours` (integer, 1…730, opcional) : Filtro: al menos una visita en los últimos N días de apertura. - `tampons_min` (integer, 0…500, opcional) : Filtro: al menos N sellos en la tarjeta actual. - `tampons_max` (integer, 0…500, opcional) : Filtro: como máximo N sellos en la tarjeta actual. - `passages_min` (integer, 1…10000, opcional) : Filtro: al menos N visitas en total desde el registro. - `inscrit_depuis` (string (date), opcional) : Filtro: registrados ese día o después (AAAA-MM-DD). - `inscrit_avant` (string (date), opcional) : Filtro: registrados antes de ese día (AAAA-MM-DD, excluido). - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Avisa a mis clientes que están casi en la recompensa de que este fin de semana hay cruasanes de almendra. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "envoyer_message", "arguments": { "texte": "Cruasanes de almendra este fin de semana: ¡solo te falta un sello para tu recompensa!", "audience": "presque", "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/envoyer_message/ --- # historique_messages Con cuenta · Solo lectura. Lista los mensajes ya enviados a los clientes, del más reciente al más antiguo, con su balance de entrega: recibidos, clientes sin pantalla (inalcanzables), fallos y aún en envío. También resume los mensajes automáticos enviados en el periodo (recordatorios a perdidos de vista, cumpleaños) e indica si todavía puede salir un mensaje hoy. Úsala para saber qué se ha enviado, comprobar que un envío ha llegado, o antes de escribir uno nuevo. ## Parámetros - `limite` (integer, 1…50, opcional) : Número máximo de resultados. Por defecto : 10. - `decalage` (integer, ≥ 0, opcional) : Número de resultados que saltar (paginación). Por defecto : 0. - `depuis` (string (date), opcional) : Solo los envíos a partir de ese día (AAAA-MM-DD). También sirve de inicio del periodo para el resumen de los automáticos (últimos 30 días por defecto). - `jusqu_au` (string (date), opcional) : Solo los envíos hasta ese día incluido (AAAA-MM-DD). ## Ejemplo Prompt : « ¿Qué he enviado a mis clientes este mes, y ha llegado bien? » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "historique_messages", "arguments": { "depuis": "2026-10-01" } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/historique_messages/ --- # regler_automatismes Con cuenta · Escribe (confirmar). Lee y ajusta los mensajes que StampyWallet envía solo a los clientes: el recordatorio a los habituales que ya no vienen (cuando su ausencia supera una vez y media su ritmo habitual o, sin historial suficiente, el plazo del comercio, propuesto según su sector y ajustable), el mensaje de cumpleaños, los avisos «solo falta un sello» y «recompensa lista» (y su retraso), las horas de silencio en las que no sale nada; muestra también el resumen del lunes enviado al comerciante. Sin parámetro de cambio: devuelve el estado actual, textos incluidos. Con cambios: confirmer=false devuelve una vista previa antes → después sin modificar nada, confirmer=true guarda. Solo cambian los campos indicados. Para un mensaje puntual, usa envoyer_message. ## Parámetros - `relance_active` (boolean, opcional) : Activa o desactiva el recordatorio automático a los perdidos de vista (uno por cliente y por ausencia). - `delai_relance_jours` (integer, opcional) : Plazo del comercio antes de que un habitual quede «perdido de vista», en días naturales: un valor entre 14, 21, 28, 35, 42, 60, 90. Sirve para los clientes sin historial suficiente y acota el ritmo de los demás (de la mitad al doble). Para volver al plazo propuesto para el sector, pon "delai_relance" en effacer. - `texte_relance` (string, ≤ 180 caracteres, opcional) : Texto del recordatorio, 180 caracteres como máximo. Para volver al texto por defecto, pon "texte_relance" en effacer. - `anniversaire_active` (boolean, opcional) : Activa o desactiva el mensaje de cumpleaños (solo sale si existe un texto y si la tarjeta pide la fecha de cumpleaños). - `cadeau_anniversaire` (enum, opcional) : El regalo de cumpleaños, válido 30 días a partir del día: message (solo el texto), pourcent (un descuento en cada compra), un_offert (2x1, una vez), choix (el cliente elige en el mostrador entre el descuento y el 2x1). Los regalos ya abiertos no cambian. Valores : message, pourcent, un_offert, choix. - `pourcent_anniversaire` (integer, 1…90, opcional) : El porcentaje del descuento de cumpleaños (pourcent y choix), de 1 a 90. - `texte_anniversaire` (string, ≤ 180 caracteres, opcional) : Texto del mensaje de cumpleaños, 180 caracteres como máximo, idealmente con el regalo incluido. Sin texto, no sale nada. - `rappel_presque` (boolean, opcional) : Recordatorio «solo falta un sello» cuando solo falta una visita. - `rappel_recompense` (boolean, opcional) : Recordatorio «tu recompensa te espera» cuando se ha ganado. - `delai_rappel_minutes` (integer, opcional) : Retraso entre la visita y el recordatorio, en minutos: un valor entre 0, 30, 60, 180, 1440 (1440 = al día siguiente). - `heures_calmes_debut` (integer, 0…23, opcional) : Inicio de las horas de silencio (hora de 0 a 23): a partir de ahí no llega ninguna notificación automática. - `heures_calmes_fin` (integer, 0…23, opcional) : Fin de las horas de silencio (hora de 0 a 23): los envíos se reanudan a partir de esa hora. - `canal_avis` (enum, opcional) : Canal de «solicitud de reseña»: auto (recomendado: un mensaje importante sale primero por SMS salvo a los clientes que responden a las notificaciones, uno menor por notificación y por SMS solo a los clientes que responden mejor a los SMS), notif, secours (SMS si la notificación no llega), sms (SMS primero), email (correo si la notificación no llega). Valores : auto, notif, secours, sms, email. - `importance_avis` (enum, opcional) : Importancia de «solicitud de reseña»: importante (pasa antes en el presupuesto de SMS) o petite (menor). Valores : importante, petite. - `canal_anniversaire` (enum, opcional) : Canal de «cumpleaños»: auto (recomendado: un mensaje importante sale primero por SMS salvo a los clientes que responden a las notificaciones, uno menor por notificación y por SMS solo a los clientes que responden mejor a los SMS), notif, secours (SMS si la notificación no llega), sms (SMS primero), email (correo si la notificación no llega). Valores : auto, notif, secours, sms, email. - `importance_anniversaire` (enum, opcional) : Importancia de «cumpleaños»: importante (pasa antes en el presupuesto de SMS) o petite (menor). Valores : importante, petite. - `canal_rappels` (enum, opcional) : Canal de «recordatorios»: auto (recomendado: un mensaje importante sale primero por SMS salvo a los clientes que responden a las notificaciones, uno menor por notificación y por SMS solo a los clientes que responden mejor a los SMS), notif, secours (SMS si la notificación no llega), sms (SMS primero). Valores : auto, notif, secours, sms. - `importance_rappels` (enum, opcional) : Importancia de «recordatorios»: importante (pasa antes en el presupuesto de SMS) o petite (menor). Valores : importante, petite. - `canal_relance` (enum, opcional) : Canal de «recordatorio a perdidos de vista»: auto (recomendado: un mensaje importante sale primero por SMS salvo a los clientes que responden a las notificaciones, uno menor por notificación y por SMS solo a los clientes que responden mejor a los SMS), notif, secours (SMS si la notificación no llega), sms (SMS primero). Valores : auto, notif, secours, sms. - `importance_relance` (enum, opcional) : Importancia de «recordatorio a perdidos de vista»: importante (pasa antes en el presupuesto de SMS) o petite (menor). Valores : importante, petite. - `canal_messages` (enum, opcional) : Canal de «mensajes del comerciante»: auto (recomendado: un mensaje importante sale primero por SMS salvo a los clientes que responden a las notificaciones, uno menor por notificación y por SMS solo a los clientes que responden mejor a los SMS), notif, secours (SMS si la notificación no llega), sms (SMS primero). Valores : auto, notif, secours, sms. - `importance_messages` (enum, opcional) : Importancia de «mensajes del comerciante»: importante (pasa antes en el presupuesto de SMS) o petite (menor). Valores : importante, petite. - `reserve_sms` (integer, 0…100, opcional) : Parte del presupuesto mensual de SMS reservada para los mensajes importantes, en %: 0, 25, 50, 75, 100. - `effacer` (array, opcional) : Textos que borrar. texte_relance vuelve al texto por defecto; texte_anniversaire vacío desactiva en la práctica los envíos de cumpleaños; delai_relance vuelve al plazo propuesto para el sector. Valores : texte_relance, texte_anniversaire, delai_relance. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Activa el mensaje de cumpleaños con un 10 % de descuento. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "regler_automatismes", "arguments": { "anniversaire_active": true, "cadeau_anniversaire": "pourcent", "pourcent_anniversaire": 10, "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/regler_automatismes/ --- # fermetures Con cuenta · Escribe (confirmar). Gestiona las vacaciones y los días de cierre del comercio: listar, añadir un periodo de vacaciones, eliminar uno o ajustar los días cerrados cada semana. Importante para la fidelidad: los días cerrados no cuentan en la ausencia de un cliente, así que unas vacaciones bien declaradas evitan que los habituales pasen por «perdidos de vista» y reciban un recordatorio a la vuelta. Opcionalmente, prevenir_clients=true con un texto prepara también una notificación a todos los clientes (mismas reglas que envoyer_message: un mensaje al día, vista previa obligatoria). action=lister (por defecto) no cambia nada. Para añadir, eliminar o ajustar los días: confirmer=false devuelve una vista previa, confirmer=true guarda (y envía el mensaje si se ha pedido). ## Parámetros - `action` (enum, opcional) : lister: vacaciones próximas y de los dos últimos meses, y días cerrados cada semana. ajouter: un periodo (du, au). supprimer: un periodo por su id (dado por lister). jours_hebdo: sustituye los días cerrados cada semana por jours_fermes. Valores : lister, ajouter, supprimer, jours_hebdo. Por defecto : "lister". - `du` (string (date), opcional) : Primer día cerrado (AAAA-MM-DD), para añadir. - `au` (string (date), opcional) : Último día cerrado, incluido (AAAA-MM-DD). Por defecto, el mismo día que du. - `libelle` (string, ≤ 80 caracteres, opcional) : Nombre del periodo, para orientarse («Vacaciones de verano»). - `id` (string, opcional) : Identificador del periodo que eliminar (dado por action=lister). - `jours_fermes` (array, ≤ 7, opcional) : Para jours_hebdo: la lista COMPLETA de días cerrados cada semana (lista vacía = abierto todos los días). Valores : dimanche, lundi, mardi, mercredi, jeudi, vendredi, samedi. - `prevenir_clients` (boolean, opcional) : true: envía también una notificación a todos los clientes con texte. Cuenta como el mensaje del día. Por defecto : false. - `texte` (string, ≤ 180 caracteres, opcional) : Texto de la notificación a los clientes (180 caracteres como máximo), si prevenir_clients=true. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Cierro del 24 al 31 de diciembre, avisa a mis clientes. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "fermetures", "arguments": { "action": "ajouter", "du": "2026-12-24", "au": "2026-12-31", "libelle": "Fiestas de fin de año", "prevenir_clients": true, "texte": "Cerramos del 24 al 31 de diciembre. ¡Felices fiestas y hasta muy pronto!", "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/fermetures/ --- # avis_google Con cuenta · Escribe (confirmar) · Plan Crecimiento. Las reseñas de Google del comercio. Cada cliente recibe la misma solicitud de reseña (notificación de Wallet, SMS o correo según el canal ajustado en regler_automatismes, canal_avis), con el enlace directo a la ficha de Google: sin nota intermedia, sin filtro y sin ninguna recompensa a cambio de una reseña (reglas de Google). Muestra las cifras de 30 días (solicitudes enviadas, clientes que han ido a Google); y ajusta la solicitud: enlace de la ficha de Google, solicitud activa o no, momento (primera recompensa o tras N visitas), retraso, texto. Sin cambios: solo lectura. Con cambios: confirmer=false devuelve una vista previa antes → después, confirmer=true guarda. Solo cambian los campos indicados. ## Parámetros - `lien` (string, ≤ 2000 caracteres, opcional) : Enlace «escribir una reseña» de la ficha de Google (g.page/r/…/review, search.google.com/local/writereview?placeid=…). Sin él, no sale ninguna solicitud. - `retirer_lien` (boolean, opcional) : true: quita el enlace de la ficha (desactiva en la práctica todas las solicitudes). - `demande_active` (boolean, opcional) : Enviar o no la solicitud de reseña a los clientes. - `moment` (enum, opcional) : Cuándo pedirla: recompense = con la primera recompensa; passages = tras N visitas (ver passages). Valores : recompense, passages. - `passages` (integer, 1…50, opcional) : Número de visitas antes de la solicitud, si moment=passages. - `delai_minutes` (integer, opcional) : Retraso entre la visita y la solicitud, en minutos: 0, 30, 60, 180, 1440 (1440 = al día siguiente). - `texte_demande` (string, ≤ 300 caracteres, opcional) : Texto de la solicitud, 300 caracteres como máximo. El enlace a la ficha de Google se añade después. - `effacer` (array, opcional) : Campos de texto que vaciar. texte_demande vuelve al texto por defecto. Valores : texte_demande. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Pide una reseña de Google tras la 3.ª visita, una hora después. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "avis_google", "arguments": { "demande_active": true, "moment": "passages", "passages": 3, "delai_minutes": 60, "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/avis_google/ --- # voir_carte Con cuenta · Solo lectura. Muestra la tarjeta de fidelidad del comercio tal como la ven los clientes en Apple Wallet y Google Wallet, con sus reglas actuales: modo (sellos, niveles o puntos), recompensas y umbrales, sellos de regalo al registrarse, caducidad de las recompensas, ajustes de los puntos, estilo, color, sello y el enlace público de registro de los clientes. Úsala antes de cualquier modificación (modifier_carte usa los mismos nombres de ajustes), o cuando el comerciante pregunte cómo es su tarjeta o cuál es su regla. Solo lectura. ## Parámetros - `variantes` (boolean, opcional) : true: muestra también las tres paletas de la colección actual, para proponer un cambio de color (que luego se pasa como «palette» a modifier_carte). Por defecto : false. - `tampons_poses` (integer, 0…1000000, opcional) : Sellos (o puntos) puestos en la vista previa, para enseñar una tarjeta empezada (por defecto: sellos de bienvenida + 2). - `qr` (boolean, opcional) : true: adjunta el QR de registro de los clientes (el del cartel), para probar la tarjeta en tu móvil. Por defecto : false. ## Ejemplo Prompt : « Enséñame mi tarjeta, con las otras paletas posibles. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "voir_carte", "arguments": { "variantes": true } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/voir_carte/ --- # modifier_carte Con cuenta · Escribe (confirmar). Cambia uno o varios ajustes de la tarjeta de fidelidad del comercio, en una sola llamada: nombre impreso, estilo (colección, paleta o color libre), sello, regla de recompensa (modo tampons/paliers/points, umbrales, recompensas), sellos de regalo al registrarse, caducidad de las recompensas, en modo paliers la forma de la tarjeta (forme_paliers: tampons o una de las cinco formas), y en modo points el nombre de los puntos, la forma de la tarjeta (forme_points), el valor por defecto de una visita, los atajos y los puntos por euro. Solo cambian los ajustes indicados; lee primero la tarjeta con voir_carte. Llámala con confirmer=false (por defecto) para enseñar el antes/después, y luego con confirmer=true tras la aprobación explícita. Un cambio de regla se aplica también a las tarjetas que ya tienen los clientes. Las imágenes (logo, fondo, sello en imagen) se cambian en la aplicación, página Tarjeta. ## Parámetros - `nom` (string, ≤ 80 caracteres, opcional) : Nombre del comercio, impreso en la parte superior de la tarjeta. - `mode` (enum, opcional) : tampons: una recompensa en un umbral (lo más sencillo). paliers: varias recompensas en la misma tarjeta (p. ej. 5 y 10). points: el comerciante introduce un número de puntos en cada visita (tickets variables). Valores : tampons, paliers, points. - `recompense` (string, ≤ 120 caracteres, opcional) : La recompensa (modo tampons). Se ignora si se indica «paliers». - `tampons` (integer, 2…30, opcional) : Número de visitas para conseguir la recompensa (modo tampons), de 2 a 30. - `paliers` (array, ≤ 6, opcional) : Las recompensas y sus umbrales (modos paliers y points). De menor a mayor. - `paliers[].a` (integer, 1…1000000, obligatorio) : Umbral: número de sellos (o de puntos en modo points) para conseguir este nivel. - `paliers[].recompense` (string, ≤ 120 caracteres, obligatorio) : Lo que recibe el cliente, tal como se imprime en la tarjeta. P. ej. «Un café gratis». - `paliers[].icone` (enum, opcional) : Icono del nivel (por defecto: cadeau). Valores : etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `collection` (enum, opcional) : Estilo de la tarjeta: original (sobrio), cafe (marco fino), botanique (cursiva, follaje), trattoria (festoneado), atelier (moderno), pass (como un pase de Apple Wallet: logo en grande, sellos como objetos con sombra, fondo liso). Valores : original, cafe, botanique, trattoria, atelier, pass. - `palette` (integer, 0…3, opcional) : Paleta de la colección: 0, 1 o 2 (cada colección propone tres; pass propone una cuarta, 3). Se ignora si se indica «couleur». - `couleur` (string, opcional) : Color de fondo libre, en hexadecimal. La tinta (texto) se elige automáticamente para que siga siendo legible. - `tampon` (enum, opcional) : El signo que se pone en cada visita. «rond»: el punto simple. Belleza: etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette. Comida: cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn. Varios: feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket. Valores : rond, etincelle, eclat, goutte, main, pinceau, oeil, ciseaux, sechoir, fleur, lotus, coeur, etoile, diamant, couronne, soleil, lune, talon, robe, sac, serviette, cafe, grain, the, cookie, gateau, pain, part, burger, glace, bol, plat, verre, biere, bulles, cocktail, cerises, orange, avocat, piment, oeuf, poisson, fromage, popcorn, feuille, flamme, eclair, sourire, patte, chien, chat, cadeau, haltere, velo, livre, note, appareil, palette, dent, parapluie, ballon, tshirt, basket, croissant. - `tampons_bienvenue` (integer, 0…5, opcional) : Sellos de regalo al registrarse el cliente (0 a 5). 1 por defecto: una tarjeta empezada da ganas de terminarla. - `nom_des_points` (string, ≤ 20 caracteres, opcional) : Modo points: cómo se llaman los puntos («puntos», «semillas», «estrellas»…). - `forme_paliers` (enum, opcional) : Modo paliers: el dibujo de la tarjeta. tampons (por defecto): los sellos en cuadrícula, cada recompensa en el lugar del sello de su umbral. O una de las cinco formas de los puntos, que entonces cuenta sellos: medailles (una barra y una medalla por recompensa), vitrine (las recompensas una al lado de otra, cada una con su barra), remplissage (la próxima recompensa en grande, que se va coloreando), chemin (una ruta en S en la que cada sello hace avanzar el cursor), anneau (una barra circular alrededor de la próxima recompensa). Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : tampons, medailles, vitrine, remplissage, chemin, anneau. - `forme_points` (enum, opcional) : Modo points: el dibujo de la tarjeta. medailles (por defecto): una barra gruesa y una medalla grande por recompensa. vitrine: las recompensas una al lado de otra, cada una con su barra pequeña. remplissage: la próxima recompensa en grande, que se va coloreando. chemin: una ruta en S, con las recompensas como etapas. anneau: una barra circular alrededor de la próxima recompensa, con la lista al lado. Las fotos de las recompensas se suben en la aplicación, página Tarjeta. Valores : medailles, vitrine, remplissage, chemin, anneau. - `expiration_recompense_jours` (integer, 0…365, opcional) : Días durante los que una recompensa ganada sigue siendo válida: 0, 30, 60, 90, 180, 365 (0 = no caduca). - `points_par_defaut` (integer, 1…100000, opcional) : Modo points: puntos que se ponen por defecto en cada visita (1 a 100 000). - `points_raccourcis` (array, ≤ 12, opcional) : Modo points: los valores propuestos con un gesto al escanear (hasta 6, ordenados y sin duplicados). P. ej. [1, 2, 5, 10]. - `points_par_euro` (number, 0.01…10000, opcional) : Modo points: puntos por euro gastado, referencia mostrada al comerciante (p. ej. 1 o 0,5). - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Pasa mi tarjeta a niveles: un café a las 5 visitas, un cruasán a las 10. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "modifier_carte", "arguments": { "mode": "paliers", "paliers": [ { "a": 5, "recompense": "Un café gratis", "icone": "cafe" }, { "a": 10, "recompense": "Un cruasán gratis", "icone": "croissant" } ], "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/modifier_carte/ --- # fiche_commerce Con cuenta · Escribe (confirmar). Lee o modifica la ficha del comercio: nombre, tipo de comercio, ticket medio (sirve para las estimaciones del panel), idioma de los clientes, datos de contacto impresos en el reverso de la tarjeta (dirección, teléfono, horario, sitio web, mensaje de bienvenida) y enlace público de registro de los clientes (stampywallet.com/rejoindre/, el del QR). Sin parámetro de cambio: devuelve la ficha actual. Con cambios: confirmer=false (por defecto) muestra el antes/después, confirmer=true escribe tras la aprobación explícita. Un enlace público antiguo sigue funcionando tras un cambio (los QR ya impresos siguen sirviendo). ## Parámetros - `nom` (string, ≤ 80 caracteres, opcional) : Nombre del comercio (también impreso en la tarjeta). - `metier` (enum, opcional) : Tipo de comercio. «autre»: centros de estética, uñas, floristerías, peluquerías, tiendas de alimentación… Valores : cafe, boulangerie, restaurant, autre. - `panier_moyen` (number, 0.01…100000, opcional) : Gasto medio de un cliente por visita, en euros. - `langue` (enum, opcional) : Idioma del comercio: el de la tarjeta, las páginas y los mensajes que ven los clientes. Valores : fr, en, es. - `adresse` (string, ≤ 160 caracteres, opcional) : Dirección, en el reverso de la tarjeta (160 caracteres como máximo). - `telephone` (string, ≤ 30 caracteres, opcional) : Teléfono, en el reverso de la tarjeta. - `horaires` (string, ≤ 120 caracteres, opcional) : Horario de apertura, en texto libre (p. ej. «Mar–sáb 7:00–19:00»). - `site_web` (string, ≤ 160 caracteres, opcional) : Sitio web o página de Instagram. - `message_bienvenue` (string, ≤ 180 caracteres, opcional) : Nota en el reverso de la tarjeta, que el cliente lee al añadirla. - `lien` (string, ≤ 120 caracteres, opcional) : Enlace público deseado, legible («Le Fournil de la Gare» se convierte en «le-fournil-de-la-gare»), de 3 a 32 caracteres. Un enlace ya usado por otro comercio se rechaza. - `effacer` (array, ≤ 6, opcional) : Campos que vaciar. «lien»: la dirección pública vuelve a ser el identificador técnico (el enlace sigue reservado a este comercio). Valores : adresse, telephone, horaires, site_web, message_bienvenue, lien. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Añade mi horario al reverso de la tarjeta: de martes a sábado, de 7:00 a 19:00. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "fiche_commerce", "arguments": { "horaires": "Mar–sáb 7:00–19:00", "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/fiche_commerce/ --- # affichette Con cuenta · Solo lectura. Devuelve el código QR de registro de los clientes (el que se pone en el mostrador y que los clientes escanean para añadir la tarjeta a su móvil), el enlace público, la tarjeta y los enlaces de descarga del cartel para imprimir (PDF A5 o A6) y del QR solo (PNG, SVG) para una carta, un escaparate o Canva. Úsala cuando el comerciante quiera imprimir su cartel, recuperar su código QR o el enlace para su bio. Las descargas se abren en la aplicación, con la sesión iniciada. Para recibir los PDF por correo: envoyer_affichette. Solo lectura. ## Parámetros - `format` (enum, opcional) : Formato del PDF destacado: a5 (media hoja, cartel de mostrador) o a6 (cuarto de hoja, expositor o portatarjetas). Valores : a5, a6. Por defecto : "a5". ## Ejemplo Prompt : « Dame mi código QR y el cartel para imprimir. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "affichette", "arguments": { "format": "a5" } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/affichette/ --- # envoyer_affichette Con cuenta · Escribe (confirmar). Envía el cartel de mostrador (PDF A5 y A6, con el QR de registro de los clientes) a la dirección de correo de la cuenta de StampyWallet conectada, para imprimirlo desde otro dispositivo o en una imprenta. Solo a esa dirección, nunca a otra. Llámala con confirmer=false (por defecto) para anunciar el envío, y luego confirmer=true tras la aprobación. ## Parámetros - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Envíame el cartel por correo para imprimirlo. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "envoyer_affichette", "arguments": { "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/envoyer_affichette/ --- # equipe Con cuenta · Escribe (confirmar) · Solo propietario. Gestiona el equipo del comercio (solo el propietario). action=lister: los miembros (nombre, correo, rol, sellos puestos) y las invitaciones pendientes. action=inviter: crea una invitación personal válida 14 días (rol empleado = solo escáner, o encargado = cifras, clientes, mensajes, tarjeta); con «email», sale por correo a la persona; si no, se devuelve el enlace para pasarlo. action=changer_role: cambia a un miembro a empleado o encargado. action=retirer: retira el acceso de un miembro y cierra sus sesiones. action=annuler_invitation: cancela un enlace aún sin usar. Los cambios usan confirmer=false (por defecto, vista previa) y luego confirmer=true tras la aprobación explícita. Nombrar a un propietario se hace en la aplicación. ## Parámetros - `action` (enum, opcional) : Lo que hay que hacer. Valores : lister, inviter, changer_role, retirer, annuler_invitation. Por defecto : "lister". - `membre_id` (string, ≤ 36 caracteres, opcional) : changer_role, retirer: identificador del miembro, leído con action=lister. - `email` (string, ≤ 254 caracteres, opcional) : inviter: dirección de la persona invitada, la invitación se le envía por correo. changer_role, retirer: correo de un miembro (en lugar de membre_id). - `nom` (string, ≤ 60 caracteres, opcional) : inviter: referencia para orientarse en las invitaciones (p. ej. «Julie, por la mañana»). - `role` (enum, opcional) : inviter (por defecto staff), changer_role: staff = empleado, solo ve el escáner; manager = encargado, ve cifras, clientes, mensajes y ajusta la tarjeta, sin tocar el equipo. Valores : staff, manager. - `invitation` (string, ≤ 300 caracteres, opcional) : annuler_invitation: el enlace de invitación o su token, leídos con action=lister. - `confirmer` (boolean, opcional) : false (por defecto): solo devuelve una vista previa de lo que se haría, sin cambiar nada. true: ejecuta. Enseña siempre la vista previa a la persona y espera su aprobación antes de volver a llamar con true. Por defecto : false. ## Ejemplo Prompt : « Invita a Julie como empleada, su correo es julie@example.com. » ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "equipe", "arguments": { "action": "inviter", "email": "julie@example.com", "nom": "Julie, por la mañana", "role": "staff", "confirmer": false } } } ``` Source : https://stampywallet.com/es/docs/mcp/herramientas/equipe/ --- # La API de StampyWallet Añade visitas, crea clientes y recibe los eventos de tu tarjeta de fidelidad desde tu TPV, tu web o una herramienta sin código. La API conecta StampyWallet con el resto de tu comercio. Funciona en los dos sentidos: - **Hacia StampyWallet**: tu TPV, tu web o tu software de reservas añade una visita, crea un cliente o entrega una recompensa, sin escanear en el mostrador. - **Desde StampyWallet**: en cada visita, tarjeta nueva o recompensa, StampyWallet llama a una dirección que tú eliges (un [webhook](https://stampywallet.com/es/docs/api/webhooks/)). Es lo que alimenta una hoja de cálculo, un CRM o un escenario de Zapier. > **Antes de empezar :** la API, las direcciones de entrada de los TPV ([Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/)) y los webhooks están incluidos en el plan **Crecimiento** (40 € sin IVA al mes) y abiertos durante la prueba gratuita. Con el plan Esencial, las llamadas responden `403` con el código `formule_requise`. > **Atención :** la API está en **beta**. Las rutas y los campos descritos aquí son los de la implementación; pueden aparecer campos nuevos antes de la versión estable: ignora los que no conozcas. Los cambios se anuncian en las [novedades](site:novedades/). ## La dirección base Todas las rutas se sirven en HTTPS, en formato JSON (campos en francés, en snake_case), bajo: ```text title="Dirección base" https://app.stampywallet.com/v1 ``` Los identificadores son UUID; los importes van en la moneda del comercio, en unidades (`12.5` para 12,50 €). ## Una primera llamada Crea una clave en **Ajustes › Integraciones** (ver [Autenticación](https://stampywallet.com/es/docs/api/autenticacion/)) y luego lee la ficha de tu comercio: ```bash title="curl" curl https://app.stampywallet.com/v1/commerce \ -H "Authorization: Bearer sw_live_votre_cle" ``` ```js title="Node.js" const reponse = await fetch('https://app.stampywallet.com/v1/commerce', { headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` }, }); console.log(await reponse.json()); ``` ```python title="Python" import os, requests reponse = requests.get( "https://app.stampywallet.com/v1/commerce", headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"}, ) print(reponse.json()) ``` ## Lo que sabe hacer la API | Ruta | Función | |---|---| | `GET /v1/commerce` | [Leer la ficha del comercio](https://stampywallet.com/es/docs/api/comercio/) y las reglas de la tarjeta | | `POST /v1/clients` | [Crear un cliente](https://stampywallet.com/es/docs/api/crear-cliente/) y obtener el enlace de su tarjeta | | `GET /v1/clients` | [Buscar un cliente](https://stampywallet.com/es/docs/api/buscar-clientes/) por teléfono, correo o tarjeta | | `GET /v1/clients/:id` | [Leer un cliente](https://stampywallet.com/es/docs/api/leer-cliente/) y el estado de su tarjeta | | `POST /v1/passages` | [Añadir una visita](https://stampywallet.com/es/docs/api/anadir-visita/): un sello, o puntos según el importe | | `DELETE /v1/passages/:id` | [Anular una visita](https://stampywallet.com/es/docs/api/anular-visita/) | | `POST /v1/recompenses` | [Entregar una recompensa](https://stampywallet.com/es/docs/api/dar-recompensa/) ganada | | `POST /v1/entrants/:jeton` | [Recibir las ventas de tu TPV](https://stampywallet.com/es/docs/api/entrantes/) (Square, Shopify, SumUp, Zettle o el formato genérico) | Y en el otro sentido, los [webhooks salientes](https://stampywallet.com/es/docs/api/webhooks/): nueve [eventos](https://stampywallet.com/es/docs/api/eventos/), firmados. > **Consejo :** ¿no tienes un desarrollador a mano? La página [Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/) da los ajustes paso a paso para Square, Shopify, SumUp y Zettle, y para Zapier, Make y n8n. ## ¿Y el MCP? La API está pensada para el software: un TPV, una web, un script. Para gestionar tu comercio **conversando**, desde Claude, ChatGPT o Cursor, usa mejor el [servidor MCP](https://stampywallet.com/es/docs/mcp/conectar/): no pide ninguna clave, solo conectar tu cuenta. ## Preguntas frecuentes **¿Cuánto cuesta la API?** La API, las direcciones de entrada de los TPV y los webhooks están incluidos en el plan Crecimiento, a 40 € sin IVA al mes, y abiertos durante la prueba gratuita de 30 días. Con el plan Esencial, las llamadas responden `403`. **¿Necesito un desarrollador para conectar mi TPV?** No para Square, Shopify, SumUp, Zettle, Zapier, Make o n8n: la página [Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/) da los ajustes paso a paso. Llamar a la API desde tu propio programa, en cambio, requiere a alguien que escriba código. **¿Hay un límite de llamadas?** Sí: 120 peticiones por minuto y por clave. Por encima, la respuesta es `429` con la cabecera `Retry-After`. **¿Una clave sirve para varios locales?** No. Una clave da acceso solo al comercio en el que se creó: crea una clave en cada local. **¿Cómo evito un sello doble cuando mi TPV reintenta?** Da una `reference` a cada visita, por ejemplo el número del ticket, y envía una cabecera `Idempotency-Key` en cada `POST`: un nuevo intento no sella dos veces. Source : https://stampywallet.com/es/docs/api/ --- # Autenticación Cada llamada a la API lleva una clave secreta sw_live_, creada en Ajustes › Integraciones y mostrada una sola vez. 120 peticiones por minuto y por clave. ## Crear una clave 1. **Abre Ajustes › Integraciones** en tu espacio de StampyWallet (el propietario o un encargado). 2. **Crea una clave** y ponle un nombre que diga dónde se usa («Caja del mostrador», «Web»). 3. **Cópiala enseguida.** Empieza por `sw_live_` y solo se muestra completa una vez: StampyWallet solo guarda una huella. Si la pierdes, no se puede recuperar: revócala y crea otra. ## Enviarla en cada llamada La clave va en la cabecera `Authorization`, después de la palabra `Bearer`: ```http title="Cabecera" Authorization: Bearer sw_live_4f9c2a7e1b... ``` Una clave da acceso a **un** comercio: aquel en el que se creó. Si gestionas varios establecimientos, crea una clave en cada uno. > **Atención :** la clave actúa en tu nombre: crea clientes y añade visitas. Guárdala en el servidor (variable de entorno, gestor de secretos), nunca en el código de una página web o de una aplicación móvil, nunca en un repositorio Git. ## Revocar una clave En **Ajustes › Integraciones**, revoca la clave: las llamadas que la lleven fallan al instante con `401` y el código `cle_revoquee`. Hazlo en cuanto una clave haya podido filtrarse, o cuando un proveedor ya no la necesite. ## Los errores de acceso | Estado | `code` | Cuándo | |---|---|---| | `401` | `non_authentifie` | Cabecera ausente o clave desconocida | | `401` | `cle_revoquee` | La clave se ha revocado | | `403` | `formule_requise` | El comercio no tiene el plan Crecimiento (la API está incluida, y abierta durante la prueba) | | `403` | `interdit` | La acción no está permitida para este comercio | | `429` | `trop_de_requetes` | Más de 120 peticiones por minuto con esta clave | ## El límite de peticiones **120 peticiones por minuto y por clave.** Por encima, la respuesta es `429` con la cabecera `Retry-After: 60`: espera ese número de segundos antes de seguir. Un TPV normal está muy lejos de ese límite. El detalle del formato de los errores está en la página [Errores](https://stampywallet.com/es/docs/api/errores/). Source : https://stampywallet.com/es/docs/api/autenticacion/ --- # Errores y reintentos El formato de los errores de la API, todos sus códigos y la cabecera Idempotency-Key para reintentar un POST sin riesgo de duplicados. ## El formato de un error Un error responde con un estado HTTP 4xx o 5xx y siempre el mismo cuerpo: ```json title="Respuesta de error" { "erreur": { "code": "client_introuvable", "message": "Ningún cliente coincide en este comercio." } } ``` - `code` es estable: es lo que tu programa debe comprobar. - `message` es una frase legible, para tus registros. Su texto puede cambiar. ## Los códigos | Estado | Códigos | |---|---| | `400` | `requete_invalide` (JSON ilegible), `client_requis`, `recherche_requise`, `montant_invalide`, `quantite_invalide`, `points_invalide`, `email_invalide`, `telephone_invalide`, `idempotency_key_invalide` | | `401` | `non_authentifie`, `cle_revoquee`, `signature_invalide` (direcciones de entrada) | | `403` | `formule_requise` (la API requiere el plan Crecimiento), `interdit` | | `404` | `introuvable` (dirección), `client_introuvable`, `passage_introuvable` | | `409` | `trop_tot`, `pas_dernier`, `deja_annule`, `recompense_offerte`, `aucune_recompense`, `requete_en_cours` | | `422` | `conditions_requises`, `montant_insuffisant` | | `429` | `trop_de_requetes` (ver [el límite de peticiones](https://stampywallet.com/es/docs/api/autenticacion/#limite)) | | `500` | `interne`: vuelve a intentarlo más tarde, con la misma `Idempotency-Key` | ## Reintentar sin duplicados: Idempotency-Key La red se corta en el peor momento y no sabes si la visita se ha registrado. Para reintentar sin riesgo, envía en cada `POST` (`/clients`, `/passages`, `/recompenses`) una cabecera `Idempotency-Key`: un valor único por operación, de 1 a 200 caracteres, por ejemplo el número del ticket. ```bash title="curl" curl https://app.stampywallet.com/v1/passages \ -H "Authorization: Bearer sw_live_votre_cle" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ticket-2026-10-25-0042" \ -d '{"client": {"telephone": "+33612345678"}, "montant": 12.50}' ``` - La respuesta se guarda **24 horas**. La misma clave repetida devuelve el mismo estado y el mismo cuerpo, con la cabecera `Idempotent-Replayed: true`. - Un error `4xx` también se guarda: repetirlo devuelve el mismo error. Un error `500` libera la clave, para que puedas reintentar. - Mientras la primera petición sigue en curso: `409 requete_en_cours`. > **Consejo :** en [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/), el campo `reference` (tu número de ticket) también protege: una misma referencia solo sella una vez por comercio, incluso sin `Idempotency-Key`. Source : https://stampywallet.com/es/docs/api/errores/ --- # Leer el comercio GET /v1/commerce devuelve la ficha del comercio vinculado a la clave y las reglas de su tarjeta de fidelidad. `GET /v1/commerce` Devuelve el comercio al que pertenece la clave: su nombre, su moneda, su zona horaria y las reglas de su tarjeta (modo, objetivo, recompensas, regla por importe). Útil para comprobar una clave o para mostrar la regla de la tarjeta en tu TPV. ## Ejemplo ```bash title="curl" curl https://app.stampywallet.com/v1/commerce \ -H "Authorization: Bearer sw_live_votre_cle" ``` ```js title="Node.js" const r = await fetch('https://app.stampywallet.com/v1/commerce', { headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}` }, }); const commerce = await r.json(); ``` ## Respuesta ```json title="200 OK" { "id": "5f0c8e2a-3b1d-4c9e-9a51-2d7f3e8b6a10", "nom": "Boulangerie Lemaire", "mode": "tampons", "tampons_requis": 10, "recompense": "Una baguette tradicional gratis", "recompenses": [ { "seuil": 10, "libelle": "Una baguette tradicional gratis" } ], "devise": "EUR", "montant_par_tampon": 10, "points_par_unite": null, "tampons_bienvenue": 1, "conditions_exigees": false, "premium": null, "fuseau": "Europe/Paris", "langue": "fr" } ``` | Campo | Significado | |---|---| | `mode` | `tampons`, `paliers` o `points` ([los tipos de tarjeta](https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/)) | | `recompenses` | Cada recompensa con su `seuil` | | `montant_par_tampon` | La regla «10 € = 1 sello», o `null` | | `points_par_unite` | En modo puntos: cuántos puntos por 1 unidad de moneda | | `conditions_exigees` | `true` si el comercio exige aceptar sus condiciones: en ese caso, pasa `conditions_acceptees: true` al crear un cliente | | `premium` | El segundo contador, cuando el comercio lo ha abierto; si no, `null` | Source : https://stampywallet.com/es/docs/api/comercio/ --- # Crear un cliente POST /v1/clients registra a un cliente en el programa de fidelidad y devuelve el enlace de su tarjeta, para enviárselo por SMS o correo. `POST /v1/clients` Registra a un cliente, como si hubiera escaneado el cartel, y devuelve el objeto cliente con `lien_carte`: la página donde añade su tarjeta a Apple Wallet o Google Wallet. Se ponen los sellos de bienvenida del comercio, como en el registro. **Cuerpo (JSON)** - `prenom` (string, opcional) : Nombre del cliente, que aparece en su tarjeta. - `nom` (string, opcional) : Apellido. - `telephone` (string, opcional) : Un móvil, en el formato del país del comercio o internacional (`+33612345678`). Si no, `400 telephone_invalide`. - `email` (string, opcional) : Dirección de correo. - `conditions_acceptees` (boolean, opcional) : Obligatorio (`true`) cuando el comercio exige sus condiciones (`conditions_exigees` de [`GET /v1/commerce`](https://stampywallet.com/es/docs/api/comercio/)); si no, `422 conditions_requises`. > **Atención :** esta ruta **no elimina duplicados**: si la llamas dos veces, crea dos clientes. Busca primero con [`GET /v1/clients`](https://stampywallet.com/es/docs/api/buscar-clientes/), o pasa directamente por [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/) con `creer_si_absent: true`, que solo crea el cliente si no existe. El cliente creado por la API nunca queda suscrito a los SMS de ofertas: no ha recibido la información. ## Ejemplo ```bash title="curl" curl https://app.stampywallet.com/v1/clients \ -H "Authorization: Bearer sw_live_votre_cle" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: inscription-0412" \ -d '{"prenom": "Léa", "telephone": "+33612345678"}' ``` ```js title="Node.js" const r = await fetch('https://app.stampywallet.com/v1/clients', { method: 'POST', headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'inscription-0412', }, body: JSON.stringify({ prenom: 'Léa', telephone: '+33612345678' }), }); const client = await r.json(); console.log(client.lien_carte); ``` ```python title="Python" import os, requests r = requests.post( "https://app.stampywallet.com/v1/clients", headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}", "Idempotency-Key": "inscription-0412"}, json={"prenom": "Léa", "telephone": "+33612345678"}, ) lien = r.json()["lien_carte"] ``` ## Respuesta `201 Created` y [el objeto cliente](https://stampywallet.com/es/docs/api/leer-cliente/#objet), por ejemplo: ```json title="201 Created" { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "nom": null, "telephone": "+33612345678", "email": null, "carte": "X7k2pQ9mLw", "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw", "cree_le": "2026-10-25T10:41:52.120Z", "etat": { "mode": "tampons", "tampons": 1, "points": null, "objectif": 10, "restants": 9, "prochaine_recompense": { "seuil": 10, "libelle": "Una baguette tradicional gratis" }, "recompenses_disponibles": [], "recompenses_obtenues": 0, "dernier_passage": null, "premium": null } } ``` > **Nota :** envía `lien_carte` al cliente por el canal que prefieras: StampyWallet no le escribe en este paso. Source : https://stampywallet.com/es/docs/api/crear-cliente/ --- # Buscar un cliente GET /v1/clients encuentra a un cliente por su teléfono, su correo o el código de su tarjeta. `GET /v1/clients` Encuentra a un cliente del comercio. Indica **solo uno** de los tres parámetros de consulta (si no, `400 recherche_requise`): **Parámetros de consulta** - `telephone` (string, opcional) : El número, codificado en la dirección (`%2B33612345678`). Se interpreta en el país del comercio: `0612345678` y `+33612345678` encuentran al mismo cliente. - `email` (string, opcional) : Dirección de correo, sin distinguir mayúsculas. - `carte` (string, opcional) : El código de la tarjeta, el que lleva su QR. ## Ejemplo ```bash title="curl" curl "https://app.stampywallet.com/v1/clients?telephone=%2B33612345678" \ -H "Authorization: Bearer sw_live_votre_cle" ``` ## Respuesta ```json title="200 OK" { "clients": [ { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "nom": "Martin", "telephone": "+33612345678", "email": null, "carte": "X7k2pQ9mLw", "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw", "cree_le": "2026-10-25T10:41:52.120Z", "etat": { "mode": "tampons", "tampons": 7, "points": null, "objectif": 10, "restants": 3, "prochaine_recompense": { "seuil": 10, "libelle": "Una baguette tradicional gratis" }, "recompenses_disponibles": [], "recompenses_obtenues": 1, "dernier_passage": "2026-10-28T08:02:11.000Z", "premium": null } } ] } ``` La lista está vacía (`"clients": []`) cuando no coincide nadie: no es un error. Cuando varias fichas tienen el mismo correo o el mismo número, se devuelve la que vino más recientemente. El detalle de los campos: [el objeto cliente](https://stampywallet.com/es/docs/api/leer-cliente/#objet). Source : https://stampywallet.com/es/docs/api/buscar-clientes/ --- # Leer un cliente GET /v1/clients/:id devuelve un cliente y el estado de su tarjeta de fidelidad, sellos, puntos y recompensas por entregar. `GET /v1/clients/:id` Devuelve un cliente y el estado de su tarjeta. `:id` es el UUID devuelto por [`POST /v1/clients`](https://stampywallet.com/es/docs/api/crear-cliente/) o [`GET /v1/clients`](https://stampywallet.com/es/docs/api/buscar-clientes/). Un identificador desconocido responde `404 client_introuvable`. ```bash title="curl" curl https://app.stampywallet.com/v1/clients/c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7 \ -H "Authorization: Bearer sw_live_votre_cle" ``` ## El objeto cliente El mismo objeto aparece en todas las rutas de cliente, y en el campo `client` de las demás respuestas: ```json title="200 OK" { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "nom": "Martin", "telephone": "0612345678", "email": "lea@exemple.fr", "carte": "X7k2pQ9mLw", "lien_carte": "https://stampywallet.com/c/X7k2pQ9mLw", "cree_le": "2026-10-22T09:14:03.120Z", "etat": { "mode": "tampons", "tampons": 3, "points": null, "objectif": 10, "restants": 7, "prochaine_recompense": { "seuil": 10, "libelle": "Un café gratis" }, "recompenses_disponibles": [ { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café gratis", "seuil": 10, "piste": "normal", "obtenue_le": "2026-10-20T16:03:44.000Z", "expire_le": null } ], "recompenses_obtenues": 1, "dernier_passage": "2026-10-22T09:20:00.000Z", "premium": null } } ``` | Campo | Significado | |---|---| | `carte` | El código de la tarjeta, el de su QR | | `lien_carte` | La página de la tarjeta, que propone añadirla a Apple Wallet o Google Wallet | | `etat.tampons`, `etat.points` | `tampons` en los modos tampons y paliers, `points` en modo points; el otro vale `null` | | `etat.restants` | Lo que falta para la próxima recompensa | | `etat.recompenses_disponibles` | Las recompensas ganadas, aún no entregadas: su `id` sirve para [entregarlas](https://stampywallet.com/es/docs/api/dar-recompensa/) | | `etat.premium` | `{ nom, tampons, objectif, restants }` cuando el comercio ha abierto el segundo contador; si no, `null` | > **Nota :** los identificadores son UUID. Se aceptan en la entrada prefijos `cli_`, `pas_` o `rec_` delante de un UUID, y se ignoran. Source : https://stampywallet.com/es/docs/api/leer-cliente/ --- # Añadir una visita POST /v1/passages añade un sello o puntos a la tarjeta de un cliente desde tu TPV, e indica si se ha conseguido una recompensa. `POST /v1/passages` El equivalente a un escaneo en el mostrador, enviado por tu TPV: un sello (o varios), o puntos. Las reglas y los límites son los del mostrador, la tarjeta del cliente se actualiza en su Wallet y la visita cuenta como las demás (habituales, recordatorios, solicitud de reseña). **Cuerpo (JSON)** - `client` (object, obligatorio) : Quién recibe la visita: **uno** de `id`, `carte` (el código de la tarjeta), `email` o `telephone`. - `montant` (number, opcional) : Importe del ticket, en unidades (`12.5` para 12,50 €). Si el comercio tiene una regla «10 € = 1 sello», el importe prevalece sobre `quantite`; en modo puntos, se convierte con la regla de puntos por euro del comercio. - `quantite` (integer, opcional) : Modos tampons y paliers: número de sellos, 1 por defecto, 50 como máximo. - `points` (integer, opcional) : Modo points, sin importe: los puntos que poner. Por defecto, el valor del comercio. - `reference` (string, opcional) : El número del ticket. Una referencia solo sella una vez por comercio. - `creer_si_absent` (boolean, opcional) : `true`: un cliente desconocido, identificado por `email` o `telephone`, se crea (con `prenom` y `nom` si están en `client`). Por defecto `false`. - `conditions_acceptees` (boolean, opcional) : Cuando el comercio exige sus condiciones y `creer_si_absent` crea el cliente (en `client` o en la raíz). ## Ejemplo ```bash title="curl" curl https://app.stampywallet.com/v1/passages \ -H "Authorization: Bearer sw_live_votre_cle" \ -H "Content-Type: application/json" \ -d '{ "client": { "telephone": "+33612345678", "prenom": "Léa" }, "montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": true }' ``` ```js title="Node.js" const r = await fetch('https://app.stampywallet.com/v1/passages', { method: 'POST', headers: { Authorization: `Bearer ${process.env.STAMPY_CLE}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ client: { telephone: '+33612345678', prenom: 'Léa' }, montant: 12.5, reference: 'TICKET-4512', creer_si_absent: true, }), }); const resultat = await r.json(); if (resultat.recompense_atteinte) console.log('¡Recompensa por entregar!'); ``` ```python title="Python" import os, requests r = requests.post( "https://app.stampywallet.com/v1/passages", headers={"Authorization": f"Bearer {os.environ['STAMPY_CLE']}"}, json={"client": {"telephone": "+33612345678", "prenom": "Léa"}, "montant": 12.5, "reference": "TICKET-4512", "creer_si_absent": True}, ) print(r.json()["recompense_atteinte"]) ``` ## Respuesta ```json title="201 Created" { "passage": { "id": "226fdea1-ba59-49fb-93e6-60a14a765134", "client_id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "valeur": 1, "montant": 12.5, "reference": "TICKET-4512", "cree_le": "2026-10-22T09:20:00.000Z" }, "rejoue": false, "client_cree": false, "recompense_atteinte": true, "recompenses_gagnees": 1, "plafonne": false, "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 0, "objectif": 10 } } } ``` | Campo | Significado | |---|---| | `passage.valeur` | Los sellos o puntos puestos | | `passage.montant` | El importe registrado, o `null` | | `rejoue` | `true` cuando la `reference` ya se había usado: la respuesta es entonces `200` y devuelve la visita original, sin sellar una segunda vez | | `client_cree` | `true` si `creer_si_absent` ha creado el cliente | | `recompense_atteinte`, `recompenses_gagnees` | Esta visita hace ganar una recompensa (o varias): para [entregar](https://stampywallet.com/es/docs/api/dar-recompensa/) cuando el cliente la recoja | | `plafonne` | `true` si el valor se ha reducido al máximo del mostrador | | `client` | [El objeto cliente](https://stampywallet.com/es/docs/api/leer-cliente/#objet) después de la visita | ## Los rechazos | Estado | `code` | Cuándo | |---|---|---| | `404` | `client_introuvable` | Ningún cliente coincide y `creer_si_absent` no está a `true` | | `409` | `trop_tot` | Hubo una visita del mismo cliente hace menos que el plazo antidoble visita del comercio (90 segundos por defecto) | | `422` | `montant_insuffisant` | El importe no llega a un sello (o a un punto) | | `422` | `conditions_requises` | El cliente se crearía, pero las condiciones del comercio no se han aceptado | > **Atención :** indica siempre una `reference` (el número de ticket): así, un TPV que reintenta tras un corte no pone dos sellos. Una referencia cuya visita se ha anulado no se vuelve a poner. Source : https://stampywallet.com/es/docs/api/anadir-visita/ --- # Anular una visita DELETE /v1/passages/:id retira la última visita de un cliente, por ejemplo tras un ticket anulado o reembolsado en caja. `DELETE /v1/passages/:id` Retira una visita, con los permisos de un encargado: se quitan los sellos o puntos que puso, y una recompensa que hubiera desbloqueado desaparece con ella. `:id` es el UUID devuelto por [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/). Cuerpo opcional: `{ "motif": "Ticket anulado" }` (o `?motif=` en la dirección). Por defecto, el motivo es «API». ## Ejemplo ```bash title="curl" curl -X DELETE https://app.stampywallet.com/v1/passages/226fdea1-ba59-49fb-93e6-60a14a765134 \ -H "Authorization: Bearer sw_live_votre_cle" \ -H "Content-Type: application/json" \ -d '{"motif": "Ticket reembolsado"}' ``` ## Respuesta ```json title="200 OK" { "annule": true, "recompenses_retirees": 1, "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "tampons": 9, "objectif": 10 } } } ``` ## Los rechazos Como en el mostrador, solo se puede anular la **última** visita de un cliente, y nunca dos veces. | Estado | `code` | Cuándo | |---|---|---| | `404` | `passage_introuvable` | La visita no existe en este comercio | | `409` | `pas_dernier` | No es la última visita del cliente | | `409` | `deja_annule` | La visita ya está anulada | | `409` | `recompense_offerte` | La recompensa desbloqueada por esta visita ya se ha entregado (la respuesta lleva un campo `recompense`) | Source : https://stampywallet.com/es/docs/api/anular-visita/ --- # Entregar una recompensa POST /v1/recompenses marca como entregada una recompensa ganada por un cliente, desde tu TPV. `POST /v1/recompenses` Marca una recompensa ganada como entregada al cliente, el equivalente al botón «Entregada» del escáner. La tarjeta del cliente se actualiza en su Wallet. **Cuerpo (JSON)** - `client` (object, obligatorio) : El cliente: **uno** de `id`, `carte`, `email` o `telephone`. - `recompense_id` (string, opcional) : El UUID de la recompensa que entregar (en `etat.recompenses_disponibles` del [objeto cliente](https://stampywallet.com/es/docs/api/leer-cliente/#objet)). Por defecto: la pendiente más antigua. - `piste` (string, opcional) : `normal` o `premium` (el segundo contador): sin `recompense_id`, la pendiente más antigua de ese contador. ## Ejemplo ```bash title="curl" curl https://app.stampywallet.com/v1/recompenses \ -H "Authorization: Bearer sw_live_votre_cle" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: recompense-ticket-0057" \ -d '{"client": {"carte": "X7k2pQ9mLw"}}' ``` ## Respuesta ```json title="200 OK" { "recompense": { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café gratis", "piste": "normal", "offerte_le": "2026-10-22T09:25:00.000Z" }, "client": { "id": "c2a91f3e-7d40-4b8a-a3c5-91e0d6f4b2c7", "prenom": "Léa", "etat": { "recompenses_disponibles": [] } } } ``` Sin recompensa que entregar, la respuesta es `409` con el código `aucune_recompense`. Source : https://stampywallet.com/es/docs/api/dar-recompensa/ --- # Webhooks Recibe una llamada HTTP firmada en tu servidor, Zapier, Make o n8n en cada visita, recompensa o tarjeta nueva, y verifica su firma HMAC. Un webhook es una dirección de tu servidor a la que StampyWallet llama en cada evento del mostrador: una visita, una recompensa, una tarjeta nueva, una tarjeta regalo vendida. Es lo que conecta StampyWallet con un TPV, un CRM, una hoja de cálculo o una herramienta sin código, sin integración oficial. > **¿En el otro sentido? :** para que tu TPV añada un sello en cada venta, usa [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/), o [recibe las ventas de tu TPV](https://stampywallet.com/es/docs/api/entrantes/) directamente. ## Configurar una dirección En **Ajustes › Integraciones › Webhooks** (el propietario y los encargados): 1. **Añade una dirección** `https://` pública y marca, si quieres, los eventos. **Ninguna casilla marcada: todos los eventos**, incluidos los que se añadan más adelante. 2. **Copia el secreto de firma**, que empieza por `whsec_`. Solo se muestra una vez; después la pantalla solo enseña los cuatro últimos caracteres. 3. **Haz clic en «Enviar una prueba»**: sale enseguida hacia tu dirección un `passage.cree` de ejemplo, marcado con `"test": true`, y la pantalla muestra la respuesta obtenida. La pantalla muestra los 20 últimos envíos (estado, código, duración, intento) y un botón **Reenviar** en los que han fallado. Diez direcciones como máximo por comercio; cada una se puede desactivar, reactivar o eliminar. > **Atención :** se rechazan: una dirección que no sea `https://`, una dirección que contenga credenciales (`https://yo:secreto@…`) y cualquier dirección privada o local (`localhost`, `10.x`, `192.168.x`…), aunque se obtenga por DNS. Se aceptan todos los puertos. Las redirecciones nunca se siguen: una respuesta 3xx cuenta como fallo. ## Lo que recibe tu servidor Una petición `POST` en JSON, con estas cabeceras: ```http title="Cabeceras" POST /votre/adresse HTTP/1.1 Content-Type: application/json User-Agent: StampyWallet-Webhooks/1.0 StampyWallet-Evenement: passage.cree StampyWallet-Id: evt_WdGHduXPRbExh0vh5eYtCjXo StampyWallet-Signature: t=1792648365,v1=8f3c…(64 caracteres hexadecimales) ``` Y este cuerpo. El sobre es el mismo para todos los eventos; solo cambia `donnees` ([la lista de eventos](https://stampywallet.com/es/docs/api/eventos/)): ```json title="passage.cree" { "id": "evt_WdGHduXPRbExh0vh5eYtCjXo", "type": "passage.cree", "cree_le": "2026-10-22T05:52:45.694Z", "commerce": { "id": "9f1cbdfc-df71-4fab-a554-3bdbb7c71ebf", "nom": "Le Café des Crochets" }, "donnees": { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "passage": { "id": "226fdea1-ba59-49fb-93e6-60a14a765134", "quantite": 1, "montant": null, "devise": "EUR", "reference": "caisse-1", "source": "scan", "piste": "normal", "tampons": 1, "objectif": 2 } } } ``` - `id`: `evt_` seguido de 24 caracteres. **El mismo en todos los envíos de un evento** (intentos, reenvíos, y de una dirección a otra): es tu clave para eliminar duplicados. - `cree_le`: el momento del evento (no el del envío), en ISO 8601 UTC. - `test`: presente, a `true`, solo en el envío del botón «Enviar una prueba». - `donnees.client`: `{ id, prenom }`, más `telephone` y `email` solo si el cliente los ha dado; `null` para una tarjeta regalo o un bono. - Los importes (`montant`, `prix`) van en **céntimos**, enteros, con su `devise` (ISO 4217). - Pueden aparecer claves nuevas: ignora lo que no conozcas. ## Verificar la firma Verifica cada petición **antes** de fiarte de su contenido: sin eso, cualquiera podría llamar a tu dirección. ```text title="El cálculo" StampyWallet-Signature: t=,v1= firma = hex( HMAC-SHA256( clave = secreto, mensaje = "." ) ) ``` - La clave es el secreto **completo**, prefijo `whsec_` incluido. - El mensaje es la marca de tiempo `t`, un punto y luego el cuerpo **tal como se recibe**, en bytes. No vuelvas a leer el JSON antes de verificar: un JSON reescrito ya no tiene los mismos bytes. - Rechaza un `t` a más de 5 minutos de tu reloj: así se impide reenviar una petición antigua. - La cabecera puede llevar varios `v1=` (el día de un cambio de secreto): basta con que coincida uno. Compara en tiempo constante. ```js title="Node.js" const crypto = require('node:crypto'); /** corpsBrut: el cuerpo recibido, en Buffer (o en texto), ANTES de cualquier JSON.parse. */ function verifierStampyWallet(secret, corpsBrut, entete, tolerance = 300) { let t = null; const v1 = []; for (const morceau of String(entete || '').split(',')) { const i = morceau.indexOf('='); const cle = morceau.slice(0, i).trim(); const valeur = morceau.slice(i + 1).trim(); if (cle === 't' && /^\d+$/.test(valeur)) t = Number(valeur); if (cle === 'v1') v1.push(valeur); } if (t === null || v1.length === 0) return false; if (Math.abs(Math.floor(Date.now() / 1000) - t) > tolerance) return false; const attendue = crypto.createHmac('sha256', secret) .update(`${t}.`).update(corpsBrut).digest('hex'); return v1.some((s) => s.length === attendue.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(attendue))); } // Con Express: conservar el cuerpo sin procesar en esta ruta. app.post('/stampywallet', express.raw({ type: 'application/json' }), (req, res) => { const ok = verifierStampyWallet(process.env.STAMPYWALLET_WEBHOOK_SECRET, req.body, req.get('StampyWallet-Signature')); if (!ok) return res.status(400).end(); const evenement = JSON.parse(req.body.toString('utf8')); // eliminar duplicados con evenement.id y procesar más tarde res.status(200).end(); }); ``` ```python title="Python" import hashlib import hmac import time def verifier_stampywallet(secret: str, corps_brut: bytes, entete: str, tolerance: float = 300) -> bool: """corps_brut: los bytes recibidos (Flask: request.get_data()), antes de cualquier json.loads.""" t, v1 = None, [] for morceau in (entete or "").split(","): cle, _, valeur = morceau.strip().partition("=") if cle == "t" and valeur.isdigit(): t = int(valeur) elif cle == "v1": v1.append(valeur) if t is None or not v1: return False if abs(int(time.time()) - t) > tolerance: return False attendue = hmac.new(secret.encode(), f"{t}.".encode() + corps_brut, hashlib.sha256).hexdigest() return any(hmac.compare_digest(s, attendue) for s in v1) # Con Flask: # @app.post("/stampywallet") # def recevoir(): # if not verifier_stampywallet(os.environ["STAMPYWALLET_WEBHOOK_SECRET"], # request.get_data(), # request.headers.get("StampyWallet-Signature", "")): # abort(400) # evenement = request.get_json() # return "", 200 ``` ```php title="PHP" $tolerance) { return false; } $attendue = hash_hmac('sha256', $t . '.' . $corpsBrut, $secret); foreach ($v1 as $s) { if (hash_equals($attendue, $s)) { return true; } } return false; } // el cuerpo sin procesar, antes de json_decode $corps = file_get_contents('php://input'); $ok = verifier_stampywallet(getenv('STAMPYWALLET_WEBHOOK_SECRET'), $corps, $_SERVER['HTTP_STAMPYWALLET_SIGNATURE'] ?? ''); ``` ### Vector de prueba Para comprobar tu código: con estos valores y una tolerancia infinita (`Infinity`, `float("inf")`, `PHP_INT_MAX`), la función debe devolver verdadero. El cuerpo ocupa una sola línea, sin salto de línea final, y contiene una «é» a propósito: la firma se calcula sobre los bytes UTF-8. ```text title="Vector" secret : whsec_5WZbPq8rLk2N7xYdTf3Hc9JmVg4RsQe1 t : 1761134400 corps : {"id":"evt_4fK9mQ2xT7bL1nR8vZ3cW6yH","type":"passage.cree","cree_le":"2026-10-22T12:00:00.000Z","commerce":{"id":"9b2f6c1e-4d3a-4f7b-8e21-5a6c7d8e9f01","nom":"Le Café du Coin"},"donnees":{"client":{"id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","prenom":"Camille"},"passage":{"id":"7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b","quantite":1,"montant":null,"devise":"EUR","reference":null,"source":"scan","piste":"normal","tampons":4,"objectif":10}}} v1 : 4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d en-tête: t=1761134400,v1=4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d ``` ## Responder, y los reintentos - Responde con un código **2xx en menos de 10 segundos**. El cuerpo de tu respuesta se ignora. Responde rápido y haz el trabajo largo después. - Si no, **ocho intentos** en total: el primero enseguida, luego a 1 min, 5 min, 30 min, 2 h, 5 h, 8 h y 8 h. El último sale unas 23 h 30 después del primero; al octavo fallo, el envío se abandona. - Tras **50 fallos seguidos** en una dirección, se **desactiva** y el propietario del comercio recibe un correo. Reactívala cuando hayas arreglado tu servidor: su contador vuelve a cero. - El envío de prueba solo se intenta una vez y no cuenta en los fallos. - **Reenviar** vuelve a enviar el mismo evento (mismo `id`, mismos bytes), con una firma nueva. - **Al menos una vez, sin orden garantizado**: un evento puede llegar dos veces, elimina duplicados con `StampyWallet-Id`; dos eventos cercanos pueden llegar desordenados, guíate por `cree_le`. - Los envíos se conservan 30 días en el registro. | Estado de un envío | Significado | |---|---| | `en_attente` | Aún no se ha intentado | | `echec` | El último intento ha fallado; hay otro previsto | | `livre` | Se ha recibido un 2xx | | `abandonne` | Ocho fallos, o dirección desactivada, o sustituido por un reenvío | > **Sin código :** Zapier, Make y n8n reciben estos webhooks tal cual: pega la dirección de su disparador «Webhook» como dirección. Los pasos a seguir están en [Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/#sans-code). Source : https://stampywallet.com/es/docs/api/webhooks/ --- # Lista de eventos Los nueve eventos que envían los webhooks de StampyWallet, cuándo salen y el contenido exacto de su campo donnees. Cada evento tiene el mismo sobre (`id`, `type`, `cree_le`, `commerce`, ver [Webhooks](https://stampywallet.com/es/docs/api/webhooks/#requete)). Solo cambia `donnees`, que se muestra solo a continuación. Los eventos salen tanto del mostrador como de la API: una visita escaneada o puesta con [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/) produce el mismo `passage.cree`. | Evento | Se envía cuando | |---|---| | `client.cree` | Un cliente se une al programa (se crea su tarjeta) | | `carte.ajoutee` | El cliente guarda su tarjeta en Apple Wallet o Google Wallet | | `passage.cree` | Se pone una visita: uno o varios sellos, o puntos | | `passage.annule` | Se anula la última visita de un cliente | | `recompense.atteinte` | Una visita supera un nivel: se debe una recompensa (una por nivel superado) | | `recompense.offerte` | La recompensa se entrega al cliente | | `recompense.annulee` | Se anula la entrega de una recompensa: vuelve a estar pendiente | | `carte_cadeau.vendue` | Se vende una tarjeta regalo | | `forfait.vendu` | Se vende un bono prepagado | > **Nota :** `carte.ajoutee` vale para Apple Wallet y Google Wallet: `donnees.carte.wallet` es `apple` o `google`. En Apple, el evento sale con cada dispositivo nuevo (un iPhone y luego un reloj generan dos). Quitar la tarjeta no envía nada. ## client.cree ```json title="donnees" { "client": { "id": "3374a06e-9608-4376-91cb-1a3fb6721b04", "prenom": "Camille", "cree_le": "2026-10-22T05:52:45.664Z" } } ``` `telephone` y `email` solo aparecen si el cliente los ha dado. `prenom` puede ser `null`. ## carte.ajoutee ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "carte": { "wallet": "apple" } } ``` ## passage.cree ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "passage": { "id": "226fdea1-ba59-49fb-93e6-60a14a765134", "quantite": 1, "montant": null, "devise": "EUR", "reference": "caisse-1", "source": "scan", "piste": "normal", "tampons": 1, "objectif": 2 } } ``` - `quantite`: lo que vale la visita (sellos, o puntos en modo puntos). - `montant`: el importe del ticket en céntimos si se ha introducido; si no, `null`. - `reference`: el identificador de operación enviado por quien llama (la referencia de la API o la del mostrador); si no, `null`. - `source`: `scan`, `manuel`, `api`… - `piste`: `normal`, o `premium` para el segundo contador. - `tampons` (o `points` en modo puntos) y `objectif`: el contador **después** de la visita. Una visita que completa la tarjeta devuelve el de la tarjeta siguiente (a menudo `0`); la recompensa llega en un `recompense.atteinte` aparte. ## passage.annule ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "passage": { "id": "d8f62d77-88a6-44ef-a0c3-2a7d5066b90a", "quantite": 1, "source": "scan", "piste": "normal", "tampons": 0, "objectif": 2 }, "recompenses_retirees": 0, "motif": "doble escaneo" } ``` `passage.id` es el del `passage.cree` original, y el contador el de después de la anulación. `recompenses_retirees`: las recompensas que esta visita había desbloqueado y que desaparecen con ella. `motif`: el motivo introducido en el mostrador, o `null`. ## recompense.atteinte ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "recompense": { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café gratis", "palier": 2, "piste": "normal", "expire_le": null }, "passage_id": "8bfbdd5e-eff4-4a3b-94fe-1557ec6edce6" } ``` Un evento por nivel superado. `expire_le` vale `null` si las recompensas del comercio no caducan. ## recompense.offerte ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "recompense": { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café gratis", "piste": "normal", "offerte_le": "2026-10-22T05:54:51.790Z" } } ``` ## recompense.annulee ```json title="donnees" { "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès", "telephone": "+33611223344", "email": "ines@example.com" }, "recompense": { "id": "504c8734-3bbd-4fe9-95f8-7a67c8239dab", "libelle": "Un café gratis", "piste": "normal" }, "motif": "tarjeta equivocada" } ``` ## carte_cadeau.vendue ```json title="donnees" { "client": null, "carte_cadeau": { "id": "ac7e56a5-3c00-492f-971a-21ca7d675fd6", "code": "EJ9Y-7FYN", "sorte": "montant", "produit": null, "montant": 2500, "devise": "EUR", "pour": "Lucie", "de": "Marc", "canal": "comptoir", "expire_le": "2027-04-22T05:54:51.879Z" } } ``` `sorte` vale `montant` o `produit` (en ese caso `produit` lleva su nombre y `montant` su precio). Aquí, 2500 céntimos: 25 €. > **Atención :** `code` es el código de la tarjeta regalo, el que lleva su QR: basta para cobrarla en el mostrador. Trátalo como un secreto: no lo escribas en una hoja de cálculo compartida ni en registros. ## forfait.vendu ```json title="donnees" { "client": null, "forfait": { "id": "0ec29323-ed13-4e6b-9595-963601290eac", "code": "XFF2-WTW9", "nom": "10 cafés", "unites": 10, "prix": 3000, "devise": "EUR", "titulaire": "Paul", "canal": "comptoir", "expire_le": "2027-04-22T05:54:51.891Z" } } ``` `titulaire`: el nombre escrito en la venta, o `null`. `expire_le` vale `null` para un bono sin vencimiento. Como en una tarjeta regalo, `code` debe mantenerse en secreto. > **Nota :** los datos personales se limitan a lo que el cliente dio al registrarse. Una vez recibidos, son responsabilidad tuya: consérvalos solo el tiempo necesario. Source : https://stampywallet.com/es/docs/api/eventos/ --- # Recibir los eventos de tu TPV POST /v1/entrants/:jeton recibe las ventas de Square, Shopify, SumUp, Zettle o de cualquier herramienta, y añade la visita al cliente correcto. `POST /v1/entrants/:jeton` Una dirección que darle a tu TPV: en cada venta pagada, el TPV la llama y StampyWallet añade la visita a la tarjeta del cliente, encontrado por su correo o su teléfono. No hay clave que escribir en el TPV: basta con el token de la dirección. Una dirección desconocida o revocada responde `404`. ## Las fuentes Cada dirección se crea para una fuente en **Ajustes › Integraciones**, con una clave de firma opcional. StampyWallet lee entonces el formato de ese TPV tal cual: | Fuente | Lo que cuenta | Cliente | Importe | Referencia | |---|---|---|---|---| | `square` | `payment.created` / `payment.updated` con estado `COMPLETED` | Correo del comprador, o correo y teléfono del cliente | Sin propina | El id del pago | | `shopify` | `orders/paid` | Correo y teléfono del cliente o del pedido | Subtotal del pedido | El id del pedido | | `sumup` (beta) | Transacción `PAID` o `SUCCESSFUL` | Correo o teléfono | Importe de la transacción | Código de transacción | | `zettle` (beta) | `PurchaseCreated` | Correo o teléfono del cliente | Importe de la compra | El id de la compra | | `generique` | El cuerpo de [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/) | `client` | `montant` | `reference` (opcional) | > **Nota :** las fuentes de los TPV **nunca crean clientes**: una venta sin cliente conocido se ignora. Una venta sin correo ni teléfono, o sin referencia, también se ignora. Solo la fuente `generique` puede crear un cliente, con `creer_si_absent: true`. ## La firma Cuando hay una clave de firma guardada para la dirección, cada llamada debe ir firmada; si no, `401 signature_invalide`. Pégala siempre que el TPV proporcione una. | Fuente | Cabecera | Firma | |---|---|---| | `generique` | `X-Stampy-Signature` | HMAC-SHA256 hexadecimal del cuerpo sin procesar, con la clave de la dirección (se acepta `sha256=` delante) | | `square` | `x-square-hmacsha256-signature` | HMAC-SHA256 base64 de la URL de notificación seguida del cuerpo sin procesar | | `shopify` | `X-Shopify-Hmac-Sha256` | HMAC-SHA256 base64 del cuerpo sin procesar | | `sumup` | `X-Payload-Signature` | HMAC-SHA256 hexadecimal del cuerpo sin procesar | | `zettle` | `X-iZettle-Signature` | HMAC-SHA256 hexadecimal de `timestamp + "." + payload` | ## El formato genérico Para un script, una herramienta sin código o un TPV sin formato conocido, envía el mismo cuerpo que [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/): ```bash title="curl" corps='{"client": {"telephone": "+33612345678"}, "montant": 18.9, "reference": "T-2026-1025-0091"}' signature=$(printf '%s' "$corps" | openssl dgst -sha256 -hmac "$STAMPY_ENTRANT_SECRET" | sed 's/^.* //') curl https://app.stampywallet.com/v1/entrants/9QkT2vX7pL4mR8sN1bC6dF3gH5jK0wYz \ -H "Content-Type: application/json" \ -H "X-Stampy-Signature: $signature" \ -d "$corps" ``` ```js title="Node.js" const crypto = require('node:crypto'); const corps = JSON.stringify({ client: { telephone: '+33612345678' }, montant: 18.9, reference: 'T-2026-1025-0091' }); const signature = crypto.createHmac('sha256', process.env.STAMPY_ENTRANT_SECRET).update(corps).digest('hex'); await fetch(process.env.STAMPY_ENTRANT_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Stampy-Signature': signature }, body: corps, }); ``` ## Las respuestas Una vez autenticada la llamada, la respuesta es siempre `200`, para que el TPV no averigüe nada de tu fichero de clientes: - `{ "ok": true, "ignore": true }`: el evento no nos concierne (no pagado, otro asunto, sin cliente, o sin referencia en el caso de un TPV); - `{ "ok": true }`: en todos los demás casos, exista o no el cliente, y se haya puesto o rechazado la visita (demasiado pronto, importe demasiado bajo). Solo una avería real responde `500`: el TPV reintenta, y la referencia garantiza que un nuevo intento no sella dos veces. Cada dirección acepta 300 llamadas por minuto. Los ajustes paso a paso, TPV por TPV: [Conectar tu TPV](https://stampywallet.com/es/docs/api/conectar-tu-tpv/). Source : https://stampywallet.com/es/docs/api/entrantes/ --- # Conectar tu TPV Los ajustes paso a paso para que Square, Shopify, SumUp, Zettle, Zapier, Make o n8n añadan un sello en cada venta, sin desarrollador. Conectar tu TPV es darle una dirección de StampyWallet a la que llamar en cada venta pagada. La visita se añade entonces sola a la tarjeta del cliente, encontrado por su teléfono o su correo. No hace falta nada para empezar: el escaneo en el mostrador basta, y el TPV es un extra, sobre todo para una [tarjeta de puntos](https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/#points). > **Nota :** el TPV solo conoce al cliente si tiene su teléfono o su correo (ficha de cliente, ticket enviado por correo, pedido en línea), y el cliente ya debe tener su tarjeta de StampyWallet: un TPV nunca crea clientes. Una venta anónima se ignora: para ella, el escaneo en el mostrador sigue siendo lo adecuado. ## Primero, en StampyWallet 1. **Abre Ajustes › Integraciones** y elige **Recibir las ventas de un TPV**. 2. **Elige el TPV** (Square, Shopify, SumUp, Zettle, u «Otro» para el formato genérico). 3. **Copia la dirección** creada, con la forma `https://app.stampywallet.com/v1/entrants/ent_…`. ## Luego, en tu TPV **Square** 1. Abre el **Square Developer Dashboard**, crea una aplicación (o abre la tuya) y luego **Webhooks › Subscriptions › Add subscription**. 2. Pega la dirección de StampyWallet como **Notification URL** y marca los eventos **`payment.created`** y **`payment.updated`**. 3. Copia la **Signature key** de la suscripción y pégala en Ajustes › Integraciones. 4. Solo cuentan los pagos que pasan a `COMPLETED`. **Shopify** 1. En la administración de Shopify: **Configuración › Notificaciones › Webhooks › Crear webhook**. 2. Evento: **Pago de pedido** (`orders/paid`), formato **JSON**, dirección: la de StampyWallet. 3. Copia el secreto que aparece bajo la lista de webhooks («Tus webhooks se firmarán con…») y pégalo en Ajustes › Integraciones. 4. El cliente se encuentra por el correo o el teléfono del pedido. **SumUp** 1. SumUp envía sus notificaciones de transacción a la dirección indicada por una aplicación vinculada a tu cuenta. Desde tu espacio de desarrollador de SumUp, declara la dirección de StampyWallet para las transacciones correctas. 2. Pega en Ajustes › Integraciones el secreto de firma proporcionado, si lo hay. 3. Beta: escríbenos si no llega una venta, lo revisamos contigo. **Zettle** 1. Zettle (PayPal) envía sus eventos mediante su API de webhooks: crea una suscripción al evento de compra creada (`PurchaseCreated`) hacia la dirección de StampyWallet. 2. Pega en Ajustes › Integraciones la clave de firma de la suscripción. 3. Beta: escríbenos si no llega una venta. ## Sin código: Zapier, Make, n8n En los dos sentidos: una herramienta sin código puede **enviar** a StampyWallet las ventas de un TPV que conozca, o **recibir** los eventos de StampyWallet para rellenar una hoja de cálculo, un CRM o una lista de correo. **Zapier** **Enviar una venta a StampyWallet** 1. Disparador: tu TPV o tu tienda («New Payment», «New Order»…). 2. Acción: **Webhooks by Zapier › POST**, URL: la dirección «Otro» (formato genérico), tipo de datos: JSON. 3. Cuerpo: `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}` (o `email` en lugar de `telephone`), siendo la referencia el número de la venta. **Recibir los eventos de StampyWallet** 1. Disparador: **Webhooks by Zapier › Catch Hook**. Copia la dirección del hook. 2. Pégala como punto de recepción en Ajustes › Integraciones ([Webhooks](https://stampywallet.com/es/docs/api/webhooks/)) y haz clic en «Enviar una prueba». **Make** **Enviar una venta a StampyWallet** 1. Módulo de tu TPV como disparador y luego módulo **HTTP › Make a request**. 2. Método `POST`, URL: la dirección «Otro», cuerpo JSON `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}`, como [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/). **Recibir los eventos de StampyWallet** 1. Módulo **Webhooks › Custom webhook**, copia la dirección. 2. Pégala como punto de recepción en Ajustes › Integraciones y luego «Enviar una prueba» para que Make aprenda la estructura. **n8n** **Enviar una venta a StampyWallet** 1. Nodo de tu TPV como disparador y luego nodo **HTTP Request**. 2. Método `POST`, URL: la dirección «Otro», cuerpo JSON `{"client": {"telephone": "…"}, "montant": …, "reference": "…"}`, como [`POST /v1/passages`](https://stampywallet.com/es/docs/api/anadir-visita/). **Recibir los eventos de StampyWallet** 1. Nodo **Webhook** (método POST), copia la dirección de producción. 2. Pégala como punto de recepción en Ajustes › Integraciones. Para verificar la firma, añade un nodo **Code** con el ejemplo de Node.js de la página [Webhooks](https://stampywallet.com/es/docs/api/webhooks/#signature). ## Otro TPV Si tu TPV sabe llamar a una dirección en cada venta (muchos lo hacen, con el nombre de «webhook» o «notificación»), usa la dirección «Otro» y el [formato genérico](https://stampywallet.com/es/docs/api/entrantes/#le-format-generique). Si no, escríbenos desde la página de [contacto](site:contact/): lo revisamos contigo. ## Preguntas frecuentes **¿Funciona con mi TPV?** Los ajustes están listos para Square, Shopify, SumUp y Zettle. Cualquier otro TPV que sepa llamar a una dirección en cada venta pasa por el formato genérico, y un TPV que Zapier, Make o n8n conozcan puede pasar por ellos. Si no, escríbenos: lo miramos contigo. **¿Necesito un desarrollador?** No. Copias una dirección en StampyWallet, la pegas en tu TPV y luego pegas en StampyWallet el secreto de firma que te da el TPV, si lo hay. **¿Mi cliente tiene que tener ya su tarjeta?** Sí. Un TPV nunca crea clientes: encuentra la tarjeta por el teléfono o el correo del cliente. Una venta anónima se ignora, y entonces el escaneo en el mostrador sigue siendo el gesto correcto. **¿Una venta puede contar dos veces?** No. Cada venta lleva su referencia: si el TPV reintenta después de un corte, la visita no se añade una segunda vez. **¿La conexión del TPV está incluida en mi suscripción?** Forma parte del plan Crecimiento, a 40 € sin IVA al mes, y está abierta durante la prueba gratuita de 30 días. No está incluida en el plan Esencial. Source : https://stampywallet.com/es/docs/api/conectar-tu-tpv/ --- # Instalar el skill «tarjetas bonitas» Un archivo Markdown que enseña a tu asistente de IA a diseñar las tarjetas de fidelidad de un comercio como lo hacemos nosotros: sus imágenes reales primero, las catorce formas de tarjeta, iconos que cuentan la recompensa y una revisión antes de enseñarlas. https://stampywallet.com/es/docs/skill.md ## Instalación **Claude** 1. **Descarga** [skill.md](skill.md). 2. En Claude, abre **Configuración › Capacidades › Skills** y añade el archivo (Claude acepta una carpeta comprimida que contenga `SKILL.md`: cambia el nombre del archivo si la interfaz lo pide). 3. **Añade el conector de StampyWallet** (`https://app.stampywallet.com/mcp`) para que las tarjetas se generen de verdad: [Conectar Claude](https://stampywallet.com/es/docs/mcp/claude/). 4. Pide: «Diseña las tarjetas de fidelidad de [nombre del comercio, ciudad].» **ChatGPT** 1. **Copia** el archivo (botón Copiar de arriba). 2. En un **Proyecto de ChatGPT**, pégalo en las instrucciones del proyecto. 3. **Añade el conector de StampyWallet**: [Conectar ChatGPT](https://stampywallet.com/es/docs/mcp/chatgpt/). 4. En una conversación del proyecto: «Diseña las tarjetas de fidelidad de [nombre del comercio].» **Cursor y agentes** 1. Dale a tu agente la dirección directa: `https://stampywallet.com/es/docs/skill.md`, o copia el archivo en la carpeta de skills o de reglas de tu agente (por ejemplo `.claude/skills/belles-cartes/SKILL.md` para Claude Code). 2. Añade el servidor MCP `https://app.stampywallet.com/mcp` a su configuración: [Cursor y agentes](https://stampywallet.com/es/docs/mcp/cursor/). 3. Pide: «Lee el skill y luego diseña las tarjetas de fidelidad de este comercio.» ## Lo que contiene el archivo ```markdown title="skill.md" --- name: tarjetas-de-fidelidad-bonitas description: Diseñar al menos 12 versiones de la tarjeta de fidelidad de un comercio, con sus imágenes reales, a través del MCP de StampyWallet, revisadas una a una. --- # Tarjetas de fidelidad bonitas ## 1. Conocer el comercio ## 2. Encontrar sus imágenes reales ## 3. Generar al menos 12 versiones, de todos los tipos ## 4. Revisar cada tarjeta, en grande ## 5. Presentar la elección ## 6. Ponerla en marcha ``` El método, paso a paso: [Lo que hace el skill](https://stampywallet.com/es/docs/skill/metodo/). ## Preguntas frecuentes **¿Hace falta una cuenta de StampyWallet?** No. El skill y la herramienta `concevoir_carte` funcionan sin cuenta. La cuenta solo sirve para poner la tarjeta en marcha, y la herramienta `creer_commerce` la crea por ti. **¿El skill funciona sin el servidor MCP?** Guía al asistente, pero sin el servidor MCP este no puede generar imágenes reales de la tarjeta: solo las describe. **¿Puedo modificarlo?** Sí, es un simple archivo Markdown. Mantén la regla de las imágenes reales y la revisión: son las que marcan la diferencia. **¿Se guardan las imágenes del comercio?** No. `concevoir_carte` las muestra en la vista previa sin guardar nada. Solo se ponen en la tarjeta si el comerciante la pone en marcha. Source : https://stampywallet.com/es/docs/skill/ --- # Lo que hace el skill Las catorce formas de tarjeta, las imágenes reales primero, los iconos con licencia cuando las fotos no encajan y la revisión de cada tarjeta antes de enseñarla. ## Las catorce formas El skill pide al menos doce versiones, una por cada forma del motor de tarjetas, para que el comerciante vea todo lo posible antes de elegir: | Modo | Formas | Para qué | |---|---|---| | Sellos | cuadrícula, círculos, libre, objetos | Una recompensa al cabo de N visitas | | Varias recompensas | camino, vitrina, medallas, relleno, anillo | Recompensas cada vez mejores | | Puntos | relleno, anillo, camino, vitrina, medallas | Puntos según lo que gasta el cliente | Cada forma se genera con [`concevoir_carte`](https://stampywallet.com/es/docs/mcp/herramientas/concevoir_carte/), parámetros `mode` y `forme`. El detalle de los modos: [Los tipos de tarjeta](https://stampywallet.com/es/docs/guia/tipos-de-tarjeta/). ## Las imágenes reales primero El logo del comercio (`logo_url`) y las fotos de sus productos (`paliers[].image_url`) van antes que cualquier ilustración. Si no se indica un color, la tarjeta toma los colores del logo. Las fotos de recompensa se recortan, en gris antes de ganarlas y en color después. > **Atención :** las imágenes de un comerciante sirven para SU tarjeta, la que se le propone. No se publican en ningún otro sitio, y una ilustración nunca se presenta como una foto del comercio. ## Iconos y licencias Cuando una foto no encaja con una recompensa (borrosa, fuera de tema, ilegible una vez reducida), el skill busca un icono o una ilustración que cuente la recompensa a primera vista, con licencia clara: - iconos **Lucide**, **Phosphor**, **Tabler** (MIT o ISC), recoloreados con los colores del comercio; - fotos e ilustraciones de **Unsplash** o **Pexels**; - o uno de los sesenta y tantos iconos integrados (`paliers[].icone`). ## Revisar cada tarjeta Antes de enseñarla, cada tarjeta se abre en grande: nombre completo, recompensas legibles y sin cortar, texto con contraste, logo nítido, fotos reconocibles incluso en gris. Una tarjeta que falla se rehace. ## Presentar y luego poner en marcha Una lámina numerada por tipo, una línea por versión, y siempre la misma frase: cada imagen y cada icono se puede cambiar. El comerciante elige un número; solo entonces [`creer_commerce`](https://stampywallet.com/es/docs/mcp/herramientas/creer_commerce/) pone la tarjeta en marcha (vista previa y luego aprobación). ![Ejemplo de lámina de tarjetas](https://placehold.co/600x400 "Una lámina numerada: una tarjeta por forma, ordenadas por tipo.") Source : https://stampywallet.com/es/docs/skill/metodo/