Структура и обозначения

Справка по URL, полям и соглашениям Integrations API. Каталог методов — Все методы API.

База

Префикс	/api/integrations/v1
Полный URL	https://{домен}/api/integrations/v1/{ресурс}
Протокол	HTTPS
Тело	JSON (Content-Type: application/json), кроме POST /price-lists/upload (multipart)
Авторизация	Authorization: Bearer {identifier}:{secret}

Отдельного OAuth / «получить токен» нет. Ключ создаётся в Система → Настройка API.

Идентификаторы

Поле	Смысл
id	Внутренний ID PlatParts (число в URL: /orders/42)
external_id	ID вашей системы (строка). Каталог: товар, категория, атрибут. Документы: внешняя ссылка
product_external_id	Внешний ID товара при записи остатков
external_ids	Массив внешних ID (удаление / деактивация)
category_external_id / category_external_ids	Привязка товара к категориям
parent_external_id	Родитель категории
group_external_id	Группа атрибута
meta	Произвольный JSON у заказа/пользователя — удобно хранить ID сделки CRM

Связка «ваша система ↔ PlatParts»:

• каталог: ключ — external_id;
• заказы/клиенты: ключ — id PlatParts + ваш ID в meta (или outbound webhook);
• документы: POST .../external-ref с external_id.

Права (scopes)

Строковые коды вида orders.read, products.write. Назначаются роли API. Полный список — Авторизация.

Формат: {сущность}.{действие}.

Суммы и цены

Направление	Единицы
Запись (POST / PATCH, остатки, платежи, позиции заказа)	копейки (150000 = 1500 ₽)
Чтение snapshot	обычно рубли

Подробнее при ошибках «цена в 100 раз» — Ошибки API.

Даты и пагинация

Даты	ISO-8601
since	фильтр по updated_at (где есть)
per_page	1–100, по умолчанию 50
cursor	курсор следующей страницы

Ответ списка: data, per_page, next_cursor, next_page_url, …

Карта ресурсов

/orders, /orders/{id}, …/status, …/meta, …/archive
/orders/{orderId}/items, /orders/{orderId}/items/{itemId}, …/status, …/archive
/statuses/orders, /statuses/order-items
/users, /users/{id}, …/meta
/organizations
/payments, /payments/{id}
/documents, /documents/{id}/external-ref
/products, /products/{id}, /products/batch-upsert, /products/delete
/categories/batch-upsert, /categories/delete
/stocks/batch-update
/pricing/search
/price-lists/upload, /price-lists/status
/modules
/pickup-points
/integrations/{package}/sync
/integrations/inbound/{package}/{instance}   ← не Bearer API-ключа

Привязка к уже существующему

1. Прочитайте сущность (GET списка/карточки) — id, external_id, фото, статусы.
2. Обновляйте по найденному ключу; не создавайте дубль.
3. Для товара: если has_images: true, не передавайте images в upsert — фото сохранятся.
4. Статусы берите из справочника по id (или code).

Каталог vs прайс-листы

API	Что это
products / categories / stocks	JSON → каталог наличия
price-lists/upload	Файл → модуль Прайс-листы (проценка «Обычный прайс-лист»)

Не путать: файл прайса не создаёт карточки каталога через products/batch-upsert.

Чего нет в этом API

• Создание/правка точек выдачи и организаций (только чтение).
• Создание PDF/содержимого документов (только список и внешний ID).
• Отдельные legacy-эндпоинты /api/b2b и /api/1c.

Дальше

• Быстрый старт
• Все методы API
• Работа с заказами — основной сценарий CRM