API / DE2COM Documentation

Quick start

Базовый запрос

Web-демо на 1cars.store обращается к API через same-origin proxy. Для серверной B2B-интеграции ключ доступа передаётся только с backend-кода клиента.

GET · список Copart лотов

curl 'https://1cars.store/api/v2/copart-lots?populate=*&pagination[page]=1&pagination[pageSize]=8&sort[0]=createdAt:desc' \
  -H 'Authorization: Bearer <API_KEY>'

Безопасность: API-ключ нельзя хранить в браузерном JavaScript, HTML или публичном репозитории. Клиентская страница должна ходить через серверный proxy/BFF, который добавляет секрет на сервере.

Source-agnostic ingestion

Архитектура, на которой строится развитие API

Адаптер изолирует специфику источника, pipeline отвечает за сбор и качество, нормализатор приводит данные к целевой модели, а публичный API выдаёт стабильный контракт. Агентный слой может управлять задачами сбора, проверкой качества и повторной обработкой, но не подменяет API.

Source adapterAPI · web · DB · files

Collector Agentjobs · retry · health

Normalizermapping · dedupe

Storageraw · core · history

Public APIstable contract

Почему так

Изменения конкретного источника изолируются в адаптере. Клиент не должен переписывать интеграцию при изменении DOM, внешнего API, схемы базы, формата файла или внутренних полей источника.

Роль AI

AI/ML подключается к контролю качества, сопоставлению сущностей, поиску и аналитике. Критические действия ограничиваются правилами, логированием и проверяемыми workflow.

Авторизация

Для защищённых серверных запросов используется Bearer token. Конкретный production base URL и ключ выдаются при подключении. На 1cars.store браузер обращается к относительному пути /api/…, а серверный proxy добавляет авторизацию.

Authorization: Bearer <API_KEY>
Accept: application/json

GET/api/v2/copart-lots

Список лотов Copart

Текущий frontend использует Strapi-style query parameters: populate, filters, pagination и sort.

Параметр	Пример	Назначение
`populate`	`*`	Связанные сущности
`pagination[page]`	`1`	Страница
`pagination[pageSize]`	`8`	Размер страницы
`sort[0]`	`createdAt:desc`	Сортировка
`filters[vehicleTypeCode][$eq]`	`VEHTYPE_V`	Тип транспорта
`filters[copart_raw_datum][raw][$notNull]`	`true`	Только записи с исходными данными

Сокращённый пример ответа

{
  "data": [
    {
      "documentId": "jsw7hosc51ctir2djlmdkfo1",
      "vin": "5XYK23DF2TG******",
      "lotNumber": "79653265",
      "lotMakeCode": "KIA",
      "lotModel": "SPORTAGE",
      "damageDescription": "REAR END",
      "source": "copart",
      "copart_vehicle_detail": {
        "lotYear": "2026",
        "engine": "2.5L 4",
        "transmissionType": "AUTOMATIC"
      },
      "copart_sale_info": {
        "auctionDate": "2026-03-09T16:00:00.000Z",
        "state": "LA",
        "country": "USA"
      }
    }
  ],
  "meta": { "pagination": { "page": 1, "pageSize": 8 } }
}

GET/api/v2/copart-lots/{documentId}?populate=*

Карточка лота

Идентификатор, используемый текущим frontend, — documentId. Ответ содержит основной объект лота и связанные блоки vehicle detail, sale info, dynamic state и raw data.

GET/api/v1/test-v1-images/fetch?url={encodedUrl}

Image proxy

Текущий интерфейс загружает изображения через серверный image proxy. URL исходного изображения обязательно кодируется через encodeURIComponent().

const src = `/api/v1/test-v1-images/fetch?url=${encodeURIComponent(imageUrl)}`;

Текущая модель данных

Контракт пока сохраняет source-specific связанные сущности Copart. Целевое направление roadmap — каноническая source-agnostic модель поверх адаптеров, при этом raw payload остаётся доступен внутреннему pipeline для аудита и повторной обработки.

lot

VIN, lot number, make/model, damage, status, source, thumbnail.

copart_vehicle_detail

Year, engine, fuel, transmission, drive, color, odometer, title.

copart_sale_info

Auction date, location, state/country, currency, sale metadata.

copart_dynamic / raw

Dynamic bid/sale state and original source representation.

HTTP и ошибки

2xx

Запрос обработан.

4xx

Ошибка параметров, авторизации или доступа.

5xx

Ошибка upstream/pipeline.

504

Timeout upstream; рекомендуется контролируемый retry с backoff.

API roadmap

Развитие API-платформы

Universal source adaptersplatform

Подключение внешних API, сайтов, баз данных, файлов и корпоративных систем через единый слой адаптеров, очередей и контроля качества.

IAAI adapter + API mappingroadmap

Сначала ingest и mapping в core-модель, затем внешний контракт после стабилизации тестового контура.

China auction/source adaptersresearch

Отбор источников, исследование доступности и схем данных, после чего — адаптеры и нормализация.

Unified source-agnostic APItarget

Source-agnostic API-контракты, исторические состояния, события/webhooks, SLA-метрики и переиспользуемые интеграционные шаблоны для разных предметных областей.

Универсальная API-архитектура. Copart — действующий пример.