FivSense · Veridian

Documentação da API

Uma habilidade externa, consumida por HTTP, que entende o estado do humano, infere perfil e estilo de comunicação e prevê o próximo comportamento — validada por outcomes reais.

Obter uma API key Ver o contrato

Contrato v1.0.0 · base URL https://fivsense.vercel.app

Autenticação

Toda chamada aos endpoints /v1 autenticados usa o header Authorization: Bearer <api_key>. Cada chave pertence a um tenant e resolve o limite de requisições. A chave crua é exibida uma única vez no cadastro — guarde-a com segurança; nós guardamos apenas o hash.

Não tem chave ainda? Crie uma em segundos.

POST /v1/predict

Envia a conversa até o instante atual e recebe state, profile, communication_style e prediction. Stateless: cada request carrega a conversa que precisa. Adicione ?debug=1 para incluir explanation.

Requisição

POST /v1/predict
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "objective": "sale",
  "locale": "pt-BR",
  "conversation": [
    { "role": "agent",    "text": "Olá! Posso ajudar?" },
    { "role": "customer", "text": "Quanto custa? Achei caro." }
  ]
}

Resposta (compacta, numérica)

{
  "state": {
    "understanding": 0.62, "confusion": 0.18, "trust": 0.44,
    "interest": 0.71, "hesitation": 0.55, "frustration": 0.12,
    "commitment": 0.33,
    "objections": [{ "type": "price", "strength": 0.7, "confidence": 0.8 }]
  },
  "profile": {
    "decision_style": "analytical", "directness": 0.6,
    "detail_orientation": 0.7, "skepticism": 0.5,
    "risk_sensitivity": 0.6, "decisiveness": 0.4, "confidence": 0.75
  },
  "communication_style": {
    "preferred_tone": "consultative", "preferred_verbosity": "medium",
    "preferred_detail_level": "high", "evidence_preference": "data",
    "recommended_pace": "medium", "question_style": "open"
  },
  "prediction": {
    "will_reply": 0.82, "will_convert": 0.41,
    "will_abandon": 0.22, "needs_human": 0.15
  }
}

objectivesale · support · collection · retention · scheduling · other

localeBCP-47, ex.: pt-BR (padrão)

conversation[]1..200 mensagens { role: agent|customer, text (1..4000), ts? }

objections.type (taxonomia fechada v1): price, trust, timing, need, competitor, decision_authority, risk, missing_information, priority, other.

POST /v1/outcomes

Fecha o flywheel (P9): devolva o que de fato aconteceu ligado ao prediction_id. Outcomes reais são o ground truth — é o que torna as probabilidades calibradas ao longo do tempo.

Requisição

POST /v1/outcomes
Authorization: Bearer <api_key>

{ "prediction_id": "...", "replied": true, "converted": false }

POST /v1/signup — onboarding self-serve

Provisiona um tenant e emite uma api_key na hora, sem processo humano (P10). Não coletamos dados pessoais: só o nome da organização e um caso de uso opcional.

Requisição / resposta

POST /v1/signup
Content-Type: application/json

{ "organization": "Minha Empresa", "use_case": "sale" }

-> 201
{
  "tenant_id": "t_9f3c...",
  "api_key": "fv_live_...",   // mostrada só aqui — guarde agora
  "key_prefix": "fv_live_ab12cd",
  "rate_limit_per_min": 120,
  "docs_url": "/docs"
}

GET /v1/health

Verificação pública de disponibilidade. Retorna versão do schema.

GET /v1/health
-> { "ok": true, "service": "fivsense", "schema_version": "1.0.0" }

Rate limits & headers

O limite é por tenant, por minuto (janela fixa). Respostas trazem os headers padrão abaixo; ao exceder, o status é 429 com Retry-After.

X-RateLimit-Limit — cota por minuto do tenant.
X-RateLimit-Remaining — chamadas restantes na janela.
X-RateLimit-Reset — epoch (s) em que a janela zera.
X-Request-Id — id da requisição (ecoado se você enviar).
X-FivSense-Schema-Version — versão do contrato.

Erros

Todo erro sai no mesmo envelope JSON, com request_id para suporte.

{
  "error": {
    "code": "invalid_request",
    "message": "Falha na validação do corpo da requisição.",
    "details": [{ "path": "conversation.0.role", "message": "..." }]
  },
  "request_id": "..."
}

400 invalid_json / invalid_request
401 unauthorized — chave ausente ou inválida
429 rate_limited
500 internal_error

SDKs

Clientes finos oficiais para TypeScript e Python (predict + outcomes).

TypeScript · npm i @fivsense/sdk

import { FivSense } from "@fivsense/sdk";

const fv = new FivSense({ apiKey: process.env.FIVSENSE_API_KEY! });
const out = await fv.predict({
  objective: "sale",
  conversation: [{ role: "customer", text: "Achei caro." }],
});
console.log(out.prediction.will_convert);

Python · pip install fivsense

from fivsense import FivSense

fv = FivSense(api_key=os.environ["FIVSENSE_API_KEY"])
out = fv.predict(
    objective="sale",
    conversation=[{"role": "customer", "text": "Achei caro."}],
)
print(out["prediction"]["will_convert"])

Privacidade & escopo

O FivSense é uma camada de percepção e previsão — não é CRM, chatbot nem orquestrador, e nunca responde ao consumidor final. Perfil são padrões comunicacionais observáveis com confidence, nunca diagnóstico: não inferimos saúde mental nem atributos sensíveis/protegidos.

IDs são pseudonimizados (HMAC), PII é removida antes de persistir e a conversa crua nunca é logada. Conformidade LGPD/GDPR por padrão.