Заказы с Вашего сайта: приём заявок в Учет3Д

Покупатель оформляет покупку на Вашем сайте, а Учет3Д получает заявку: кто обратился, какие товары выбрал и куда их доставить. Вы проверяете состав, цены и доставку, затем сами создаёте заказ. До подтверждения не появляются заказ, карточка клиента, оплата или списание со склада.

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

Сайт передаёт данные через API, интерфейс для программ. Для этого создаётся отдельный ключ с правом «Создавать заявки». Он не читает каталог, клиентов и заказы и не меняет их. Ключ из карточки «Свой сайт и Excel» остаётся ключом только для чтения и для приёма заявок не подходит.

Подключите сайт

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

Для каждого сайта создайте своё подключение. Храните ключ в настройках приёмщика Tilda или на сервере сайта. Не вставляйте его в код открытой страницы, адрес запроса, общедоступную таблицу или сообщения покупателям. Передача контактов и согласие покупателей оформляются на Вашем сайте; поручение в настройках Учет3Д их не заменяет.

Tilda: настройка формы

В Tilda откройте «Настройки сайта» → «Формы» → «Webhook». Webhook здесь означает автоматическую отправку заполненной формы в Учет3Д.

  1. Вставьте адрес Tilda из окна с ключом. Он заканчивается на /api/public/v1/order-requests/tilda.
  2. В настройках ключа API выберите передачу в заголовках. Имя: X-Uchet3D-Key, значение: Ваш ключ Учет3Д. Передача ключа полем формы не поддерживается.
  3. Для корзины включите отправку товаров массивом и передачу externalid. Внешний код каждого товара в Tilda должен совпадать с артикулом товара Учет3Д.
  4. Сохраните подключение. В содержимом нужной формы отметьте этот приёмщик, сохраните и опубликуйте страницу. Поля контактов назовите Name, Phone, Email, пожелания: Comments.
  5. Отправьте пробную покупку со своей опубликованной страницы и найдите её в заявках Учет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 означает, что отправка в этом подключении не найдена.

Ограничения

<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. Новую несовместимую версию следует подключать отдельно; адреса этого руководства относятся только к первой версии.

Исходящие уведомления о смене статуса, изменение товаров, клиентов и остатков через этот ключ не поддерживаются.