Перейти к содержимому
AISARAISAR
REST API

Каталог интеграторов

Публичный каталог интеграторов AISAR без авторизации: список и карточка партнёров, чьи профили прошли модерацию, логотипы, карта сайта для поисковиков, заявка на подбор интегратора с подтверждением кодом из письма и общий справочник городов (Казахстан, Кыргызстан, Узбекистан, Россия). Пока каталог или приём заявок не открыты, соответствующие маршруты отвечают 404.

Доступ и переключатели

Ни один маршрут группы не требует заголовка Authorization. Каталог (/v1/public/partners*) и приём заявок (/v1/public/partner-leads*) включаются отдельными переключателями на стороне платформы; пока переключатель выключен, маршруты отвечают 404 { "message": "Not found." }. Справочник городов (/v1/public/geo/cities) от переключателей не зависит. Лимиты запросов действуют по IP: при превышении приходит 429.

В каталог попадает только партнёр, у которого активен кабинет, профиль одобрен модератором, включена публикация и принято действующее партнёрское соглашение. Наружу отдаётся только одобренный снимок профиля и полученные сертификации; комиссии, контакты и внутренние заметки партнёра не публикуются. Формат ответов этой группы: списки { "data": [...], "meta": {...} }, карточка и карта сайта { "data": ... }, ответы формы заявки без обёртки data.

Список и карточка

GET /v1/public/partners принимает необязательные фильтры: country (KZ, KG, UZ, RU), city_id (id города из справочника), specialization (whatsapp, instagram, telegram, telephony, ai_agents, automation, bitrix24, amocrm, onboarding), language (ru, kk, en, ky, uz), q (поиск от 2 до 80 символов по названию, слогану и городам), locale (ru, en, kk, по умолчанию en: язык названий городов) и page (1 до 1000). Страница содержит до 24 партнёров, порядок по названию. Фильтр city_id находит только города из справочника: партнёр, указавший свой город текстом, находится по стране и по q. Неизвестное значение фильтра даёт 422.

GET /v1/public/partners/{slug} возвращает карточку: поля карточки списка плюс description, website, founded_year, team_size, cases, og_image_url, published_at. Неизвестный или скрытый slug даёт 404 { "message": "Not found." }. Логотип и картинка для превью ссылок отдаются по GET /v1/public/partners/{slug}/logo и /og-image (ссылки на них приходят в logo_url и og_image_url, в конце добавлен ?v= для сброса кеша); у скрытого профиля или без файла ответ 404. GET /v1/public/partners/sitemap возвращает slug и updated_at всех видимых партнёров для карты сайта.

Заявка на подбор интегратора

POST /v1/public/partner-leads принимает заявку посетителя. Обязательные поля: contact_name (2 до 100 символов), email, country (KZ, KG, UZ, RU), consent (должен быть true) и ровно одно из двух: geo_city_id (город из справочника, должен принадлежать указанной стране) или city_name (свой город текстом, до 80 символов); передать оба нельзя. Необязательные: partner_slug (заявка конкретному интегратору из каталога), ref_slug, phone (проверяется по стране), company_name, company_size (1-5, 6-15, 16-50, 51-200, 200+), needs[] (коды специализаций), message (до 2000 символов), locale (ru, en, kk), utm_source, utm_medium, utm_campaign, utm_content, utm_term, landing_path, visitor_id. Текстовые поля очищаются от разметки. Поля website и form_started_at служат защитой от ботов: website оставьте пустым, form_started_at не обязателен.

Ответ всегда 202 { "status": "check_email", "submission_token": "..." }, независимо от того, новый это адрес, известный или повтор: по ответу нельзя узнать, есть ли такой адрес в системе. На почту уходит шестизначный код. Подтвердить заявку можно двумя способами: POST /v1/public/partner-leads/verify с submission_token (из ответа на создание, 40 символов) и code, либо POST /v1/public/partner-leads/{publicId}/verify с одним code (идентификатор заявки приходит в ссылке из письма). Код состоит из шести цифр и действует 24 часа, на заявку даётся 5 попыток. Успех: 200 { "status": "verified" }. Неверный код, неизвестная заявка и исчерпанные попытки дают одинаковый 422 { "error": "invalid_code" }. Пока заявка не подтверждена, интеграторам она не показывается.

Справочник городов

GET /v1/public/geo/cities?country=KZ возвращает активные города страны, крупные первыми. Параметры: country (обязателен: KZ, KG, UZ, RU), q (до 64 символов, совпадение по началу названия на любом языке или прежнего названия, без учёта регистра) и locale (ru, en, kk, по умолчанию en). Элемент: id, code, name и region на выбранном языке, is_admin_center. Ответ кешируется (ETag, Cache-Control: public, max-age=86400), на повторный запрос с If-None-Match приходит 304. Идентификатор из этого справочника подставляется в city_id каталога и в geo_city_id заявки. Данные основаны на GeoNames (лицензия CC BY 4.0).

Эндпоинты

МетодПуть
GET/v1/public/partners

Список интеграторов каталога с фильтрами и страницами

GET/v1/public/partners/sitemap

Slug и дата обновления всех видимых интеграторов (для карты сайта)

GET/v1/public/partners/{slug}

Карточка интегратора

GET/v1/public/partners/{slug}/{asset}

Логотип (`logo`) или картинка для превью (`og-image`) интегратора

POST/v1/public/partner-leads

Заявка на подбор интегратора (ответ 202, код уходит на почту)

POST/v1/public/partner-leads/verify

