SDK (Futuro)

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Backend, Arquitetura

Atualmente, a SOFIA não publica um SDK oficial (ex.: pacote npm).

A integração oficial é baseada em:

HTTP (REST)
WebSocket
Webhook
Iframe + postMessage (browser)

Um SDK será apenas uma camada opcional de conveniência sobre esses contratos.

1. O que é (e o que não é) um SDK

Um SDK oficial terá como objetivo:

Centralizar autenticação
Padronizar timeout e retry
Reduzir boilerplate
Facilitar versionamento
Garantir validações consistentes

Ele não substituirá:

Webhook
API Pull
postMessage
Iframe

Esses são contratos estruturais da plataforma.

2. Quando Usar um SDK

Use um SDK ou cliente interno quando:

Você tem backend próprio
Precisa padronizar retry/backoff
Precisa validar assinatura HMAC
Precisa integrar múltiplos workers
Quer reduzir duplicação de código

Não use quando:

Sua integração é apenas Iframe
Você prefere dependência zero
Você quer controle total manual

3. Recomendações Atuais (Sem SDK Oficial)

Hoje, a recomendação é criar um mini-client interno no seu backend.

Esse client deve:

Aceitar baseUrl
Injetar Authorization
Aplicar timeout
Aplicar retry somente para 429/5xx
Nunca logar segredos

4. Estrutura Recomendada de Client

Exemplo mínimo (Node.js / TypeScript):


type SofiaClientConfig = {
  baseUrl: string;
  token?: string;
  timeoutMs?: number;
};
 
export function createSofiaClient(cfg: SofiaClientConfig) {
  const baseUrl = cfg.baseUrl.replace(/\/+$/, '');
  const timeoutMs = Number.isFinite(cfg.timeoutMs) ? Number(cfg.timeoutMs) : 8000;
 
  async function request<T>(path: string, init?: RequestInit): Promise<T> {
    const url = new URL(path.replace(/^\//, ''), `${baseUrl}/`);
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);
 
    try {
      const headers = new Headers(init?.headers || {});
      headers.set('accept', 'application/json');
 
      if (init?.body && !headers.has('content-type')) {
        headers.set('content-type', 'application/json');
      }
 
      if (cfg.token && !headers.has('authorization')) {
        headers.set('authorization', `Bearer ${cfg.token}`);
      }
 
      const resp = await fetch(url, {
        ...init,
        headers,
        signal: controller.signal,
      });
 
      const text = await resp.text().catch(() => '');
      const json = text ? JSON.parse(text) : null;
 
      if (!resp.ok) {
        const err = new Error(`SOFIA_HTTP_${resp.status}`);
        (err as any).status = resp.status;
        (err as any).body = json;
        throw err;
      }
 
      return json as T;
    } finally {
      clearTimeout(timer);
    }
  }
 
  return {
    get: <T>(path: string) => request<T>(path, { method: 'GET' }),
    post: <T>(path: string, body?: unknown) =>
      request<T>(path, {
        method: 'POST',
        body: body ? JSON.stringify(body) : undefined,
      }),
  };
}

5. Variáveis de Ambiente


SOFIA_API_BASE_URL=https://api.v1sofia.com/api
SOFIA_SUPABASE_JWT=********
SOFIA_WS_URL=wss://ws.v1sofia.com

Regras:

Nunca usar token no frontend público
Usar secret manager
Rotacionar se houver suspeita de vazamento

6. Versionamento

Até o SDK oficial existir, o versionamento relevante é:

API

Documentado em Especificação Técnica
Mudanças breaking exigem nova versão

Eventos

postMessage → version no envelope
Webhook → versionamento por contrato

Futuro SDK

Quando publicado:

major → breaking change
minor → novo recurso compatível
patch → correções internas

7. Arquitetura Recomendada

Integração madura normalmente é:


Webhook (backend confiável)
+
Iframe (experiência visual)

Ou:


API Pull (enterprise)
+
Cache local

SDK é apenas facilitador.