Quickstart Express

1. Установка

npm install @recca/federation-sdk

2. Инициализация клиента

В вашем Express-приложении (например server.ts):

import express from "express"
import { ReccaFederationClient } from "@recca/federation-sdk"

const recca = new ReccaFederationClient({
  apiBase: "https://api.recca.ru",
  apiKey: process.env.RECCA_API_KEY!,          // rtk_live_*
  webhookSecret: process.env.RECCA_WEBHOOK_SECRET!,
})

Ключ rtk_live_* выпускается один раз в /org/<slug>/api-keys и показывается plain ОДНОКРАТНО — сохраните в vault. Webhook secret тоже разово в /org/<slug>/integration → Webhook.

3. Upsert партнёра после OAuth

Когда новый пользователь регистрируется на вашем сайте (VK, email, etc.) — зарегистрируйте его в Recca, сохраните возвращённый tenant_recca_id рядом с вашей пользовательской записью:

app.post("/api/auth/vk", async (req, res) => {
  const { tenant_recca_id } = await recca.users.upsert({
    external_id: `mysite:vk:${req.body.vkId}`,
    vk_id: String(req.body.vkId),
    full_name: req.body.name,
    email: req.body.email,
    email_verified: false,
  })
  // persist tenant_recca_id on your user row
  res.json({ tenantReccaId: tenant_recca_id })
})

4. Webhook receiver с HMAC

Recca шлёт события (новый лид, бонус подтверждён, конверсия) на ваш URL. SDK содержит middleware который проверяет X-Recca-Signature и парсит событие:

app.post(
  "/api/recca/webhook",
  express.raw({ type: "application/json" }),    // raw body для HMAC
  recca.webhookMiddleware(),
  (req, res) => {
    const e = (req as any).reccaEvent           // verified + parsed
    switch (e.event_type) {
      case "lead.created":        /* enqueue CRM sync */     ; break
      case "bonus.approved":      /* notify partner */        ; break
      case "conversion.cascaded": /* update finance */        ; break
    }
    res.json({ received: true })
  }
)

Если предпочитаете не использовать SDK middleware — проверка руками:

import crypto from "crypto"
const sig = req.header("X-Recca-Signature") || ""
const expected = crypto
  .createHmac("sha256", process.env.RECCA_WEBHOOK_SECRET!)
  .update(req.body as Buffer)
  .digest("hex")
if (sig !== expected) return res.status(401).end()

Важно: используйте express.raw() на webhook-руте, не express.json() — JSON-парсер пересобирает body и HMAC перестаёт совпадать.

5. Регистрация конверсии

Когда привлечённый партнёром клиент оплатил заказ — пингуйте Recca, чтобы запустить каскадное начисление бонусов рефереру и вверх по сети:

await recca.conversions.register({
  lead_id: "lead_01HXVB...",
  amount_kopecks: 1280000,             // 12 800 ₽
  currency: "RUB",
  external_order_id: "order-42",
})

6. Проверка

Полный список curl-проверок и список событий — в API Reference и Webhooks Catalog.

Далее: Webhooks → каталог событий с примерами payload →