Gumy Platform — API hub

Каталог публичных API. Один X-API-Key, единые конвенции (page/page_size, error envelope, snake_case) — выучил один сервис, остальные предсказуемы.

Все API — на стиль-гайде. Авторизация: заголовок X-API-Key: <key>. Версия в URL: /v1/.... Health-чек: GET /health без ключа. Ошибки: { "error": "…", "code": "…", "request_id": "…" } + заголовок X-Request-Id.

L6 — продуктовые фасады

api.gumy.space

Каталог авто, NLP-поиск, словари. Продуктовый фасад Auto/Sale.

auto/sale REST L6
Swagger apispec.json health

mcp.gumy.space

MCP Streamable HTTP — транспорт для AI-агента. Тот же каталог Auto/Sale, но через Model Context Protocol.

auto/sale MCP L6
health

L5 — B2B продукт

dealer.gumy.space

Дилерский кабинет: профиль компании, инвентарь, фильтры, наценки, контакты.

auto/sale REST L5 B2B
Swagger health

L1–L2 — Master-data / shared

geo.gumy.space

Страны, города мира, autocomplete, гео-координаты, расстояния. GeoNames cities1000 + русские падежи стран. Канон — /v1/countries/*, /v1/cities/{nearest,top,search,<id>,by_ids,resolve}, /v1/distance. Алиасы /v1/geo/cities/* — для легаси-консьюмеров `api.gumy.space` (см. P2 2026-05-16).

shared REST L2
Swagger health

delivery.gumy.space

Доставка и расчёт растаможки авто. POST /v1/price — стоимость, POST /v1/route — маршрут.

auto REST L2
Swagger openapi.json health

modification.gumy.space

Справочник модификаций авто (drom). POST /v1/match — подобрать mod_id по brand/model/specs. GET /v1/modifications/{mod_id} — полная карточка.

auto REST L2
Swagger apispec_1.json health

L7 — каналы / виджеты

maps.gumy.space

Карта подержанных авто. Встраивается на сайт через <iframe>. Управление URL-параметрами: theme, lang, chrome, accent, mode=browse|delivery.

auto/sale widget L7
Документация виджета Открыть карту

Связки между сервисами

Каждый сервис автономен (см. ADR-0021), но данные стыкуются по предсказуемым ключам. Главная связка:

Объявление api.gumy.space → модификация modification.gumy.space

GET /v1/cars и GET /v1/cars/{id} возвращают modification_id в Car-карточке (nullable — ~10% объявлений ещё не сматчены). По нему — прямой deep-link: 

GET https://modification.gumy.space/v1/modifications/{modification_id}

Фильтрация по модификации: 

GET https://api.gumy.space/v1/cars?modification_id=79221
GET https://api.gumy.space/v1/cars?modification_ids=79221,67234,29196

Когда у listing'а modification_id = null (свежий ingest, низкий score, нет аналога в drom) — можно вытащить вручную: 

POST https://modification.gumy.space/v1/match
{
  "brand": "Toyota", "model": "Camry", "year": 2018,
  "engine_volume_cc": 2487, "power_hp": 181,
  "body_type": "Седан", "fuel_type": "Бензин",
  "transmission": "Автомат", "drive_type": "Передний"
}
→ { "match": { "modification_id": 125944, "score": 0.99, ... }, "candidates": [...] }

Имя modification_id одинаковое везде — в Car, в фильтре, в match-ответе, в path URL. См. ADR-0028.

Получить ключ

API-ключи выдаёт администратор платформы. Напиши на api@gumy.space с описанием use-case (какой канал/интеграция, ожидаемый объём, продакшн или тест).

Стандарты