Guía de usuario
Conectar un tercero
Esta es la versión para quien administra. Vas a crear una llave, decidir qué puede hacer con ella y entregársela a quien va a programar — sin escribir una línea de código. Unos 10 minutos, más el trámite del aviso de privacidad si aplica.
Tú creas la llave; tu proveedor la usa. Toda la parte técnica —cómo se llama, qué contesta, cómo se reintenta— está en la guía de API. Mándale ese enlace junto con la llave y no vas a tener que traducir nada.
Antes de nada: ¿va a recibir nombres y correos?
De esta pregunta depende que la siguiente media hora sea rápida o que tengas que esperar una semana. Léela con calma.
Cada tercero que recibe nombre y correo de tu gente es una transferencia de datos personales. Bajo la ley mexicana, tiene que estar nombrado en tu aviso de privacidad antes del primer dato que le mandemos.
Y no se arregla después: los consentimientos que ya recabaste quedaron sellados contra la versión del aviso que cada persona aceptó, y esa versión no lo mencionaba. Agregarlo hoy aplica a quien se registre de hoy en adelante, no a tu padrón actual. Cómo funciona el sellado.
Por eso el panel no te deja crear una llave con permisos de identidad sin que confirmes que tu aviso ya nombra a ese tercero. No es una casilla de trámite: es la que te protege si alguien pregunta.
La buena noticia: muchas integraciones no necesitan identidad. Un punto de venta que acredita puntos no necesita saber cómo se llama nadie — le basta el número de socio. Si tu proveedor pide nombres y correos, pregúntale para qué; la mitad de las veces la respuesta es «por si acaso», y eso no justifica una transferencia.
1 Crea la integración
En ⚙️ Configuración → 🔌 Integraciones con terceros → ➕ Nueva integración. Cuatro decisiones:
| Campo | Qué poner |
|---|---|
| Nombre del socio | Cómo lo vas a reconocer en la bitácora. El nombre de la empresa, no el del contacto |
| Tipo | Punto de venta, boletera, CRM u otro. Es organizativo |
| Modo | Prueba siempre la primera vez. Guarda lo que mandan para que lo veas, pero no mueve saldos reales |
| Permisos | Solo lo que necesiten. La tabla de abajo |
Los permisos, y cuáles cuestan trámite
| Permiso | Deja hacer | ¿Recibe nombre y correo? | Estado |
|---|---|---|---|
fan:leer |
POST /api/v1/fan/resolve | Sí — requiere aviso | En producción |
tx:escribir |
POST /api/v1/tx | No | En producción |
redeem:escribir |
POST /api/v1/redeem | No | En producción |
codigos:escribir |
POST /api/v1/codes | No | En producción |
roster:leer |
GET /api/v1/roster | Sí — requiere aviso | En producción |
Un caso que no es obvio: el dueño del inventario. Si tus códigos de promoción los emite un patrocinador o tu punto de venta, puedes darle una llave con el permiso de inventario y que deposite sus lotes él mismo, en vez de mandarte un archivo que alguien tenga que pegar. No necesita identidad, así que no hay trámite de aviso.
Esa llave no le deja crear promociones: eso se queda en tu panel. Puede llenar el inventario de una promoción que tú creaste, y consultarlas para saber a cuál mandar. La decisión de qué se promociona sigue siendo tuya.
Empieza con menos de lo que te pidan. Agregar un permiso después es rotar la llave, que toma un minuto. Quitar uno que ya usaron en producción rompe su integración un viernes. La conversación incómoda es más barata al principio.
2 Entrega la llave
Al crearla, la llave se muestra una sola vez. De ahí en adelante solo guardamos su huella: ni tú ni nosotros podemos volver a leerla.
Una llave es una contraseña. No la mandes por WhatsApp ni la pegues en un correo que va a quedar en la bandeja de cinco personas. Un gestor de contraseñas, o una llamada. Si dudas de cómo llegó, rótala: es gratis y toma un minuto.
Mándale a tu proveedor tres cosas y nada más:
- La llave.
- El enlace a la guía de API.
- Una frase: «la primera llamada debe ser
ping; contesta contra qué programa quedaste y con qué permisos».
Cómo verificas que quedó
La integración aparece en la lista con su pista de llave. En cuanto tu proveedor haga su primera llamada, la fila muestra la última llamada, cuántas van en 24 horas y cuántas con error. Mientras diga «Todavía sin usar», no han empezado.
3 Acompáñalos en las pruebas
Mientras la llave esté en modo prueba, todo lo que manden se guarda pero no mueve saldos. Es el momento de mirar la bitácora juntos: cada llamada con su ruta, su código de respuesta, cuánto tardó y un resumen.
Esa bitácora es tu mejor herramienta en esta relación. Cuando tu proveedor diga «se los mandamos y no llegó», la respuesta está ahí en cinco segundos y sin pedirle registros a nadie. Se conserva 30 días.
Cuando las pruebas cuadren, crea una llave nueva en modo en vivo y entrégasela. Su código no cambia: solo el valor de la llave.
4 Mantén el acceso
Dos botones, y no hacen lo mismo:
| Botón | La llave anterior | Cuándo |
|---|---|---|
| Rotar llave | Sigue funcionando 7 días | Mantenimiento: cambio de proveedor, rotación periódica, ajustar permisos. La ventana existe para que puedan cambiarla sin cortarles el servicio — sin ella, nadie rota nunca |
| Revocar | Muere de inmediato | El botón del incidente. Si crees que la llave se filtró, o si terminaste la relación hoy, es este |
Revocar no borra la bitácora. Lo que ese socio hizo mientras tuvo acceso sigue siendo consultable, que es justo lo que necesitas si la separación fue por algo.
Qué sale mal, y por qué
«Perdí la llave»
No se puede recuperar — solo guardamos su huella. Rótala y entrega la nueva. Si el socio todavía tiene la anterior funcionando, tiene siete días para cambiarla sin interrupción.
«El panel no me deja marcar el permiso que necesitan»
Es un permiso que recibe nombre y correo, y falta la confirmación del aviso de privacidad. Primero agrega a ese tercero a tu aviso, después crea la llave. Cómo se edita el aviso.
«Están recibiendo muchos errores»
Mira la bitácora: el código de respuesta dice de qué lado está el problema. Los de autorización son de la llave o los permisos —tuyos—; los de formato son de su código. Pásales el catálogo de errores, que explica qué hacer con cada uno.
«Un código de cupón se rechazó en su terminal»
Es a propósito y es información valiosa: alguien presentó un cupón que ya había salido de circulación o que nunca se entregó. Si el número crece, hay listas viejas circulando del lado del comercio. Está explicado en la guía de promociones.
«Quiero conectar un segundo proveedor»
Es otra llave, con sus propios permisos y su propia bitácora. No se estorban: los dos pueden usar los mismos identificadores internos sin pisarse. Y si uno recibe identidad, es una transferencia distinta que también tiene que estar nombrada.
Y después
Con el punto de venta conectado, los puntos empiezan a acumularse con el gasto real y no solo con las visitas. Ese es el momento de revisar tus tasas en la guía del Fan Pass: la tasa por compra es la que más mueve el saldo, y conviene tenerla pensada antes de que empiece a correr.