Данные Учет3Д на своём сайте и в Excel

Ваш сайт или Excel могут получать данные мастерской через API, интерфейс для программ. Вы выбираете, какие разделы доступны ключу: витрина, заказы, отзывы, заявки с витрины или остатки склада.

Учет3Д разрешает владельцу мастерской автоматически получать свои данные из выбранных разделов через этот штатный API, в пределах ограничений на этой странице. Ключ работает только для чтения и не открывает данные других мастерских.

Ключ храните на своём сервере, не вставляйте в код страницы

Запросы к заказам, данным покупателей, отзывам, заявкам и складу выполняйте на своём сервере или из закрытой книги Excel. Из браузера эти разделы недоступны.

Браузер может получить только открытый каталог витрины: создайте для этого отдельный ключ с единственным разделом «Витрина», без личных данных. Ключ с любыми другими разделами из браузера не работает даже при запросе каталога. Для сайта рекомендуем хранить и такой ключ на сервере.

Ключ работает, пока у мастерской есть действующий доступ к Учет3Д, например пробный период или оплата. После окончания доступа запрос получит понятный отказ. Отозвать ключ можно и после окончания доступа.

Как получить ключ

Откройте «Свой сайт и Excel» в настройках или пройдите по шагам:

Войдите как владелец мастерской. Сотрудникам создание и отзыв ключей пока недоступны.
Откройте «Профиль и настройки» → «Подключения» → «Свой сайт и Excel».
Нажмите «Создать ключ» и укажите название, например «Сайт мастерской» или «Excel: заказы».
Выберите разделы, которые нужны программе. Ключ без раздела «Заказы» не сможет получить заказы.
При необходимости отметьте «Включить личные данные покупателей». Без этой галочки имена, контакты и тексты покупателей не передаются.
Отметьте поручение «Поручаю Учет3Д передавать моей программе данные из выбранных разделов» и нажмите «Создать ключ».
Скопируйте ключ и сохраните его. Он показан один раз: после закрытия окна получить тот же ключ снова нельзя.

Для сайта храните ключ на сервере и добавляйте его к запросам там. Не вставляйте ключ в код открытой страницы, адрес ссылки или общедоступную таблицу. Книга Excel хранит ключ в запросе: не публикуйте и не передавайте такую книгу другим людям.

Контакты покупателей доступны только Вашей программе. Храните ключ на сервере и не размещайте контакты в открытом доступе. Галочка личных данных не разрешает публиковать покупателей на сайте. Почта из карточки клиента не передаётся; в контакте заявки с витрины может быть почта, указанная самим покупателем при отправке заявки.

Запрос из командной строки

Адрес сайта: учет3д.рф, тот же адрес латиницей: xn--3-htbb6cdy.xn--p1ai.

Пример для программы curl. Замените ВАШ_КЛЮЧ сохранённым значением. Ключ передаётся в заголовке Authorization, не в адресе запроса.


curl --fail-with-body \
  'https://xn--3-htbb6cdy.xn--p1ai/api/public/v1/products?page=1&pageSize=50' \
  -H 'Authorization: Bearer ВАШ_КЛЮЧ' \
  -H 'Accept: application/json'

Чтобы прочитать заказы, замените products на orders. У ключа должен быть выбран соответствующий раздел.

Все ответы содержат массив записей data и сведения о странице pagination:


{
  "data": [],
  "pagination": { "page": 1, "pageSize": 50, "hasMore": false }
}

Здесь показан пример пустого ответа. hasMore: true означает, что нужно запросить следующую страницу. Увеличивайте page на 1, сохраняя тот же pageSize, пока hasMore не станет false.

Заказы в Excel через Power Query

Power Query, встроенное средство Excel для получения данных, может читать заказы и обновлять таблицу по команде «Обновить».

Создайте ключ с разделом «Заказы».
В Excel откройте «Данные» → «Получить данные» → «Из других источников» → «Пустой запрос». Названия пунктов могут отличаться в Вашей версии Excel.
Откройте «Расширенный редактор» и вставьте код ниже. Замените ВАШ_КЛЮЧ сохранённым ключом.
Если Excel спросит способ подключения к этому сайту, выберите «Анонимный»: ключ уже передаётся в заголовке запроса.
Нажмите «Готово», затем «Закрыть и загрузить».


let
    ApiKey = "ВАШ_КЛЮЧ",
    BaseUrl = "https://xn--3-htbb6cdy.xn--p1ai/",
    GetPage = (PageNumber as number) as record =>
        Json.Document(Web.Contents(BaseUrl, [
            RelativePath = "api/public/v1/orders",
            Query = [page = Text.From(PageNumber), pageSize = "100"],
            Headers = [Authorization = "Bearer " & ApiKey, Accept = "application/json"]
        ])),
    Pages = List.Generate(
        () => [Number = 1, Response = GetPage(1)],
        each [Response] <> null,
        each if [Response][pagination][hasMore]
            then [Number = [Number] + 1, Response = GetPage([Number] + 1)]
            else [Number = [Number] + 1, Response = null],
        each [Response][data]
    ),
    Orders = Table.FromRecords(List.Combine(Pages))
