Delivery services: integration API

What it is#

Shuqr is a system for cafes and restaurants: point of sale, kitchen, online orders. A venue can connect your service in its settings. Shuqr then sends you paid orders for delivery, and you send back the stages: courier assigned, order picked up, delivered.

You don't need a contract with Shuqr. You agree on terms, prices and payments directly with the venue.

How it works#

1. The venue connects your service in its settings and clicks "Check connection" – Shuqr sends ping.
2. When it is time to deliver an order, Shuqr sends delivery.create. Within 10 seconds you reply with your job ID in id.
3. As the courier moves on, you send stages to the order's callbackUrl: assigned, on the way to the venue, picked up.
4. The delivered stage closes the order for the venue: it becomes “Completed”. Along the way the cashier and the guest see the courier and the current stage.
5. Until the courier picks up the order, the venue may cancel it. Then you get delivery.cancel.

How connecting works#

1. You give the venue your server address (https:// only) and a signing key – a long random string you make up yourself. Each venue gets its own key.
2. The venue opens “Settings → Delivery” in Shuqr and, in the “Who delivers” block, adds “Other service via API” and enters your address, the key and the delivery price the guest pays. Delivery time for the guest is optional.
3. When an order is paid and ready to go, Shuqr sends you a delivery.create request. From then on you report the delivery stages.

A venue can connect several services and pick the main one. If you refuse an order or don't answer, the order goes to the next service or to the venue's cashier.

Several restaurants

Each venue has its own signing key. The easiest way is to give each venue its own address, for example https://your-service.example.com/shuqr/cafe-pelmen, where cafe-pelmen is a venue code you make up yourself. When a request comes in, find that venue's key by the code in the address and check the signature with it.

delivery.create also has a restaurantId field – the venue ID in Shuqr. It also tells you whose order it is. But trust it only after the signature check.

ping has no restaurantId. One more reason to give each venue its own address.

What you need to build#

• An HTTPS address that accepts POST with JSON and understands three events: ping, delivery.create, delivery.cancel.
• A separate address and key for each venue (see “Several restaurants”).
• A check of the X-Shuqr-Signature header on every request.
• Protection from repeats: a second delivery.create with the same deliveryId must not create a second job.
• Your job ID in id in the reply to delivery.create.
• Sending stages to the order's callbackUrl every time something changes.

Requests from Shuqr#

Shuqr sends a POST request to the address the venue entered in its settings. The body is UTF-8 JSON.

ping – connection check

When the venue clicks "Check connection" in its settings, Shuqr sends a signed ping. Reply with any 2xx code and the venue sees "The connection works". If the signature is wrong, reply 401 and the venue sees that the key needs checking.

{ "event": "ping" }

delivery.create – new order

Sent when it is time to deliver a paid order. The venue chooses the moment: right after the order is accepted, when the kitchen starts cooking, when the order is ready, or manually – the cashier presses a button. So the courier may have to wait at the venue. orderNumber helps to pick up the right order.

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}

Guest address in parts

When the address was picked from suggestions, dropoff.details carries its parts – handy for finding the building in your own database and showing the courier the apartment and entrance separately. All fields are optional: an order with a typed-in address may have none.

Amounts are in currency units (from currency), not in cents or kopecks. They can be fractional, for example 249.5.

A 2xx code and JSON with your job ID in id. You can pass the stage in status right away – usually searching. Without status, Shuqr assumes you are looking for a courier.

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

If the same order is handed over again (for example, after a refusal), it comes with a new deliveryId – that is a new job. A repeat with the same deliveryId is the same order: return the job you already created.

delivery.cancel – cancellation

Sent when the venue cancels the order or refunds the guest, and also when you take too long to find a courier (the venue sets the time limit). The id field holds your job ID from the delivery.create reply.

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

Cancelled – reply 2xx. No such job – 404, this also counts as cancelled. The courier already has the order and you can't cancel – 409.

If you replied 409, the venue sees that cancelling failed. Contact the venue to agree what to do with the order.

How Shuqr reads your reply

On any error for delivery.create the order goes to the venue's backup service or to the cashier. Shuqr does not retry this request by itself.

In an error reply you can pass an error field with a clear message. Shuqr saves it in the delivery history, which helps to sort out the problem.

Checking the signature#

The signature proves that the request came from Shuqr and nobody changed it. Shuqr takes the request body as is and computes HMAC-SHA256 of it with the key the venue entered in its settings. The hex result with the sha256= prefix goes into the X-Shuqr-Signature header. You do the same on your side and compare the strings.

• Compute the signature over the raw body – exactly the bytes you received. If you parse the JSON and encode it again, the signature won't match.
• Compare with a constant-time function: hash_equals in PHP, crypto.timingSafeEqual in Node.js.
• Signature doesn't match – reply 401 and don't touch the order.

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);

Both examples were tested against real Shuqr requests. saveOrder and cancelOrder are your code: save the job and cancel it.

Reporting delivery stages#

When something changes with a job, send a POST with JSON to the order's callbackUrl. Use the address exactly as you received it, don't change anything in it.

Fields

Send only what changed: a field missing from the request stays as it was. Only status is always needed.

{
  "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
}

Stages

The usual path: searching → assigned → to_pickup → picked_up → delivered.

• Stages only move forward. If you send an earlier stage, Shuqr skips it. One exception – the courier dropped out before picking up the order: you can go back to searching and look for another one.
• delivered, cancelled and failed are final. After them Shuqr changes nothing, so send the final price no later than the final stage.
• failed or cancelled before the courier picked up the order – Shuqr immediately hands the order to the venue's backup service or to the cashier.
• The courier picked up the order but couldn't hand it over: send returning with a reason, for example guestRefused. When the courier brings the order back to the venue, send cancelled with reason returned. The cashier decides what happens next.

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

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

Reasons

The first four reasons are for refusing before the courier picked up the order. The rest are for when the courier already has the order but couldn't hand it over.

Shuqr doesn't store other reason values, but still accepts the stage.

What Shuqr replies

No reply or a 5xx code – retry a bit later.

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"}'

How to test#

• Shuqr has no separate test environment yet. You test the connection together with a venue that wants to work with you.
• Your address must be reachable from the internet over HTTPS. To test a server on your own computer, use a tunnel such as ngrok or Cloudflare Tunnel.
• Log every incoming request in full: headers and raw body. That makes it easier to find out why a signature doesn't match.
• You can check the signature without Shuqr: sign a test body yourself and send a request to yourself, as in the example below.

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"

Then ask the venue to place a test delivery order and pay for it. You will get delivery.create and can go through all stages. Cancelling the order in Shuqr sends delivery.cancel.

Questions#

If something is unclear or doesn't work, contact us or write to support@shuqr.ru. Include your server address and the request time – that helps us find it in the logs faster.