Recca Разработчикам
Меню

Быстрый старт

Ключ, первый вызов и проверка подписи: от нуля до рабочей интеграции.

Интеграция с Recca идёт между серверами: ваш сервер вызывает API сети с ключом и принимает от неё вебхуки. Ниже — минимальный путь от выпуска ключа до проверенной подписи. Все адреса относительно https://api.recca.ru.

Что понадобится

  • Организация (сеть) в Recca и доступ владельца к её кабинету.
  • Тариф, на котором включено управление API-ключами. Если он не включён, страница ключей в кабинете показывает замок с названием тарифа.
  • Сервер, который хранит секреты. Ключ нельзя класть в код страницы или мобильного приложения.

Шаг 1. Выпустите ключ

В кабинете организации откройте страницу «API-ключи» (/org/<slug>/api-keys) и создайте ключ:

  • Название — до 80 символов, среди действующих ключей оно уникально (повтор даст 409 LABEL_TAKEN).
  • Права — отметьте только то, что нужно интеграции. Переключатель «Только чтение» выбирает все права, оканчивающиеся на :read. Подробности — в разделе «Ключи, права и лимиты».
  • Срок действия — форма предлагает 180 дней; ключ без срока тоже можно выпустить, если снять срок осознанно.
  • Список IP — до 50 адресов или сетей CIDR; пустой список значит «с любого адреса».

Ключ выглядит как rtk_live_ и 32 шестнадцатеричных символа. Полностью он показывается один раз, при выпуске: в базе хранится только хеш. Потеряли — отзовите ключ и выпустите новый. В примерах ниже ключ берётся из переменной окружения RECCA_TENANT_KEY.

Шаг 2. Первый вызов

Ключ передаётся заголовком X-Recca-Tenant-Key. Начните с вызова, которому не нужны отдельные права:

curl -s https://api.recca.ru/federation/v1/self \
  -H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY"

Ответ в общем конверте { "success": true, "data": … }:

{
  "success": true,
  "data": {
    "organization": { "id": "org_01…", "slug": "my-network", "display_name": "Моя сеть", "plan_tier": "organization", "allowed_origins": [] },
    "key": { "prefix": "rtk_live_ab12cd34", "scopes": ["offers:read", "leads:write"] },
    "visibility": { "shop_count": 1 },
    "environment": "production"
  }
}

Здесь вы проверяете три вещи: ключ принят, у него именно те права, которые вы отметили, и environment — та среда, в которую вы пришли (production, staging или sandbox). Код, который создаёт данные ради проверки, запускайте только там, где environment равен sandbox: см. раздел «Песочница».

Для проверки доступности без ключа есть GET /federation/v1/health: он отвечает status, database, cache и jwks и не расходует лимит.

Если вы подключаете CPA-сеть, аналогичная проба — GET /federation/v1/cpa/self (право cpa:self:read). Она тоже не тратит лимит запросов.

Шаг 3. Прочитайте данные

Списки отдаются страницами. У GET /federation/v1/offers и GET /federation/v1/users параметры skip (от 0) и take (от 1 до 100, по умолчанию 20); offers дополнительно принимает shop_id и q. В ответе есть meta: total, count, offset, limit, hasMore.

curl -s "https://api.recca.ru/federation/v1/offers?take=5" \
  -H "X-Recca-Tenant-Key: $RECCA_TENANT_KEY"

Для offers нужно право offers:read. Без него вы получите 403 INSUFFICIENT_SCOPE, а в details.required — название недостающего права.

Шаг 4. Передайте событие в сеть

Самые частые записи: участник (POST /federation/v1/users/upsert, право users:upsert), заявка (POST /federation/v1/leads, право leads:write) и конверсия (POST /federation/v1/conversions, право conversions:write). Для машинной CPA-двери используйте методы /federation/v1/cpa/*, они описаны в разделе «CPA-API».

Запись должна быть идемпотентной на вашей стороне: у заявки и конверсии есть external_id, повтор с тем же значением не создаёт дубль. Конверсия отвечает 201 при создании и 200 при повторе.

Шаг 5. Примите вебхук и проверьте подпись

События сети приходят на ваш адрес подписанным POST. Заголовок X-Recca-Signature содержит метку времени и HMAC-SHA256 от строки «метка, точка, сырое тело». Проверять нужно по байтам тела до разбора JSON и отклонять метки старше пяти минут. Готовый код, состав событий и расписание повторов — в разделе «Вебхуки».

Что делать при ошибках

Каждая ошибка приходит в конверте { "success": false, "error": { "code", "message", "details" } }. Ветвитесь по code, а не по тексту сообщения. Самые частые на старте:

КодСтатусЧто значит
MISSING_TENANT_KEY401заголовок X-Recca-Tenant-Key не передан
INVALID_TENANT_KEY401ключ не найден, отозван, просрочен или организация отключена
INSUFFICIENT_SCOPE403у ключа нет права, которого требует метод
IP_NOT_ALLOWED403адрес вызова вне списка IP ключа
RATE_LIMIT_EXCEEDED429исчерпан лимит запросов; повторяйте не раньше Retry-After

Полный справочник кодов — в разделе «Ключи, права и лимиты». У методов CPA-двери в ответе есть meta.request_id и заголовок X-Request-Id: назовите его, если обращаетесь в поддержку.

См. также