SDKs e exemplos

Não há um SDK oficial publicado em registros (npm, pip) ainda. Por enquanto, copie os helpers abaixo direto para o seu projeto — são pequenos e auto-contidos.

JavaScript / TypeScript

typescript
// meucatalogo.ts
const BASE = "https://katalog.com.br/api/v1";

export class MeuCatalogo {
  constructor(private token: string) {}

  private async request<T>(path: string, init: RequestInit = {}): Promise<T> {
    const res = await fetch(`${BASE}${path}`, {
      ...init,
      headers: {
        ...init.headers,
        Authorization: `Bearer ${this.token}`,
        "Content-Type": "application/json",
      },
    });
    if (!res.ok) {
      const err = await res.json().catch(() => ({}));
      throw new Error(err.erro || `HTTP ${res.status}`);
    }
    return res.json();
  }

  produtos = {
    list: (params?: Record<string, string>) =>
      this.request<{ produtos: any[]; paginacao: any }>(
        "/produtos" + (params ? "?" + new URLSearchParams(params) : ""),
      ),
    get: (id: string) => this.request<any>(`/produtos/${id}`),
    create: (data: any) => this.request<any>("/produtos", { method: "POST", body: JSON.stringify(data) }),
    update: (id: string, data: any) =>
      this.request<any>(`/produtos/${id}`, { method: "PUT", body: JSON.stringify(data) }),
  };

  pedidos = {
    list: (params?: Record<string, string>) =>
      this.request<{ pedidos: any[]; paginacao: any }>(
        "/pedidos" + (params ? "?" + new URLSearchParams(params) : ""),
      ),
  };

  estoque = {
    movimentar: (data: { produtoId: string; tipo: "ENTRADA" | "SAIDA" | "AJUSTE"; quantidade: number; variacaoId?: string; observacao?: string }) =>
      this.request<any>("/estoque", { method: "POST", body: JSON.stringify(data) }),
  };

  clientes = {
    list: (params?: Record<string, string>) =>
      this.request<{ clientes: any[]; paginacao: any }>(
        "/clientes" + (params ? "?" + new URLSearchParams(params) : ""),
      ),
    upsert: (data: any) => this.request<any>("/clientes", { method: "POST", body: JSON.stringify(data) }),
  };

  categorias = {
    list: () => this.request<any[]>("/categorias"),
  };
}

// Uso:
// const api = new MeuCatalogo("sk_live_...");
// const { produtos } = await api.produtos.list({ limite: "100" });

Python

python
# meucatalogo.py
import requests

BASE = "https://katalog.com.br/api/v1"

class MeuCatalogo:
    def __init__(self, token: str):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
        })

    def _request(self, method: str, path: str, **kwargs):
        res = self.session.request(method, f"{BASE}{path}", **kwargs)
        if not res.ok:
            raise Exception(res.json().get("erro", f"HTTP {res.status_code}"))
        return res.json()

    # Produtos
    def listar_produtos(self, **params):
        return self._request("GET", "/produtos", params=params)

    def criar_produto(self, **data):
        return self._request("POST", "/produtos", json=data)

    def get_produto(self, id: str):
        return self._request("GET", f"/produtos/{id}")

    # Pedidos
    def listar_pedidos(self, **params):
        return self._request("GET", "/pedidos", params=params)

    # Estoque
    def movimentar_estoque(self, produto_id: str, tipo: str, quantidade: float, **opts):
        return self._request("POST", "/estoque", json={
            "produtoId": produto_id,
            "tipo": tipo,
            "quantidade": quantidade,
            **opts,
        })

    # Clientes
    def upsert_cliente(self, **data):
        return self._request("POST", "/clientes", json=data)


# Uso:
# api = MeuCatalogo("sk_live_...")
# produtos = api.listar_produtos(limite=100)

PHP

php
<?php
// meucatalogo.php
class MeuCatalogo {
    const BASE = 'https://katalog.com.br/api/v1';
    private $token;

    public function __construct($token) {
        $this->token = $token;
    }

    private function request($method, $path, $body = null, $query = null) {
        $url = self::BASE . $path;
        if ($query) $url .= '?' . http_build_query($query);

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->token,
            'Content-Type: application/json',
        ]);
        if ($body) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));

        $res = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $data = json_decode($res, true);
        if ($code >= 400) {
            throw new Exception($data['erro'] ?? "HTTP $code");
        }
        return $data;
    }

    public function listarProdutos($params = []) { return $this->request('GET', '/produtos', null, $params); }
    public function criarProduto($data) { return $this->request('POST', '/produtos', $data); }
    public function listarPedidos($params = []) { return $this->request('GET', '/pedidos', null, $params); }
    public function movimentarEstoque($data) { return $this->request('POST', '/estoque', $data); }
    public function upsertCliente($data) { return $this->request('POST', '/clientes', $data); }
}

// Uso:
// $api = new MeuCatalogo('sk_live_...');
// $produtos = $api->listarProdutos(['limite' => 100]);

Validar webhooks (qualquer linguagem)

Use o secret do webhook para verificar HMAC SHA-256 do body recebido:

Node.js

javascript
import crypto from "crypto";

function verificarWebhook(secret, body, assinaturaHeader) {
  const hmac = crypto.createHmac("sha256", secret);
  hmac.update(body); // body como string original (não parseada)
  const esperada = "sha256=" + hmac.digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(esperada),
    Buffer.from(assinaturaHeader)
  );
}

Python

python
import hmac, hashlib

def verificar_webhook(secret: str, body: bytes, assinatura: str) -> bool:
    esperada = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(esperada, assinatura)

PHP

php
<?php
function verificarWebhook($secret, $body, $assinatura) {
    $esperada = 'sha256=' . hash_hmac('sha256', $body, $secret);
    return hash_equals($esperada, $assinatura);
}