Pular para o conteúdo principal

Identificador do usuário final (end_user)

Cada pergunta enviada a /v1/ask deve trazer end_user: um identificador opaco da pessoa que perguntou no seu sistema. O Datafala usa esse valor só para contar usuários ativos por mês, que é a base da mensalidade por faixa.

O que enviar​

Um valor derivado do ID interno da pessoa, nunca o dado pessoal. Não envie nome, e-mail, CPF nem o ID em claro.

  • Formato: de 16 a 128 caracteres entre letras, números, _ e -. Hexadecimal de SHA-256/HMAC (64 caracteres), base64url e UUID são aceitos. E-mails, nomes, espaços e IDs curtos (como 42) são recusados com 422 invalid_end_user.
  • Estável: a mesma pessoa gera sempre o mesmo valor, em todas as perguntas e em todos os meses.
  • Individual: nunca use o mesmo valor para duas pessoas (uma conta de serviço ou um usuário genérico admin). Um valor compartilhado conta como uma pessoa só e aparece nos sinais de auditoria.
  • Segredo fixo: gere o valor com um segredo que fica só no seu servidor (DATAFALA_END_USER_SECRET).
Não troque o segredo

Depois de uma troca, cada pessoa passa a gerar outro valor e é contada de novo no mês da troca, o que muda a faixa da fatura.

Exemplos​

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'));
}

Um UUID público e estável do usuário também serve, desde que não mude com o tempo.

Para gerar o segredo uma vez:

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

Obrigatoriedade e limite​

  • Se o seu tenant exige o campo e a pergunta vier sem ele, a resposta é 400 end_user_required. Novos clientes já começam exigindo.
  • Cada end_user pode fazer 10 perguntas por minuto. Acima disso, 429 rate_limited com details.scope = "end_user".
  • Requisições recusadas com 429 não contam como usuário ativo. Perguntas que falham na geração (sql_rejected, no_answer, llm_error) contam, porque a pessoa usou o sistema.

Privacidade​

O valor recebido não entra em log, resposta, histórico nem métrica. Ele é guardado apenas como HMAC-SHA256 com um sal próprio do seu tenant, nunca ligado a uma pergunta, e os registros de contagem são apagados depois de 13 meses.