Заказы с Вашего сайта: приём заявок в Учет3Д
Покупатель оформляет покупку на Вашем сайте, а Учет3Д получает заявку: кто обратился, какие товары выбрал и куда их доставить. Вы проверяете состав, цены и доставку, затем сами создаёте заказ. До подтверждения не появляются заказ, карточка клиента, оплата или списание со склада.
Базовый обмен входит в обычную подписку Учет3Д без доплаты. Для приёма заявок нужен действующий доступ мастерской. Отозвать ключ можно и после окончания доступа.
Сайт передаёт данные через API, интерфейс для программ. Для этого создаётся отдельный ключ с правом «Создавать заявки». Он не читает каталог, клиентов и заказы и не меняет их. Ключ из карточки «Свой сайт и Excel» остаётся ключом только для чтения и для приёма заявок не подходит.
Подключите сайт
- Войдите в Учет3Д как владелец мастерской. Создавать, заменять и отзывать ключи может только владелец.
- Откройте «Заказы с Вашего сайта» в настройках: «Профиль и настройки» → «Подключения» → «Заказы с Вашего сайта».
- Нажмите «Подключить сайт», укажите название и отметьте «Поручаю Учет3Д принимать заявки от моего сайта».
- Нажмите «Создать ключ». Сохраните ключ и адрес приёма. Ключ показывается один раз.
- Для Tilda выполните настройку ниже. Для другого сайта передайте программисту эту страницу и описание OpenAPI, файл со схемами запросов и ответов.
Для каждого сайта создайте своё подключение. Храните ключ в настройках приёмщика Tilda или на сервере сайта. Не вставляйте его в код открытой страницы, адрес запроса, общедоступную таблицу или сообщения покупателям. Передача контактов и согласие покупателей оформляются на Вашем сайте; поручение в настройках Учет3Д их не заменяет.
Tilda: настройка формы
В Tilda откройте «Настройки сайта» → «Формы» → «Webhook». Webhook здесь означает автоматическую отправку заполненной формы в Учет3Д.
- Вставьте адрес Tilda из окна с ключом. Он заканчивается на
/api/public/v1/order-requests/tilda. - В настройках ключа API выберите передачу в заголовках. Имя:
X-Uchet3D-Key, значение: Ваш ключ Учет3Д. Передача ключа полем формы не поддерживается. - Для корзины включите отправку товаров массивом и передачу
externalid. Внешний код каждого товара в Tilda должен совпадать с артикулом товара Учет3Д. - Сохраните подключение. В содержимом нужной формы отметьте этот приёмщик, сохраните и опубликуйте страницу. Поля контактов назовите
Name,Phone,Email, пожелания:Comments. - Отправьте пробную покупку со своей опубликованной страницы и найдите её в заявках Учет3Д.
При подключении Tilda отправляет test=test: Учет3Д отвечает 200, без создания заявки. Tilda ждёт ответ до 5 секунд, затем делает ещё 2 попытки с интервалом в минуту. Настройки описаны в официальной справке Tilda.
Учет3Д использует formid и tranid для номера вида tilda:form48844953:467251:8442970. При повторной доставке той же формы в том же подключении второй заявки не будет. Если состав не передан или артикул не найден, заявка сохранится с замечанием: исправьте состав перед подтверждением. Хотя бы один контакт покупателя обязателен. Отметка об оплате из формы не создаёт оплату в Учет3Д.
Где проверить заявку
В карточке подключения нажмите «Открыть заявки». Используется общий список заявок Учет3Д, отдельную витрину для своего сайта включать не нужно. В заявке видны сайт, внешний номер, покупатель, состав, предложенные цены и доставка.
Откройте проверку заявки. Сравните цены сайта с текущими ценами Учет3Д, уточните артикулы и количество, подтвердите стоимость доставки. При необходимости подберите товар из каталога. Только после Вашего подтверждения появится заказ. Повторное подтверждение откроет тот же заказ.
Цена с сайта служит предложением покупателя. Даже если сайт прислал нулевую цену или отметку об оплате, окончательные цены подтверждаете Вы. Оплаты и списания оформляются обычными действиями Учет3Д.
Свой сайт: запрос из командной строки
Все адреса ниже используют учет3д.рф. Тот же домен латиницей: xn--3-htbb6cdy.xn--p1ai.
Заранее создайте товар с артикулом BOX-01 или замените его своим. Сохраните пример в request.json. Здесь цена за штуку 450 ₽ и доставка 200 ₽: суммы передаются целым числом копеек.
{
"externalId": "site-order-1042",
"customer": { "name": "Покупатель", "email": "buyer@example.com" },
"items": [
{ "sku": "BOX-01", "quantity": 2, "offeredUnitPriceMinor": 45000 }
],
"currency": "RUB",
"delivery": {
"method": "Курьер",
"address": "Адрес покупателя",
"recipient": "Покупатель",
"offeredAmountMinor": 20000
},
"comment": "Связаться перед доставкой"
}
Передайте ключ через закрытую переменную окружения UCHET3D_INCOMING_KEY, затем выполните:
curl --fail-with-body \
'https://xn--3-htbb6cdy.xn--p1ai/api/public/v1/order-requests' \
-H "Authorization: Bearer $UCHET3D_INCOMING_KEY" \
-H 'Idempotency-Key: site-order-1042' \
-H 'Content-Type: application/json' \
--data-binary @request.json
externalId - постоянный номер покупки на Вашем сайте. Idempotency-Key - ключ повтора, по которому Учет3Д узнаёт повторную отправку. Сохраните оба значения у себя до первого запроса. Для одной покупки повторяйте то же тело с теми же значениями, даже если первый ответ потерялся. Для новой покупки используйте новые значения.
Первая успешная отправка получает 201, повтор принятой отправки: 200. Тело совпадает:
{
"requestId": "11111111-1111-4111-8111-111111111111",
"receiptId": "22222222-2222-4222-8222-222222222222",
"externalId": "site-order-1042",
"status": "received",
"issues": []
}
requestId - номер заявки Учет3Д, receiptId - номер подтверждения приёма. received означает приём заявки, без обещания выполнить заказ. Сохраните ответ у себя. Изменённые данные с уже использованным внешним номером или ключом повтора получат 409: повтор не редактирует ранее принятую заявку.
Номер покупки уникален в пределах подключения. При «Заменить ключ» подключение и история повторов сохраняются. Создание другого подключения начинает другую историю: не пересылайте в него прежние покупки как новые. История повторов сохраняется и после удаления заявки.
Поля заявки для программиста
Запрос POST /api/public/v1/order-requests принимает JSON. Неизвестные поля отклоняются, включая поля для оплаты, статуса заказа и списания склада. Пробелы по краям строк удаляются. В комментарии и адресе разрешены переносы строк; остальные служебные символы не принимаются.
| Поле | Что передать |
|---|---|
externalId |
Обязательный внешний номер, до 160 символов |
customer.name |
Обязательное имя, до 80 символов |
customer.phone |
Телефон, до 50 символов и не менее пяти цифр; разрешены пробелы, скобки, точка, дефис и начальный + |
customer.email |
Почта, до 200 символов |
customer.contact |
Другой способ связи, до 200 символов |
items |
От 1 до 100 позиций; один артикул встречается один раз |
items[].sku |
Артикул действующего товара мастерской, до 120 символов |
items[].quantity |
Целое количество от 1 до 999 |
items[].offeredUnitPriceMinor |
Необязательная цена сайта за штуку целым числом мелких денежных единиц |
currency |
Обязательный трёхбуквенный код, например RUB; должен совпадать с валютой мастерской |
delivery.method |
Способ доставки, до 120 символов |
delivery.address |
Адрес, до 500 символов |
delivery.recipient |
Получатель, до 160 символов |
delivery.pickupPoint |
Пункт выдачи, до 200 символов |
delivery.offeredAmountMinor |
Необязательная стоимость доставки целым числом мелких денежных единиц |
comment |
Пожелания, до 1000 символов |
Кроме имени, нужен хотя бы один контакт: phone, email или contact. delivery и comment необязательны. Каждая денежная сумма неотрицательна и не превышает 10000000000 мелких единиц: для рублей это 100 000 000 ₽. Суффикс Minor означает сотую часть денежной единицы: 45000 для RUB равно 450 ₽. Число 450 означало бы 4,50 ₽.
Неизвестный или архивный артикул в обычном JSON-запросе даёт 422: заявка и клиент не создаются. Для Tilda состав с замечаниями сохраняется, чтобы мастер мог исправить его в общем списке. Файлы и ссылки на модели этим способом не загружаются.
Пример на JavaScript для сервера
Пример для Node.js использует встроенный fetch. Функция получает уже сохранённые у Вас тело заявки и ключ повтора. Вызывайте её на сервере, а не в браузере покупателя.
const baseUrl = 'https://xn--3-htbb6cdy.xn--p1ai';
export async function sendRequest(savedBody, savedIdempotencyKey) {
const key = process.env.UCHET3D_INCOMING_KEY;
if (!key) throw new Error('Не задан ключ Учет3Д');
const response = await fetch(`${baseUrl}/api/public/v1/order-requests`, {
method: 'POST',
headers: {
Authorization: `Bearer ${key}`,
'Content-Type': 'application/json',
'Idempotency-Key': savedIdempotencyKey,
},
body: JSON.stringify(savedBody),
signal: AbortSignal.timeout(10000),
});
const body = await response.json();
if (response.ok) return body;
const error = new Error(body.error || 'Учет3Д не принял заявку');
error.code = body.code;
error.field = body.field;
error.retryAfter = Number(response.headers.get('Retry-After') || 0);
error.status = response.status;
throw error;
}
При потере соединения сохраните задачу отправки у себя и повторите тот же запрос. После 429 или 503 дождитесь числа секунд из Retry-After. Ответ 409 или 422 требует проверки данных, бесконечно повторять его не нужно. Не записывайте ключи и контакты покупателей в общедоступные журналы ошибок.
Как узнать результат приёма
Тем же ключом можно прочитать только состояние своих отправок. Запросы выполняются последовательно и расходуют тот же предел обращений.
curl --fail-with-body \
'https://xn--3-htbb6cdy.xn--p1ai/api/public/v1/order-requests/status?externalId=site-order-1042' \
-H "Authorization: Bearer $UCHET3D_INCOMING_KEY"
Другой адрес: GET /api/public/v1/order-requests/RECEIPT_ID, где RECEIPT_ID взят из ответа приёма. Для сложного внешнего номера закодируйте значение параметра externalId как часть адреса.
{
"requestId": "11111111-1111-4111-8111-111111111111",
"receiptId": "22222222-2222-4222-8222-222222222222",
"externalId": "site-order-1042",
"status": "new",
"orderCreated": false
}
Здесь status - состояние заявки; orderCreated: true означает, что мастер создал заказ. Если заявку удалили, останется подтверждение приёма со статусом removed. Ответ не содержит контакты покупателя, состав, цены или номер заказа. 404 означает, что отправка в этом подключении не найдена.
Ограничения
- До 20 действующих подключений на мастерскую; отозванные не занимают этот предел.
- До 20 различных ключей
Idempotency-Keyна одну заявку. Новый 21-й ключ получит409; ранее использованные ключи продолжат работать. Для обычного повтора используйте исходный ключ. - До 60 обращений в минуту на ключ и до 60 суммарно на мастерскую. Проверка состояния и тест Tilda тоже считаются.
- Одновременно мастерская выполняет не больше двух запросов, сколько бы ключей у неё ни было. Одним ключом в один момент идёт один запрос.
- Тело запроса нужно передать за 10 секунд.
- Одним ключом обращайтесь последовательно. Одновременный запрос может получить
429сRetry-After: 1. - До 100 новых заявок за последние 24 часа суммарно с витрины Учет3Д и внешних сайтов. Повтор ранее принятой отправки новой заявкой не считается.
- Тело запроса до 256 КБ. В форме до 1000 полей. До 100 позиций, до 999 штук на позицию.
- Сумма товаров по ценам каталога при приёме не превышает 999 999 999 999,99 в валюте мастерской.
- Все обращения по HTTPS. Ключ только в заголовке:
Authorization: Bearer ...для JSON и чтения результата,X-Uchet3D-Keyдля Tilda.
<div id="errors" />
Ответы и ошибки
Отказ содержит текст error, постоянный код code, при ошибке поля: field. requestId в отказе - номер обращения для разбора ошибки, а не номер созданной заявки.
{
"error": "Укажите целое количество от 1 до 999.",
"code": "INCOMING_INVALID_FIELD",
"field": "items.0.quantity",
"requestId": "33333333-3333-4333-8333-333333333333"
}
| Ответ | Причина и действие |
|---|---|
200 |
Повтор приёма, ответ о состоянии или тест Tilda; обычный приём Tilda тоже отвечает 200 |
201 |
Новая заявка из JSON сохранена |
401 INCOMING_KEY_INVALID |
Нет ключа, он неверный, заменён или отозван; проверьте подключение и заголовок |
403 INCOMING_ACCESS_EXPIRED |
Закончился доступ мастерской; возобновите обычную подписку |
404 INCOMING_RECEIPT_NOT_FOUND |
Результат этой отправки не найден в подключении |
405 INCOMING_METHOD_NOT_ALLOWED |
Способ обращения не поддерживается |
408 INCOMING_BODY_TIMEOUT |
Тело запроса передавалось дольше 10 секунд; отправьте заявку одним запросом |
409 INCOMING_REPEAT_CONFLICT |
Номер или ключ повтора уже использован с другим содержимым; проверьте историю у себя |
409 INCOMING_REPEAT_KEYS_LIMIT |
У заявки уже 20 различных ключей повтора; повторите отправку с одним из ранее использованных ключей |
413 INCOMING_BODY_TOO_LARGE |
Превышен размер тела или число полей формы |
415 INCOMING_CONTENT_TYPE |
Неверный формат; JSON-запрос требует application/json |
422 INCOMING_INVALID_JSON |
Тело не разобрано как JSON |
422 INCOMING_INVALID_FIELD |
Неверное или пустое обязательное поле; смотрите field |
422 INCOMING_TOTAL_TOO_LARGE |
Сумма товаров по ценам каталога превышает предел заявки; уменьшите состав |
422 INCOMING_UNKNOWN_FIELD |
Передано неподдерживаемое поле |
422 INCOMING_SKU_NOT_FOUND |
Артикул не найден; исправьте его перед повторной отправкой |
422 INCOMING_CURRENCY_MISMATCH |
Валюта отличается от валюты мастерской; пересчитайте суммы до отправки |
429 INCOMING_RATE_LIMIT |
Превышен предел обращений, ключ занят или мастерская уже выполняет два запроса одновременно; подождите Retry-After секунд |
429 STOREFRONT_DAILY_LIMIT |
Превышен общий предел новых заявок за 24 часа; подождите Retry-After секунд |
503 INCOMING_UNAVAILABLE |
Временная недоступность; подождите Retry-After секунд и повторите ту же отправку |
Если ответ об ошибке не пришёл, исход первой попытки неизвестен. Повторите неизменённую отправку с теми же номерами. Не создавайте для неё новый ключ повтора.
Заменить или отозвать ключ
В карточке подключения «Заменить ключ» выдаёт новый секрет для того же сайта. Прежний перестаёт работать сразу: вставьте новый в настройки сайта. Накопленные заявки и защита от повторов сохраняются.
«Отозвать ключ» останавливает приём и чтение результатов этим подключением. Принятые заявки и заказы остаются. Дата последнего использования и последний ответ видны рядом с названием. Последний ответ относится также к проверке состояния и тесту подключения, поэтому наличие заявки проверяйте в общем списке.
Версия и изменения
Версия адреса: v1. Форматы доступны в описании OpenAPI. Новую несовместимую версию следует подключать отдельно; адреса этого руководства относятся только к первой версии.
- 03.11.2026: начальное описание приёма заявок, формы Tilda, подтверждений приёма, ключей и ограничений.
Исходящие уведомления о смене статуса, изменение товаров, клиентов и остатков через этот ключ не поддерживаются.