Docs eksp

EKSP — Encantra Knowledge & Signals Protocol

Um contrato aberto e simples para que qualquer plataforma (BaaS, SaaS, e-commerce, ERP, serviço) ensine à Encantra tudo o que ela precisa saber para atender e cuidar dos clientes — e mantenha isso sempre atualizado.

Versão atual: 1.0 · Status: estável · Especificação normativa: spec-v1.md · Prompt para gerar o provedor com IA: AI-BUILD-PROMPT.md

Por que existe

O atendimento excelente depende de duas coisas que normalmente vivem fora da ferramenta de suporte:

  1. Conhecimento do produto — documentação, FAQs, planos, preços, políticas, changelog, status.
  2. Sinais do cliente — quem é, que plano tem, como está usando, se está com fatura atrasada, se foi afetado por um incidente.

Sem isso, a IA inventa ou se cala, e o atendente abre cinco abas para entender um caso. O EKSP resolve o problema com um contrato HTTP+JSON pequeno, que um time (ou uma IA) implementa em poucas horas na stack que já usa.

Como a Encantra usa cada capacidade

Capacidade Endpoint O que a Encantra faz com ela
content GET /content Indexa artigos, FAQs, tutoriais e referências na base de conhecimento da Lumi (IA). Públicos alimentam a central de ajuda e o chat; internos ficam só para agentes.
catalog GET /catalog Ensina produtos, planos, preços e limites — a Lumi responde "qual plano tem SSO?" sem inventar.
customers GET /customers Cria/atualiza contas e contatos (por external_id) para a jornada do cliente e o health score.
context GET /customers/{id}/context Mostra ao vivo, ao lado do ticket e na visão 360º, a assinatura, faturas, uso, flags e incidentes do cliente.
usage GET /usage Alimenta o health score e os gatilhos de Customer Success (ex.: "sem login há 14 dias").
status GET /status Mantém a Lumi ciente de incidentes em andamento e evita respostas erradas durante instabilidades.
actions GET /actions + POST /actions/{name} Permite que agentes (com confirmação humana) executem ações no produto: reenviar fatura, estender avaliação…
push POST {encantra}/eksp/v1/push/{uuid} O provedor avisa mudanças em segundos (assinado com HMAC), sem esperar o próximo ciclo de sincronização.

Implemente só o que fizer sentido. O mínimo viável é o manifesto + content.

Arquitetura em 30 segundos

 Seu produto (provedor EKSP)                              Encantra
 ┌──────────────────────────────┐   descoberta    ┌──────────────────────────┐
 │ /.well-known/encantra.json   │ ◄────────────── │ Connect (sync a cada N min)│
 │ /content  /catalog /status   │ ◄── pull ────── │  → Índice de conhecimento │
 │ /customers  /usage           │ ◄── pull ────── │  → Contas, contatos, uso  │
 │ /customers/{id}/context      │ ◄── ao vivo ─── │  → Painel do atendente    │
 │ /actions  /actions/{name}    │ ◄── sob demanda │  → Ações com confirmação  │
 │                              │ ── push HMAC ─► │ /eksp/v1/push/{uuid}      │
 └──────────────────────────────┘                 └──────────────────────────┘

Começando

  1. Leia a especificação (20 minutos).
  2. Use um SDK de referência: sdk/eksp-provider-php ou sdk/eksp-provider-node — ou cole o AI-BUILD-PROMPT.md na sua IA favorita.
  3. Valide os objetos com os JSON Schemas e compare com os exemplos.
  4. Na Encantra, vá em Integrações › Conectores › Novo conector, informe a URL base e o token.
  5. Rode o Testador de conformidade (nota ≥ 80 e nenhuma falha obrigatória = compatível com EKSP v1).
  6. Configure o push com a URL e o segredo exibidos no detalhe do conector.

Arquivos

Arquivo Conteúdo
spec-v1.md Especificação normativa (MUST/SHOULD)
openapi.yaml OpenAPI 3.1 do provedor
schemas/ JSON Schema 2020-12 de cada objeto
examples/ Respostas de exemplo
AI-BUILD-PROMPT.md Prompt pronto para gerar um provedor com IA

Demonstração viva

Toda instalação da Encantra serve um provedor de demonstração completo em /eksp-demo/aurora (token eksp_demo_aurora_7f3c9a1e5b). Explore:

curl https://suporte.inspire4u.com.br/eksp-demo/aurora/.well-known/encantra.json
curl -H "Authorization: Bearer eksp_demo_aurora_7f3c9a1e5b" \
     "https://suporte.inspire4u.com.br/eksp-demo/aurora/content?limit=2"

Licença

A especificação EKSP é aberta (CC BY 4.0). Os SDKs de referência são MIT. Qualquer plataforma pode implementá-la.

Encontrou algo para melhorar? Escreva para master@inspire4u.com.br.