Del rollo al escaneo

Primeros pasos

1. Pedinos etiquetas. Nos decís cuántas unidades y para qué producto. Desde el panel podés cargar el pedido vos mismo: nos llega, generamos los códigos y mandamos a imprimir.
2. Cargá tu producto y tu lote. Mientras se imprime. Nombre, presentación, número de lote y vencimiento si corresponde.
3. Recibí el rollo y confirmalo. Marcarlo como recibido es lo que lo pone bajo tu custodia, y deja registro de cuándo.
4. Aplicá y activá. Pegás las etiquetas durante el empaque y activás el rango en el panel. Hasta ese momento ninguna de esas unidades autentica.
5. Mirá los escaneos. Aparecen en vivo, con país, estado y hora. Las alertas se generan solas.

El orden del paso 4 importa: activar antes de aplicar significa que un rollo que se pierde en el camino tiene unidades que sí autentican. Activá cuando la etiqueta ya está sobre el producto.

Qué ve el comprador

Escanea el QR con la cámara del teléfono y se abre una página en el navegador. No hay app que instalar y no se le pide ningún dato. La página pesa menos de 30 KB para que cargue en una góndola con una barra de señal.

Rollos y etiquetas

Los códigos los generamos nosotros y viajan cifrados hasta la imprenta. Vos nunca tenés que manipular un archivo de millones de códigos, y quien imprime nunca ve a qué cliente pertenecen: el código no lleva la marca adentro.

Cada rollo trae un rango de series y un estado. El estado es lo que se audita cuando algo no cierra.

Si te roban un rollo, marcalo como robado en el panel. Todas sus unidades dejan de autenticar en el acto, incluso las que ya estaban activadas, y cada intento de verificarlas te queda registrado con país y hora — que es cómo se rastrea por dónde salieron.

Productos, lotes y activación

Un producto es lo que vendés; un lote es una corrida de producción de ese producto; una unidad es un envase con su etiqueta. Las alertas, el retiro y los informes trabajan sobre el lote, así que conviene que el lote del panel sea el mismo que el de tu sistema de producción.

La activación se hace de tres formas, todas desde el panel:

• Por rango — de la serie X a la Y. Es lo normal cuando se consume un rollo entero.
• Por rollo — el rango completo de un rollo recibido, de un clic.
• Por unidad — para reposiciones y muestras.

Cada activación queda en el registro de auditoría con quién la hizo y cuándo. Ese registro está encadenado por hash: no se puede editar después sin que se note, que es justo lo que pide un auditor.

Retiro de lote

Marcás el lote como retirado y el siguiente escaneo de cualquiera de sus unidades muestra la alerta sanitaria en lugar de "producto verificado". Tarda segundos en propagarse a todo el mundo y no requiere reimprimir ni recolectar nada.

Es reversible: si el retiro fue precautorio y se levanta, el lote vuelve a verificar normalmente. Las dos operaciones quedan auditadas.

Anomalías y casos

Hay once reglas mirando el flujo de escaneos. Las que más se disparan en la práctica:

• Reescaneo — una misma unidad verificada muchas veces, sobre todo desde lugares distintos.
• Imposibilidad geográfica — dos escaneos tan separados que nadie pudo viajar entre ellos.
• Desvío de territorio — producto asignado a un mercado apareciendo en otro. Es fuga de canal, no falsificación, y se distingue.
• Ráfaga de lote — un pico de escaneos concentrado en un lote y una zona.
• Rollo robado — cualquier intento sobre un rango denunciado.

Cada alerta llega con su evidencia —qué unidades, dónde, cuándo— y se puede convertir en un caso: se le asigna un responsable, se le agregan notas y adjuntos, y se cierra con una resolución. El caso es lo que después se le muestra a un abogado, a una aduana o a un distribuidor.

Usuarios y roles

Los datos de cada marca están aislados en la base, no en la aplicación: aunque un error de programación pidiera datos de otra empresa, la base no los devuelve.

API

Verificación pública. Es la misma que usa la página del QR. No lleva autenticación —tiene que funcionar desde el teléfono de cualquier comprador— y no revela a qué marca pertenece el código.

GET https://xyvona.com/api/v/K7M2QX9J4TB8WNPC5RDA

{
  "result": "genuine",
  "message": "Producto verificado.",
  "product_id": 412,
  "batch_id": 88
}

Cuando la unidad ya fue vista antes, la respuesta agrega first_seen y first_country. Cuando no verifica, el cuerpo es sólo result y message: no se filtra si el código no existe, si no está activado o si el rollo fue robado, porque esa diferencia es exactamente lo que un falsificador necesita para calibrar.

API del panel. Todo lo que hace el panel tiene su endpoint. Se autentica con una llave que generás vos, con su propio alcance, y que se muestra una sola vez.

curl https://xyvona.com/capi/api/v1/batches \
  -H "X-API-Key: $XYVONA_API_KEY"

Guardá la llave apenas se genera: no volvemos a mostrarla y no la podemos recuperar. Si se pierde, se revoca y se emite otra — que es lo que debe pasar cuando una credencial se extravía.

Webhooks

Registrás una URL y te avisamos cuando se genera una alerta, filtrando por severidad mínima y por tipo. Los reintentos van con espera creciente y cada entrega queda en un registro que podés consultar cuando tu equipo diga "no nos llegó".

POST https://tu-sistema.com/hooks/xyvona
X-Xyvona-Signature: t=1755820800,v1=9f86d081...

{
  "version": 1,
  "type": "alert.created",
  "tenant_id": 7,
  "alert": {
    "alert_type": "geo_impossible",
    "severity": "high",
    "severity_level": 4,
    "status": "open",
    "unit_id": 90210,
    "batch_id": 88,
    "created_at": "2026-08-21T14:03:11+00:00",
    "evidence": { "km": 8410, "hours": 1.5 }
  }
}

Verificá la firma antes de confiar en el cuerpo: es HMAC-SHA256 sobre «timestamp.cuerpo» con el secreto que te damos al registrar la URL. Rechazá lo que llegue con más de cinco minutos de antigüedad y compará la firma en tiempo constante.

Datos, exportación y retención

• Los datos son tuyos. Escaneos, unidades, lotes, alertas y casos se exportan en CSV cuando quieras, sin pedirlo por correo.
• Geolocalización, IP y huella de dispositivo se borran a los 90 días. No es configurable: es requisito legal.
• La IP nunca se guarda en claro. Se usa para resolver el país y se reemplaza por un hash con sal rotativa antes de escribir nada.
• El código completo nunca aparece en un registro. Ni en el nuestro ni en el que exportás.
• Todo viaja y se guarda cifrado, en infraestructura con certificación internacional de seguridad de la información, con claves propias de XYVONA y copias de resguardo.
• En farmacéutica el portal del comprador viene apagado y no se puede encender: asociar a una persona identificada con los medicamentos que escaneó es un dato de salud.

¿Falta algo acá?

Escribinos y lo agregamos. Si la pregunta te la hiciste vos, se la está haciendo otro.