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.

Contrato v1.0.0 · base URL https://fivsense.4profitai.com

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.

Começar em 1 minuto

Fluxo completo, sem processo humano: crie a conta grátis, copie a sua api_key e abra o painel — lá os exemplos abaixo já vêm com a sua chave embutida, prontos para colar. Troque SUA_API_KEY pela chave e rode.

curl
curl -sS https://fivsense.4profitai.com/v1/predict \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective":"sale","locale":"pt-BR","conversation":[{"role":"agent","text":"Olá! Posso ajudar com alguma dúvida?"},{"role":"customer","text":"Quanto custa o plano? Achei meio caro."}]}'
TypeScript · npm i @fivsense/sdk
import { FivSenseClient } from "@fivsense/sdk";

const fv = new FivSenseClient({
  apiKey: "SUA_API_KEY",
  baseUrl: "https://fivsense.4profitai.com",
});

const out = await fv.predict({
  "objective": "sale",
  "locale": "pt-BR",
  "conversation": [
    {
      "role": "agent",
      "text": "Olá! Posso ajudar com alguma dúvida?"
    },
    {
      "role": "customer",
      "text": "Quanto custa o plano? Achei meio caro."
    }
  ]
});

console.log(out.prediction.will_convert);
Python · pip install fivsense
from fivsense import FivSenseClient

fv = FivSenseClient(
    api_key="SUA_API_KEY",
    base_url="https://fivsense.4profitai.com",
)

out = fv.predict({
  "objective": "sale",
  "locale": "pt-BR",
  "conversation": [
    {
      "role": "agent",
      "text": "Olá! Posso ajudar com alguma dúvida?"
    },
    {
      "role": "customer",
      "text": "Quanto custa o plano? Achei meio caro."
    }
  ]
})

print(out["prediction"]["will_convert"])

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 (@fivsense/sdk, classe FivSenseClient) e Python (fivsense), cobrindo predict + outcomes. Veja os exemplos prontos em Começar em 1 minuto ou gere-os com a sua chave no painel.

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.