Saltar al contenido principal

Identificador del usuario final (end_user)

Cada pregunta enviada a /v1/ask debe traer end_user: un identificador opaco de la persona que preguntó en tu sistema. Datafala usa ese valor solo para contar usuarios activos por mes, que es la base de la mensualidad por tramo.

Qué enviar​

Un valor derivado del ID interno de la persona, nunca el dato personal. No envíes nombre, correo, CPF ni el ID en texto claro.

  • Formato: de 16 a 128 caracteres entre letras, números, _ y -. Se aceptan hexadecimal de SHA-256/HMAC (64 caracteres), base64url y UUID. Los correos, nombres, espacios e IDs cortos (como 42) se rechazan con 422 invalid_end_user.
  • Estable: la misma persona genera siempre el mismo valor, en todas las preguntas y en todos los meses.
  • Individual: nunca uses el mismo valor para dos personas (una cuenta de servicio o un usuario genérico admin). Un valor compartido cuenta como una sola persona y aparece en las señales de auditoría.
  • Secreto fijo: genera el valor con un secreto que quede solo en tu servidor (DATAFALA_END_USER_SECRET).
No cambies el secreto

Después de un cambio, cada persona pasa a generar otro valor y se cuenta de nuevo en el mes del cambio, lo que modifica el tramo de la factura.

Ejemplos​

Python:

import hashlib
import hmac
import os

SECRET = os.environ["DATAFALA_END_USER_SECRET"].encode()


def datafala_end_user(user_id: int | str) -> str:
    return hmac.new(SECRET, str(user_id).encode(), hashlib.sha256).hexdigest()

Node.js:

import { createHmac } from "node:crypto";

export function datafalaEndUser(userId) {
  return createHmac("sha256", process.env.DATAFALA_END_USER_SECRET)
    .update(String(userId))
    .digest("hex");
}

PHP:

function datafala_end_user(string|int $userId): string {
    return hash_hmac('sha256', (string) $userId, getenv('DATAFALA_END_USER_SECRET'));
}

Un UUID público y estable del usuario también sirve, siempre que no cambie con el tiempo.

Para generar el secreto una sola vez:

python3 -c "import secrets; print(secrets.token_hex(32))"

Obligatoriedad y límite​

  • Si tu tenant exige el campo y la pregunta llega sin él, la respuesta es 400 end_user_required. Los clientes nuevos ya empiezan exigiéndolo.
  • Cada end_user puede hacer 10 preguntas por minuto. Por encima, 429 rate_limited con details.scope = "end_user".
  • Las solicitudes rechazadas con 429 no cuentan como usuario activo. Las preguntas que fallan al generarse (sql_rejected, no_answer, llm_error) sí cuentan, porque la persona usó el sistema.

Privacidad​

El valor recibido no entra en logs, respuestas, historial ni métricas. Se guarda solo como HMAC-SHA256 con una sal propia de tu tenant, nunca vinculado a una pregunta, y los registros de conteo se borran después de 13 meses.