Службы доставки: API для подключения

Что это#

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

Договор с Shuqr не нужен. Условия, цены и расчёты вы обсуждаете напрямую с заведением.

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

1. Заведение подключает вашу службу у себя в настройках и нажимает «Проверить подключение» – Shuqr присылает ping.
2. Когда пора везти заказ, Shuqr присылает delivery.create. В течение 10 секунд вы отвечаете своим номером заявки id.
3. Курьер движется – вы отправляете этапы на callbackUrl из заказа: назначен, едет в заведение, забрал заказ.
4. Этап delivered закрывает заказ у заведения: он становится «Выдан». По пути кассир и гость видят курьера и текущий этап.
5. Пока курьер не забрал заказ, заведение может его отменить. Тогда придёт delivery.cancel.

Как проходит подключение#

1. Вы даёте заведению адрес своего сервера (только https://) и ключ подписи – длинную случайную строку, которую придумываете сами. У каждого заведения ключ свой.
2. Заведение открывает в Shuqr «Настройки → Доставка», в блоке «Кто везёт» добавляет «Другая служба по API» и вводит ваш адрес, ключ и цену доставки – её платит гость. Время доставки для гостя можно указать по желанию.
3. Когда заказ оплачен и пора везти, Shuqr отправляет вам запрос delivery.create. Дальше вы сообщаете этапы доставки.

Заведение может подключить несколько служб и выбрать, какая основная. Если вы откажетесь от заказа или не ответите, заказ уйдёт следующей службе или кассиру заведения.

Несколько заведений

У каждого заведения свой ключ подписи. Проще всего дать каждому заведению свой адрес, например https://your-service.example.com/shuqr/cafe-pelmen, где cafe-pelmen – код заведения, который вы придумали сами. Пришёл запрос – по коду из адреса найдите ключ этого заведения и уже им проверьте подпись.

В delivery.create есть и поле restaurantId – номер заведения в Shuqr. По нему тоже можно понять, чей это заказ. Но верьте ему только после проверки подписи.

В ping поля restaurantId нет. Это ещё одна причина дать каждому заведению отдельный адрес.

Что нужно сделать у себя#

• Адрес HTTPS, который принимает POST с JSON и понимает три события: ping, delivery.create, delivery.cancel.
• Отдельный адрес и ключ для каждого заведения (см. «Несколько заведений»).
• Проверку подписи X-Shuqr-Signature на каждом запросе.
• Защиту от повторов: второй delivery.create с тем же deliveryId не должен создавать вторую заявку.
• Ваш номер заявки id в ответе на delivery.create.
• Отправку этапов на callbackUrl из заказа – при каждом изменении.

Запросы от Shuqr#

Shuqr отправляет запрос POST на адрес, который заведение указало в настройках. Тело – JSON в кодировке UTF-8.

ping – проверка связи

Когда заведение нажимает «Проверить подключение» в настройках, Shuqr присылает ping с подписью. Ответьте любым кодом 2xx – заведение увидит «Подключение работает». Неверная подпись – ответьте 401, и заведение увидит, что ключ нужно проверить.

{ "event": "ping" }

delivery.create – новый заказ

Приходит, когда пора везти оплаченный заказ. Момент выбирает заведение: сразу после того, как заказ принят, когда кухня начала готовить, когда заказ готов, или вручную – кассир нажимает кнопку. Поэтому курьеру иногда придётся подождать в заведении. Номер orderNumber поможет забрать нужный заказ.

1{
2  "event": "delivery.create",
3  "restaurantId": "cmh8x2p1q0000ab3c",
4  "deliveryId": "cmhf2k9x80001qa7z",
5  "orderNumber": "42",
6  "callbackUrl": "https://shuqr.ru/api/delivery/webhook/webhook?delivery=cmhf2k9x80001qa7z&sig=5e1c0f3a9b2d4e6f8a7b9c0d1e2f3a4b",
7  "pickup": {
8    "lat": 55.7601,
9    "lng": 37.6187,
10    "address": "Moscow, Tverskaya st, 7",
11    "contact": { "name": "Cafe Pelmen", "phone": "+74950000000" }
12  },
13  "dropoff": {
14    "lat": 55.7712,
15    "lng": 37.6329,
16    "address": "Moscow, Sretensky blvd, 4, apt 15",
17    "comment": "apt 15, entrance 2, floor 4, intercom 15",
18    "details": {
19      "city": "Moscow",
20      "street": "Sretensky blvd",
21      "house": "4",
22      "block": null,
23      "flat": "15",
24      "entrance": "2",
25      "floor": "4",
26      "intercom": "15",
27      "geoQuality": 0
28    },
29    "contact": { "name": "Anna", "phone": "+79990001122" }
30  },
31  "items": [
32    { "name": "Pelmeni", "quantity": 2, "price": 390 },
33    { "name": "Mors", "quantity": 1, "price": 150 }
34  ],
35  "total": 1180,
36  "price": 250,
37  "currency": "RUB",
38  "scheduledAt": null,
39  "comment": "Please call when you arrive",
40  "locale": "ru",
41  "paid": true
42}

Адрес гостя по частям

Если адрес выбран из подсказки, в dropoff.details приходят его части – по ним удобно искать дом в своей базе и показывать курьеру квартиру и подъезд отдельно. Все поля необязательные: у заказа, где адрес набран вручную, частей может не быть.

Суммы – в рублях (или другой валюте из currency), не в копейках. Могут быть дробными, например 249.5.

Код 2xx и JSON с вашим номером заявки в id. В status можно сразу передать этап – обычно searching. Если status нет, Shuqr считает, что вы ищете курьера.

{ "id": "A-1042", "status": "searching" }

Если тот же заказ передадут ещё раз (например, после отказа), придёт новый deliveryId – это новая заявка. Повтор с тем же deliveryId – тот же заказ: верните уже созданную заявку.

delivery.cancel – отмена

Приходит, когда заведение отменило заказ или вернуло гостю деньги, а также когда вы слишком долго ищете курьера (срок задаёт заведение). В поле id – ваш номер заявки из ответа на delivery.create.

{ "event": "delivery.cancel", "deliveryId": "cmhf2k9x80001qa7z", "id": "A-1042" }

Отменили – ответьте 2xx. Такой заявки нет – 404, это тоже считается отменой. Курьер уже везёт заказ и отменить нельзя – 409.

Если вы ответили 409, заведение увидит, что отменить не удалось. Свяжитесь с ним, чтобы договориться, что делать с заказом.

Как Shuqr понимает ваш ответ

При любой ошибке на delivery.create заказ уходит запасной службе заведения или кассиру. Сам Shuqr этот запрос не повторяет.

В ответе с ошибкой можно передать поле error с понятным текстом. Shuqr сохранит его в истории доставки – так проще разобраться в сбое.

Проверка подписи#

Подпись доказывает, что запрос пришёл от Shuqr и его никто не менял. Shuqr берёт тело запроса как есть и считает от него HMAC-SHA256 с ключом, который заведение ввело в настройках. Результат в hex с приставкой sha256= лежит в заголовке X-Shuqr-Signature. Вы делаете то же самое у себя и сравниваете строки.

• Считайте подпись от «сырого» тела – ровно тех байтов, что пришли. Если сначала разобрать JSON и собрать заново, подпись не сойдётся.
• Сравнивайте функцией с постоянным временем: hash_equals в PHP, crypto.timingSafeEqual в Node.js.
• Подпись не сошлась – ответьте 401 и ничего не делайте с заказом.

1const http = require('node:http');
2const crypto = require('node:crypto');
3
4// The signing key you gave to the restaurant. With several restaurants give each one its own address,
5// e.g. /shuqr/cafe-pelmen, and look up that restaurant's key by the code from req.url.
6const SECRET = process.env.SHUQR_SECRET;
7
8// The signature is calculated over the raw request body, byte for byte.
9function isFromShuqr(rawBody, header) {
10  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex'));
11  const received = Buffer.from(header || '');
12  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
13}
14
15function reply(res, code, data) {
16  res.writeHead(code, { 'Content-Type': 'application/json' });
17  res.end(JSON.stringify(data));
18}
19
20http.createServer((req, res) => {
21  const chunks = [];
22  req.on('data', (chunk) => chunks.push(chunk));
23  req.on('end', () => {
24    const rawBody = Buffer.concat(chunks);
25    if (!isFromShuqr(rawBody, req.headers['x-shuqr-signature'])) {
26      return reply(res, 401, { error: 'Bad signature' });
27    }
28    const event = JSON.parse(rawBody.toString('utf8'));
29
30    if (event.event === 'ping') {
31      return reply(res, 200, { ok: true });
32    }
33    if (event.event === 'delivery.create') {
34      // Your code: save the order together with event.callbackUrl.
35      // If an order with this event.deliveryId already exists, return it, do not create a second one.
36      const order = saveOrder(event);
37      return reply(res, 200, { id: order.id, status: 'searching' });
38    }
39    if (event.event === 'delivery.cancel') {
40      // Your code: cancel the order. false = the courier already has the food.
41      const cancelled = cancelOrder(event.deliveryId);
42      return cancelled ? reply(res, 200, { ok: true }) : reply(res, 409, { error: 'Courier already picked up the order' });
43    }
44    reply(res, 400, { error: 'Unknown event' });
45  });
46}).listen(8080);

Оба примера проверены на настоящих запросах Shuqr. Функции saveOrder и cancelOrder – ваш код: сохранить заявку и отменить её.

Как сообщать этапы доставки#

Когда у заявки что-то меняется, отправьте POST с JSON на callbackUrl из заказа. Используйте адрес точно в том виде, в каком он пришёл, ничего в нём не меняйте.

Поля

Присылайте только то, что изменилось: поле, которого нет в запросе, остаётся прежним. Только status нужен всегда.

{
  "status": "assigned",
  "id": "A-1042",
  "courier": { "name": "Oleg", "phone": "+79990003344" },
  "trackingUrl": "https://track.example.com/A-1042",
  "etaDropoffAt": "2026-11-01T19:40:00+03:00",
  "price": 250
}

Этапы

Обычный путь: searching → assigned → to_pickup → picked_up → delivered.

• Этапы идут только вперёд. Если прислать более ранний этап, Shuqr его пропустит. Исключение – курьер отказался до того, как забрал заказ: можно вернуть searching и искать другого.
• delivered, cancelled и failed – последние. После них Shuqr ничего не меняет, поэтому итоговую цену присылайте не позже последнего этапа.
• failed или cancelled до того, как курьер забрал заказ, – Shuqr сразу передаёт заказ запасной службе заведения или кассиру.
• Курьер забрал заказ, но вручить не смог: пришлите returning с причиной, например guestRefused. Когда курьер вернёт заказ в заведение, пришлите cancelled с причиной returned. Дальше решает кассир.

{ "status": "returning", "id": "A-1042", "reason": "guestRefused" }

{ "status": "cancelled", "id": "A-1042", "reason": "returned" }

Причины

Первые четыре причины – для отказа до того, как курьер забрал заказ. Остальные – когда курьер уже забрал заказ, но вручить не смог.

Другие значения reason Shuqr не запоминает, но сам этап примет.

Что ответит Shuqr

Нет ответа или код 5xx – повторите запрос чуть позже.

curl -X POST "https://shuqr.ru/api/delivery/webhook/webhook?delivery=cmhf2k9x80001qa7z&sig=5e1c0f3a9b2d4e6f8a7b9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{"status": "picked_up", "id": "A-1042"}'

Как проверить#

• Отдельной тестовой среды у Shuqr пока нет. Проверяют подключение вместе с заведением, которое хочет работать с вами.
• Ваш адрес должен быть доступен из интернета по HTTPS. Чтобы проверить сервер на своём компьютере, используйте туннель, например ngrok или Cloudflare Tunnel.
• Записывайте в журнал каждый входящий запрос целиком: заголовки и сырое тело. Так проще разобраться, если подпись не сходится.
• Подпись можно проверить без Shuqr: подпишите тестовое тело сами и отправьте себе запрос, как в примере ниже.

BODY='{"event":"ping"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SHUQR_SECRET" | sed 's/^.* //')
curl -X POST "https://your-service.example.com/shuqr" \
  -H "Content-Type: application/json" \
  -H "X-Shuqr-Event: ping" \
  -H "X-Shuqr-Signature: sha256=$SIG" \
  -d "$BODY"

Затем попросите заведение оформить тестовый заказ с доставкой и оплатить его. Вы получите delivery.create и сможете пройти все этапы. Отмена заказа в Shuqr пришлёт delivery.cancel.

Вопросы#

Если что-то непонятно или не работает, напишите нам или на support@shuqr.ru. Укажите адрес сервера и время запроса – так мы быстрее найдём его в журнале.