← Cookbook

SimplesZap + Tokia

Como o SimplesZap (WhatsApp Business SaaS da IT Booster Global) consome o Tokia como provedor de IA — sem precisar integrar OpenAI/Anthropic/etc diretamente em cada fluxo WhatsApp.

Por quê SimplesZap → Tokia?

Princípio CLAUDE.md da IT Booster (decisão arquitetural fundamental):

Tokia ≠ SimplesZap — Tokia é cérebro de IA; SimplesZap é canal WhatsApp. Tokia não vende "WhatsApp Bot" como feature (canibaliza SimplesZap). Integração é via SimplesZap consumir Tokia internamente.

Consequência prática:

• SimplesZap NÃO contrata OpenAI/Anthropic/Fal.ai diretamente — usa Tokia
• 1 contrato (Tokia ↔ providers) em vez de N contratos (SimplesZap ↔ N providers)
• Markup IT Booster centralizado em 1 lugar (Tokia), facilita auditoria
• Cliente que assina os 2 produtos tem 1 saldo BRL (futuro: shared balance, hoje separado por simplicidade)

Setup

1. Admin Tokia roda node scripts/tokia-provision-simpleszap.mjs (no monorepo usetokia). Provisiona profile simpleszap-internal@itbooster.com.br + key alias tokia-simpleszap com rate limit 600 req/min.
2. Copia a key sk-tokia-... impressa.
3. Adiciona em SimplesZap/.env:

   SIMPLESZAP_TOKIA_KEY=sk-tokia-...

Exemplo JavaScript / Node

import OpenAI from "openai";

const tokia = new OpenAI({
  baseURL: "https://api.usetokia.com/v1",
  apiKey: process.env.SIMPLESZAP_TOKIA_KEY,
  defaultHeaders: {
    "x-tokia-client": "simpleszap",
  },
});

export async function gerarRespostaWhatsApp(prompt, modelo = "gpt-4o-mini") {
  const completion = await tokia.chat.completions.create({
    model: modelo,
    messages: [
      { role: "system", content: "Você é assistente do SimplesZap respondendo via WhatsApp em PT-BR." },
      { role: "user", content: prompt },
    ],
    max_tokens: 300,
    temperature: 0.7,
  });

  // Loga request_id pra debug cross-system Tokia ↔ SimplesZap
  const requestId = completion._raw?.headers?.["x-tokia-request-id"];
  console.log({ tokia_request_id: requestId, model: modelo });

  return completion.choices[0]?.message?.content ?? "";
}

Exemplo Python

from openai import OpenAI
import os

tokia = OpenAI(
    base_url="https://api.usetokia.com/v1",
    api_key=os.environ["SIMPLESZAP_TOKIA_KEY"],
    default_headers={"x-tokia-client": "simpleszap"},
)

def gerar_resposta_whatsapp(prompt: str, modelo: str = "gpt-4o-mini") -> str:
    completion = tokia.chat.completions.create(
        model=modelo,
        messages=[
            {"role": "system", "content": "Você é assistente do SimplesZap em PT-BR."},
            {"role": "user", "content": prompt},
        ],
        max_tokens=300,
        temperature=0.7,
    )
    return completion.choices[0].message.content or ""

Headers obrigatórios

• Authorization: Bearer sk-tokia-... — sua key SimplesZap
• x-tokia-client: simpleszap — identifica origem do tráfego no Tokia admin dashboard (separa de "direct", "tokia-chat", etc — Sprint 324)
• x-tokia-request-id (opcional, mas RECOMENDADO) — gera UUID client-side, Tokia ecoa de volta no response header. Permite debug correlacionado quando WhatsApp user reportar problema.

Billing interno

SimplesZap NÃO paga via PIX/cartão. É carry-over interno IT Booster:

• Balance inicial R$ 5000 BRL por quarter (financiamento IT Booster mãe)
• Adjusts via admin /dashboard/admin/users + "Ajustar saldo" no profile simpleszap-internal@itbooster.com.br
• Consumption real aparece em /dashboard/admin/chat (clients-summary filtrado futuro por x-tokia-client=simpleszap — Sprint 526)
• Relatórios SimplesZap pra cliente final incluem o custo IA repassado da Tokia (decisão financeira IT Booster)

Modelos recomendados pra WhatsApp

• gpt-4o-mini — default. Bom equilíbrio velocidade/qualidade. Markup 2x.
• gemini-flash — mais rápido + bom PT-BR. Markup 2.5x.
• deepseek-v3 — mais barato. Markup 3x mas custo upstream baixo.
• test-free (gpt-oss-120b) — pra desenvolvimento/teste sem debitar saldo.

Anti-abuso

• Rate limit: 600 req/min por key SimplesZap (5x default Tokia 120 RPM)
• Hard cap saldo: se SimplesZap zerar saldo, keys são auto-suspensas pelo cron Tokia (chama upstream falha). Refill via admin balance adjust.
• IP allowlist: NÃO usada (SimplesZap multi-container, IPs voláteis)

Troubleshooting

Ver /docs/troubleshooting geral. Erros específicos SimplesZap:

• HTTP 429 "rate_limit_exceeded" — SimplesZap bateu 600 req/min. Implementa retry com exponential backoff + reduzir paralelismo.
• HTTP 402 "exhausted_balance" — saldo SimplesZap zerou. Admin Tokia precisa fazer balance adjust pra refill.
• HTTP 401 "invalid_authorization" — key expirou/revogada. Re-provisionar via tokia-provision-simpleszap.mjs.

Roadmap futuro

• Sprint 536: evento webhook outbound simpleszap.message_relayed pra clientes Tokia+SimplesZap
• Sprint 600+: shared balance — cliente que assina os 2 produtos tem 1 saldo único
• Sprint 700+: SimplesZap como "tier" dedicado no /pricing pra venda cruzada

Decisão arquitetural completa: DR-030 no monorepo usetokia. Repo SimplesZap (privado IT Booster): inael/simpleszap.