Public API

Este guia mostra como usar a API publica para chat standalone e clientes customizados.

Visao geral

A API publica segue o mesmo contrato de governanca do chat publico:

• Resolve uso por publicSlug
• Exige x-idempotency-key em operacoes de escrita
• Exige x-correlation-id para rastreabilidade
• Exige x-public-session-token para mensagens e stream

Quick Start (curl)

1) Criar sessao publica

curl -i -X POST "https:///api/public/pages/support-assistant/session" \
  -H "x-correlation-id: docs-session-1" \
  -H "x-idempotency-key: docs-session-1"

Resposta (resumo):

{
  "sessionId": "f8f8b1cc-....",
  "useCaseSlug": "support-assistant",
  "metadata": {
    "session_token": "3f9eb9f4-...."
  }
}

2) Enviar mensagem

curl -i -X POST "https:///api/public/sessions/{sessionId}/messages" \
  -H "Content-Type: application/json" \
  -H "x-correlation-id: docs-message-1" \
  -H "x-idempotency-key: docs-message-1" \
  -H "x-public-session-token: {session_token}" \
  -d '{"useCaseSlug":"support-assistant","content":"Ola, preciso de ajuda"}'

3) Consumir stream SSE

curl -N "https:///api/public/sessions/{sessionId}/stream" \
  -H "Accept: text/event-stream" \
  -H "x-correlation-id: docs-stream-1" \
  -H "x-public-session-token: {session_token}"

Exemplos por linguagem

JavaScript (fetch)

const apiBase = "https:///api/public";
const slug = "support-assistant";

const sessionResp = await fetch(`${apiBase}/pages/${slug}/session`, {
  method: "POST",
  headers: {
    "x-correlation-id": crypto.randomUUID(),
    "x-idempotency-key": crypto.randomUUID(),
  },
});
const session = await sessionResp.json();
const sessionId = session.sessionId;
const sessionToken = session.metadata?.session_token;

await fetch(`${apiBase}/sessions/${sessionId}/messages`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-correlation-id": crypto.randomUUID(),
    "x-idempotency-key": crypto.randomUUID(),
    "x-public-session-token": sessionToken,
  },
  body: JSON.stringify({
    useCaseSlug: slug,
    content: "Ola, preciso de ajuda",
  }),
});

Python (requests)

import uuid
import requests

api_base = "https:///api/public"
slug = "support-assistant"

session = requests.post(
    f"{api_base}/pages/{slug}/session",
    headers={
        "x-correlation-id": str(uuid.uuid4()),
        "x-idempotency-key": str(uuid.uuid4()),
    },
).json()

session_id = session["sessionId"]
session_token = session["metadata"]["session_token"]

requests.post(
    f"{api_base}/sessions/{session_id}/messages",
    headers={
        "Content-Type": "application/json",
        "x-correlation-id": str(uuid.uuid4()),
        "x-idempotency-key": str(uuid.uuid4()),
        "x-public-session-token": session_token,
    },
    json={"useCaseSlug": slug, "content": "Ola, preciso de ajuda"},
)

Erros comuns

• USE_CASE_PUBLIC_ACCESS_DISABLED: caso de uso com acesso publico desabilitado
• RESOURCE_NOT_FOUND: slug invalido ou recurso inexistente
• PUBLIC_SESSION_NOT_FOUND: sessao expirada/invalida
• PUBLIC_SESSION_TOKEN_INVALID: token de sessao incorreto
• IDEMPOTENCY_KEY_REQUIRED: header obrigatorio ausente em escrita

Error reference

Code	HTTP	Causa comum	Acao recomendada
RESOURCE_NOT_FOUND	404	Slug invalido	Verificar publicSlug
USE_CASE_PUBLIC_ACCESS_DISABLED	403	Use case nao publicado para publico	Habilitar Public Access
PUBLIC_SESSION_NOT_FOUND	404	Sessao expirada ou inexistente	Criar nova sessao
PUBLIC_SESSION_TOKEN_INVALID	403	Token ausente/incorreto	Reusar token da criacao de sessao
IDEMPOTENCY_KEY_REQUIRED	400	Header ausente em escrita	Enviar x-idempotency-key

API contract source

A referencia oficial desta API e o contrato OpenAPI gerado e publicado em:

• /contracts/fsaap-agent-api/latest.yaml (ponteiro estavel)
• /contracts/fsaap-agent-api/fsaap-agent-api.yaml (artefato nomeado)

Fonte canonica: contrato do fsaap-agent-api publicado no pipeline de docs.

Docs helper (assistido por IA)

Nao autoritativo: respostas do helper sao orientativas. Em caso de conflito, prevalecem o contrato OpenAPI e esta documentacao canonica.

Perguntas guiadas (Q&A):

• “Quais headers sao obrigatorios para criar sessao publica?”
• “Como devo reagir a PUBLIC_SESSION_NOT_FOUND?”
• “Qual a diferenca entre erro de slug invalido e acesso publico desabilitado?”

Try this next:

• Valide seu fluxo contra o contrato em /contracts/fsaap-agent-api/latest.yaml
• Reproduza o quick start com curl
• Verifique os codigos de erro na tabela de referencia

Boas praticas

• Gere x-idempotency-key unico por operacao de escrita
• Preserve e propague x-correlation-id entre servicos
• Nunca exponha x-public-session-token em logs ou analytics publicos
• Em PUBLIC_SESSION_NOT_FOUND, recrie sessao e solicite reenvio da mensagem ao usuario