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 de produto da IT Booster:

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 provedores de IA diretamente, usa Tokia
1 contrato (Tokia ↔ provedores) em vez de N contratos (SimplesZap ↔ N provedores)
Cobrança centralizada em 1 lugar (Tokia), facilita auditoria
Cliente que assina os 2 produtos tem 1 saldo BRL (futuro: shared balance, hoje separado por simplicidade)

Setup

O time Tokia provisiona uma conta interna pro SimplesZap e gera uma API key dedicada com rate limit de 600 req/min.
Copia a key sk-tokia-... impressa.
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)
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 por x-tokia-client=simpleszap)
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.
gemini-flash, mais rápido + bom PT-BR.
deepseek-v3, o mais barato pra uso em escala.
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, as keys são auto-suspensas automaticamente. 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. Solicitar re-provisionamento ao time Tokia.

Roadmap futuro

Evento webhook outbound simpleszap.message_relayed pra clientes Tokia+SimplesZap
Shared balance, cliente que assina os 2 produtos tem 1 saldo único
SimplesZap como "tier" dedicado no /pricing pra venda cruzada