in
    Orders

Запрос собирает все страницы заказов. Вложенный список items содержит позиции заказа: раскройте его в редакторе, если нужна отдельная строка для каждой позиции. Для витрины замените orders на products и выберите раздел «Витрина» у ключа.

Описание используемых команд у Microsoft: Web.Contents, запрос к сайту и List.Generate, последовательное получение страниц.

Разделы и поля ответа

Все адреса начинаются с /api/public/v1/. Даты и время передаются строками ISO 8601, например 2026-10-08T09:30:00Z, где Z означает время по Гринвичу. Отсутствующее значение может быть null.

Раздел ключа	Адрес	Поля каждой записи без личных данных
Витрина	`products`	`id`, `name`, `price`, `priceMode`, `priceMax`, `currency`, `photoUrl`, `galleryUrls`, `inStock`, `available`, `createdAt`
Заказы	`orders`	`id`, `orderNumber`, `status`, `paymentStatus`, `orderDate`, `dueDate`, `totalAmount`, `paidAmount`, `createdAt`, `updatedAt`, `items`
Отзывы	`reviews`	`id`, `orderId`, `productId`, `rating`, `moderationStatus`, `createdAt`
Заявки с витрины	`requests`	`id`, `kind`, `status`, `orderId`, `totalPrice`, `totalPriceMax`, `createdAt`, `handledAt`, `items`
Остатки склада	`stock`	`id`, `kind`, `name`, `unit`, `quantity`, `reserved`, `available`

Витрина: price и priceMax задают цену и верхнюю границу диапазона, priceMode - способ указания цены, currency - валюту. photoUrl и galleryUrls - фотографии. inStock - наличие, available - доступное количество.
Адреса фото могут начинаться с /api/images/. Дополните такой адрес доменом Учет3Д, например https://xn--3-htbb6cdy.xn--p1ai/api/images/.... Полные адреса, начинающиеся с https://, используйте без изменения.
Заказы: totalAmount - итоговая сумма к оплате с учётом скидки, наценки и корректировки, в том числе ноль для бесплатного заказа; paidAmount - оплаченная сумма. У каждой позиции в items: id, productId, quantity, unitPrice, totalPrice, status.
Отзывы: moderationStatus равен published для опубликованного отзыва или hidden для скрытого. Владелец получает оба вида, поэтому при показе отзывов на своём сайте отбирайте только published.
Заявки: у каждой позиции в items: id, productId, quantity, unitPrice, unitPriceMax.
Остатки: quantity - количество, reserved - резерв, available - доступный остаток. kind различает product (товар), material (материал), packaging (упаковка), printerPart (запчасть принтера), partVariant (вариант комплектующего). Материалы передаются в килограммах; для других записей смотрите unit.

При включённых личных данных добавляются следующие поля:

Раздел	Дополнительные поля
Заказы	`client`: объект с `name`, `phone`, `shippingAddress`
Отзывы	`text`: текст отзыва
Заявки	`clientName`, `contact`, `comment`, `custom`

В заявке contact - строка с контактом, который оставил покупатель. Объект custom для индивидуального расчёта содержит fileName, sizeMm с размерами x, y, z в миллиметрах, volumeCm3 и quantity. Сами модели, файлы, ссылки для доступа и примечания к заказам не передаются.

Ограничения и причины отказа

До 20 действующих ключей у мастерской. Отозванные ключи этот предел не занимают.
До 60 запросов в минуту на ключ и 60 запросов в минуту суммарно на мастерскую. Несколько ключей используют общий предел мастерской. После ответа 429 подождите число секунд из заголовка Retry-After и повторите запрос. У других мастерских свой предел.
Одним ключом отправляйте запросы последовательно. Одновременные обращения могут получить 429 с Retry-After: 1.
page начинается с 1, pageSize - от 1 до 100. Без параметров возвращается первая страница по 50 записей.
Ответ витрины может обновляться с задержкой до 15 секунд. Отзыв ключа действует сразу, в том числе для витрины.
401 - ключ не передан, не найден или отозван. Проверьте заголовок и при необходимости создайте новый ключ.
403 - у ключа нет нужного раздела, запрос к закрытым данным сделан из браузера или закончился доступ мастерской. В ответе указана причина. Проверьте разделы ключа, выполняйте закрытые запросы на сервере или возобновите доступ к Учет3Д.
400 - неверные параметры страницы. Проверьте page и pageSize.
Ключом можно делать только запросы чтения GET. Изменение данных недоступно.

Как остановить доступ

В карточке «Свой сайт и Excel» найдите ключ по названию и нажмите «Отозвать ключ». Появится отметка «Ключ отозван», а следующие запросы с ним получат отказ. Если отзыв не удался, сообщение останется рядом с ключом и действие можно повторить.

В списке видно последнее использование ключа. Чтобы заменить ключ или изменить набор разделов, создайте новый, обновите его в своей программе и отзовите прежний.