API-токены и вебхуки

Токены и вебхуки нужны, чтобы подключить 3D Print Pricing к Home Assistant, Discord, Slack, n8n или собственным скриптам. Полная документация с песочницей — на странице для разработчиков.

Как это работает

Токен доступа.

1. Откройте «Настройки → Интеграции → Разработчикам → Токены доступа».
2. Создайте токен и выберите срок: 30 дней, 90 дней, 1 год (по умолчанию) или без срока. Можно иметь до 10 действующих токенов.
3. Скопируйте токен сразу. На почту придёт письмо о создании — если это были не вы, удалите токен.
4. Заведите отдельный токен под каждую интеграцию, чтобы отозвать один, не трогая остальные.

Токен с полным доступом даёт доступ к заказам, принтерам, филаментам, расчёту и вебхукам. Он не управляет аккаунтом: нельзя выпускать токены, делать бэкап, менять пароль и почту, удалять аккаунт, приглашать людей, завершать сессии, отправлять документы по почте и давать принтеру команды паузы или остановки.

Вебхуки. В «Интеграции → Разработчикам» добавьте канал: свой адрес, Home Assistant, Discord или Slack. Адрес должен быть публичным https. Для каждого канала галочками выбираются события: новый заказ, смена статуса заказа, печать завершена, ошибка печати, филамент заканчивается, новая заявка из каталога мастеров, счёт оплачен клиентом. У старых каналов остаются два заказных события, новые включаются вручную. Тело запроса подписывается, примеры данных — на странице для разработчиков.

Токен «только чтение»: свой сайт и Excel

При создании токена выберите права:

• Только чтение (по умолчанию) — отметьте разделы: каталог моделей, заказы, клиенты, склад, заявки. Такой токен ничего не меняет: любой запрос на изменение получит ошибку 403, как и раздел, который вы не отметили. Персональные данные клиентов (имя, телефон, почта) в ответах появляются, только если отметить соответствующую галочку.
• Полный доступ — как у прежних токенов (плагин слайсера, Home Assistant, n8n). Все токены, созданные раньше, остались с полным доступом; в списке у каждого видна метка прав.

Для таблиц есть готовые списки с постраничной выдачей, фильтром «изменено с» и выгрузкой в CSV: /read-api/orders, /read-api/clients, /read-api/stock, /read-api/models, /read-api/leads. Лимит — 120 запросов в минуту на токен.

Excel. «Данные → Получить данные → Из других источников → Пустой запрос → Расширенный редактор». Вставьте запрос из раздела «API на чтение» на странице для разработчиков и подставьте свой токен. Если используете обычное «Из Интернета» — выберите «Расширенное» и добавьте заголовок Authorization со значением Bearer pat_…. Обновляйте данные кнопкой «Обновить всё».

Google Таблицы. Токен в ссылке (формула IMPORTDATA) не поддерживается: ссылки сохраняются в истории браузера и логах, а заголовки IMPORTDATA передавать не умеет. Используйте «Расширения → Apps Script» — короткий скрипт с UrlFetchApp есть на странице для разработчиков.

Свой сайт. Для публичной витрины токен не нужен: анкета мастера, бейдж и виджет оценки открыты. Если берёте данные на своём сервере, держите токен только там, не в коде страницы.

Частые вопросы

Интеграция вдруг перестала работать. Возможно, истёк срок токена — создайте новый.

Приходят ли повторы, если приёмник недоступен? Нет, доставка без повторов.

Если что-то не так

Токен возвращает ошибку 401 — он истёк или удалён. Вебхук не приходит — проверьте, что адрес публичный https и нужные события отмечены.