Подтверждение заявки по `submission_token` и коду из письма

POST/v1/public/partner-leads/{publicId}/verify

Подтверждение заявки по идентификатору из ссылки письма и коду

GET/v1/public/geo/cities

Справочник городов страны (KZ, KG, UZ, RU) с поиском по началу названия

Примеры

Список интеграторов в Казахстане по WhatsApp

Запрос

bash
curl "https://api.aisar.app/v1/public/partners?country=KZ&specialization=whatsapp&locale=ru"

Ответ

json
{
  "data": [
    {
      "slug": "acme-integrations",
      "display_name": "Acme Integrations",
      "tagline": { "ru": "Внедряем WhatsApp и CRM под ключ", "en": "WhatsApp and CRM rollout end to end" },
      "logo_url": "https://api.aisar.app/v1/public/partners/acme-integrations/logo?v=1763100000",
      "countries": ["KZ"],
      "cities": [
        { "id": 101, "name": "Алматы" },
        { "id": null, "name": "Шымкент" }
      ],
      "specializations": ["whatsapp", "bitrix24"],
      "languages": ["ru", "kk"],
      "certifications": [
        { "slug": "technical-onboarding", "name": "Technical Onboarding", "badge_icon": "settings", "earned_at": "2026-10-02T09:00:00+00:00" }
      ],
      "accepts_leads": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 24, "total": 1 }
}

Карточка интегратора

Запрос

bash
curl "https://api.aisar.app/v1/public/partners/acme-integrations?locale=en"

Ответ

json
{
  "data": {
    "slug": "acme-integrations",
    "display_name": "Acme Integrations",
    "tagline": { "ru": "Внедряем WhatsApp и CRM под ключ", "en": "WhatsApp and CRM rollout end to end" },
    "logo_url": "https://api.aisar.app/v1/public/partners/acme-integrations/logo?v=1763100000",
    "countries": ["KZ"],
    "cities": [{ "id": 101, "name": "Almaty" }],
    "specializations": ["whatsapp", "bitrix24"],
    "languages": ["ru", "kk"],
    "certifications": [],
    "accepts_leads": true,
    "description": { "ru": "Команда из 12 человек.", "en": "A team of 12 people." },
    "website": "https://acme.example",
    "founded_year": 2019,
    "team_size": "6-15",
    "cases": [
      { "title": "Retail chain", "problem": "Requests got lost across messengers.", "solution": "One inbox with routing.", "result": "First reply time halved." }
    ],
    "og_image_url": null,
    "published_at": "2026-11-10T08:30:00+00:00"
  }
}

Заявка на подбор интегратора (202)

Запрос

bash
curl -X POST https://api.aisar.app/v1/public/partner-leads \
  -H "Content-Type: application/json" \
  -d '{
    "partner_slug": "acme-integrations",
    "contact_name": "Aigerim",
    "email": "aigerim@example.com",
    "country": "KZ",
    "geo_city_id": 101,
    "company_size": "6-15",
    "needs": ["whatsapp", "bitrix24"],
    "message": "Need WhatsApp inside Bitrix24.",
    "locale": "ru",
    "consent": true
  }'

Ответ

json
{ "status": "check_email", "submission_token": "Xk3m9QwR7tYb2LpZ0aVn8CdEfGhJ4sUoI5rT1uBy" }

Подтверждение заявки по submission_token

Запрос

bash
curl -X POST https://api.aisar.app/v1/public/partner-leads/verify \
  -H "Content-Type: application/json" \
  -d '{ "submission_token": "Xk3m9QwR7tYb2LpZ0aVn8CdEfGhJ4sUoI5rT1uBy", "code": "482913" }'

Ответ

json
{ "status": "verified" }

Подтверждение заявки по ссылке из письма

Запрос

bash
curl -X POST https://api.aisar.app/v1/public/partner-leads/0b6f7c1e-3a52-4d8e-9f10-6c2e5a7d9b34/verify \
  -H "Content-Type: application/json" \
  -d '{ "code": "482913" }'

Ответ

json
{ "status": "verified" }

Неверный код (422)

Запрос

bash
curl -X POST https://api.aisar.app/v1/public/partner-leads/verify \
  -H "Content-Type: application/json" \
  -d '{ "submission_token": "Xk3m9QwR7tYb2LpZ0aVn8CdEfGhJ4sUoI5rT1uBy", "code": "000000" }'

Ответ

json
{ "error": "invalid_code" }

Карта сайта каталога

Запрос

bash
curl "https://api.aisar.app/v1/public/partners/sitemap"

Ответ

json
{
  "data": [
    { "slug": "acme-integrations", "updated_at": "2026-11-10T08:30:00+00:00" },
    { "slug": "northwind-digital", "updated_at": "2026-11-12T14:05:00+00:00" }
  ]
}

Логотип интегратора (файл изображения)

Запрос

bash
# 200: the image itself (image/png, image/jpeg, image/webp or image/svg+xml),
# Cache-Control: public, max-age=300, X-Content-Type-Options: nosniff.
# Use "og-image" instead of "logo" for the link preview image.
curl "https://api.aisar.app/v1/public/partners/acme-integrations/logo" \
  -o acme-logo.png

Поиск города

Запрос

bash
curl "https://api.aisar.app/v1/public/geo/cities?country=KZ&q=алм&locale=ru"

Ответ

json
{
  "data": [
    { "id": 101, "code": "KZ-ALA", "name": "Алматы", "region": "Алматы", "is_admin_center": true }
  ]
}