Быстрый старт
Ключ, первый вызов и проверка подписи: от нуля до рабочей интеграции.
Интеграция с 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_KEY | 401 | заголовок X-Recca-Tenant-Key не передан |
INVALID_TENANT_KEY | 401 | ключ не найден, отозван, просрочен или организация отключена |
INSUFFICIENT_SCOPE | 403 | у ключа нет права, которого требует метод |
IP_NOT_ALLOWED | 403 | адрес вызова вне списка IP ключа |
RATE_LIMIT_EXCEEDED | 429 | исчерпан лимит запросов; повторяйте не раньше Retry-After |
Полный справочник кодов — в разделе «Ключи, права и лимиты». У методов CPA-двери в ответе есть meta.request_id и заголовок X-Request-Id: назовите его, если обращаетесь в поддержку.
См. также
- Ключи, права и лимиты — выдача ключа, права и лимиты
- CPA-API — полный контракт CPA-двери
- Постбэки и цели — как сообщить сети о конверсии
- Вебхуки — события сети на ваш адрес
- Go SDK — то же через Go-библиотеку
- Песочница — где безопасно пробовать