Clientes verificados y compras desde tu servidor

Identificar a un cliente

Llama a identificar cuando tu cliente inicie sesión, se registre o compre: son datos que ya te compartió y que tu aviso de privacidad cubre. Puedes llamarlo en cada página; se manda una vez por sesión del navegador.

• Con firma: el perfil queda verificado y se une con su historial anónimo. Solo así dispara la alerta de cliente que regresa.
• Sin firma: se guarda como no verificado. No se une con perfiles verificados.

albunea('identificar', { externo: '42', email: '[email protected]', nombre: 'Ana', firma: '…', ts: 1762300000 });

Cómo se calcula la firma

• firma = HMAC-SHA256(secreto, externo + "." + ts), en hexadecimal minúscula.
• ts es la hora Unix en segundos del momento en que firmas; la firma vale 24 horas.
• Se calcula SIEMPRE en tu servidor. El secreto «alb_sec_…» nunca va en la página: guárdalo en una variable de entorno.
• Si tu página se guarda en caché, no pongas la firma en el HTML: pídela con fetch a un endpoint tuyo que responda con Cache-Control: no-store.

import { createHmac } from 'node:crypto';
const SECRETO = process.env.ALBUNEA_SECRETO; // alb_sec_…

export function firmarAlbunea(externo) {
  const ts = Math.floor(Date.now() / 1000);
  const firma = createHmac('sha256', SECRETO).update(`${externo}.${ts}`).digest('hex');
  return { externo: String(externo), firma, ts };
}

<?php
function albunea_firmar(string $externo): array {
    $ts = time();
    $firma = hash_hmac('sha256', $externo . '.' . $ts, getenv('ALBUNEA_SECRETO'));
    return ['externo' => $externo, 'firma' => $firma, 'ts' => $ts];
}

// Java 17+
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secreto.getBytes(UTF_8), "HmacSHA256"));
String firma = HexFormat.of().formatHex(mac.doFinal((externo + "." + ts).getBytes(UTF_8)));

hmac.new(secreto.encode(), f"{externo}.{ts}".encode(), hashlib.sha256).hexdigest()

Compras desde tu servidor

Manda cada compra también desde tu servidor, para que cuente aunque el navegador falle o un bloqueador la detenga. Se deduplica con la del navegador por transaction_id. Esta API está en Presagio y en los planes mayores.

• v: el valor de la cookie _alb de tu cliente. Guárdalo en el pedido al iniciar el pago y mándalo: así la compra se une a la visita que la originó.
• perfil.externo: el id del cliente en tu sistema. Desde el servidor es identificación de confianza y no necesita firma.
• Pago después (OXXO, depósito, contra entrega): manda «pedido_creado» al crear el pedido y «purchase» cuando se pague.
• Nunca bloquees el pago: espera 2 segundos como máximo e ignora los errores.

curl -X POST https://www.getalbunea.com/v1/servidor/eventos \
  -H "Authorization: Bearer $ALBUNEA_SECRETO" -H "Content-Type: application/json" \
  -d '{"v":"<cookie _alb, opcional>","perfil":{"externo":"42"},
       "eventos":[{"t":"purchase","p":{"transaction_id":"P-77","value":360,"currency":"MXN"}}]}'

export async function enviarCompraAlbunea(pedido, vid) {
  try {
    await fetch('https://www.getalbunea.com/v1/servidor/eventos', {
      method: 'POST',
      signal: AbortSignal.timeout(2000),
      headers: { Authorization: `Bearer ${process.env.ALBUNEA_SECRETO}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        v: vid || undefined,
        perfil: pedido.clienteId ? { externo: String(pedido.clienteId) } : undefined,
        eventos: [{ t: 'purchase', p: { transaction_id: String(pedido.id), value: pedido.total, currency: 'MXN' } }],
      }),
    });
  } catch { /* Albunea nunca detiene una venta */ }
}

El secreto del servidor

Lo encuentras en Ajustes › Secreto del servidor. Se muestra una sola vez al crearlo o rotarlo; Albunea guarda una huella, no el secreto. Si lo pierdes o crees que alguien más lo vio, genera uno nuevo: el anterior deja de funcionar en ese momento, así que cámbialo enseguida en tu servidor.