SDK (TypeScript, Python)

Официальные клиенты из того же файла OpenAPI, что и этот справочник — версия = версия спецификации. Всё показанное здесь работает и через чистый HTTP.

Установка

TypeScript: пакет npm @claritos/api (ESM, Node ≥ 18, также edge/браузер со своим fetch). Python: пакет PyPI claritos (Python ≥ 3.9, httpx). Оба содержат типы для всех конечных точек и проверку вебхуков.

shell

npm install @claritos/api
# oder
pip install claritos

TypeScript

createClaritos({ apiKey }) возвращает настроенный клиент; каждая операция — функция с именем конечной точки (contactsList, invoicesIssue, …), принимающая { client, path, query, body, headers }. Ответы — { data, error, response }; с throwOnError: true вызов бросает исключение. Для записи передавайте заголовок Idempotency-Key.

typescript

import { createClaritos, contactsList, contactsCreate, STAGING_BASE_URL } from "@claritos/api";

const claritos = createClaritos({
  apiKey: process.env.CLARITOS_API_KEY!,
  // baseUrl: STAGING_BASE_URL, // Sandbox
});

const { data, error } = await contactsList({ client: claritos, query: { limit: 50, q: "muster" } });
if (error) throw new Error(error.title);
for (const c of data.data) console.log(c.displayName);

const created = await contactsCreate({
  client: claritos,
  body: { type: "PERSON", firstName: "Anna", lastName: "Muster", email: "anna@example.com" },
  headers: { "Idempotency-Key": crypto.randomUUID() },
  throwOnError: true,
});

Python

create_client(api_key) возвращает AuthenticatedClient; операции лежат модулями в claritos_api.api.<домен>.<операция> с вариантами sync/asyncio (sync, sync_detailed, asyncio). Модели в claritos_api.models — имена полей в snake_case.

python

from claritos import create_client, STAGING_BASE_URL
from claritos_api.api.contacts import contacts_list, contacts_create
from claritos_api.models import ContactsCreateBody

client = create_client(api_key="capi_…")  # base_url=STAGING_BASE_URL für die Sandbox

page = contacts_list.sync(client=client, limit=50, q="muster")
for c in page.data:
    print(c.display_name)

created = contacts_create.sync(
    client=client,
    body=ContactsCreateBody(type="PERSON", first_name="Anna", last_name="Muster", email="anna@example.com"),
)

Проверка вебхуков

verifyWebhook / verify_webhook проверяют webhook-id, webhook-timestamp (±5 минут) и webhook-signature (HMAC-SHA256, Standard Webhooks) — всегда по сырому телу. При ротации секрета передайте оба секрета списком.

typescript

import { verifyWebhook, WebhookVerificationError } from "@claritos/api";

export async function POST(req: Request) {
  const payload = await req.text(); // Roh-Body, nicht geparst
  try {
    const event = await verifyWebhook({ payload, headers: req.headers, secret: process.env.CLARITOS_WEBHOOK_SECRET! });
    // event.type z. B. "invoices.invoice.paid"; event.data = Nutzlast
    return new Response(null, { status: 204 });
  } catch (e) {
    if (e instanceof WebhookVerificationError) return new Response("invalid signature", { status: 400 });
    throw e;
  }
}

python

from claritos import verify_webhook, WebhookVerificationError

@app.post("/webhooks/claritos")
def claritos_webhook(request):
    try:
        event = verify_webhook(request.get_data(), request.headers, secret=os.environ["CLARITOS_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return ("invalid signature", 400)
    handle(event["type"], event["data"])
    return ("", 204)

Версии

Версия SDK — это версия файла OpenAPI (см. changelog). Новые конечные точки и поля добавляются аддитивно; обновлять SDK для продолжения вызовов не обязательно. Публикация в npm/PyPI по тегам sdk-ts-v… и sdk-py-v… в репозитории.