Skip to main content
Documentation

Integration recipes

Five tasks people most often solve through the External API: catalog syncing, taking orders and leads from a website, exporting sales and online booking. Every recipe is a call order, a ready curl and the event worth subscribing to instead of polling.

The common rules (authentication, formats, pagination, error codes) are described in External API, and the full list of methods is in the API reference. In the examples the token lives in the MBS_TOKEN variable.

Syncing the catalog with a marketplace

The marketplace storefront shows the same items and prices as the company catalog.

  1. Create a token with the catalog:write scope — it includes reading.
  2. Pull the catalog in pages of 50 items until you exhaust total.
  3. Match items by barcode or SKU and store the "our identifier — marketplace identifier" pair on your side.
  4. Push changes back with targeted PATCH calls by product identifier.
curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/catalog/products?page=1&pageSize=50"

Prices arrive in minor units: 120000 means 1,200 ₽. A coffee shop catalog of 30 items, for instance, fits into a single page, so a full pass costs one request.

Stock lives separately from the product card: read it through warehouse/stocks and change it only through warehouse/stocks/adjust. Subscribe to product.created, product.updated and product.bulk_repriced — then a full pass once a day is enough.

Taking orders from a website

The website places an order, and the system carries it further through statuses.

  1. A token with the orders:write and clients:write scopes.
  2. Find the customer by phone through clients with the search parameter, or create a new one.
  3. Create the order and pass X-Idempotency-Key: a dropped connection after sending will not create a second order.
  4. Manage states through the status change rather than by re-creating the order.
curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
      "customerId": "123e4567-e89b-12d3-a456-426614174000",
      "items": [
        { "kind": "product", "refId": "…", "qty": 2, "unitPrice": 125000 }
      ]
    }' \
https://app.easymb.ru/api/external/v1/orders

Two packs at 1,250 ₽ each, for instance, make an order of 2,500 ₽: unitPrice is set in minor units per unit, and the total is calculated by the system.

The idempotency key is a UUID unique per attempt. While the first attempt is still running, a repeat with the same key gets a 409 with the IDEMPOTENCY_IN_FLIGHT code: wait a second and repeat to collect the response of the first one.

Listen to order.created and order.status_changed — in both data carries the whole order, and the status change adds previousStatus; catch the fact of shipping via order.shipped, raised by a posted shipment note.

Exporting sales to accounting

The reliable setup is a fast trigger plus a nightly reconciliation.

  1. Subscribe to the sale.completed event and store receipts on your side right after they are closed.
  2. Once a day re-read the sales of the past day and reconcile them with what arrived.
  3. A mismatch means a missed delivery: look it up in the subscription delivery history.
curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/sales?dateFrom=2026-08-04T00:00:00.000Z&dateTo=2026-08-04T23:59:59.999Z&pageSize=100"

Dates are passed in UTC, so a shift from 9:00 to 21:00 Moscow time is pulled with an interval from 06:00 to 18:00 UTC. Refunds arrive as a separate sale.refunded event and go into accounting with the same posting, only with a minus sign.

Taking leads from a website form

A request from a landing page lands in the Leads section and turns into a customer or a deal.

  1. A token with the leads:write scope; the company must have the Marketing component enabled (and Deals as well for a conversion into a deal).
  2. Send the request passing externalId — the record number in your form.
  3. After that change the status, assign an owner or convert the lead.
curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
      "name": "John Peterson",
      "phone": "+79991234567",
      "message": "I would like to book a diagnostic",
      "source": "landing",
      "externalId": "form-8123",
      "utm": { "source": "yandex", "medium": "cpc", "campaign": "spring" }
    }' \
https://app.easymb.ru/api/external/v1/leads

Creation is idempotent by the "source plus externalId" pair: sending the same request again returns the lead already created and does not raise a second lead.created event. For example, a landing form that fires twice on a double click still produces a single lead.

Conversion is two different calls: leads/{id}/convert creates a customer and returns clientId, while leads/{id}/convert-deal creates a customer and a deal and returns dealId. The lead statuses are new, in_progress, converted and spam.

Online booking for a customer

A booking form on the website shows the free time and creates a booking.

  1. A token with the scheduling:write scope; the Scheduling component is enabled.
  2. Show the free intervals of the resource for the chosen day.
  3. Create a booking on the chosen interval.
  4. Wait for the confirmation by the administrator or the customer.
curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://app.easymb.ru/api/external/v1/scheduling/bookings/slots?resourceId=…&date=2026-08-05&serviceId=…"

The response is an array of intervals with a free field. When serviceId is passed, the grid step comes from the service duration: a 60-minute haircut gives the slots 10:00–11:00, 11:00–12:00 and so on.

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: $(uuidgen)" \
-d '{
      "resourceId": "…",
      "serviceId": "…",
      "startAt": "2026-08-05T07:00:00.000Z",
      "customerName": "John Peterson",
      "customerPhone": "+79991234567"
    }' \
https://app.easymb.ru/api/external/v1/scheduling/bookings

A booking is created in the pending status. The confirmation arrives as booking.confirmed, a no-show as booking.no_show, a completion as booking.completed; each of them comes together with booking.status_changed. You can set a status yourself through the booking status change.

Pre-production checklist

  • A separate token per integration, with the minimal set of scopes.
  • The secret in secure storage, not in the repository and not in a frontend build variable.
  • 429, IDEMPOTENCY_IN_FLIGHT and network errors handled: a retry with a growing pause.
  • Every mutation sent with the X-Idempotency-Key header.
  • The client does not fail on unknown fields in responses.
  • Monitoring in place: 401 and 403 raise an alarm.
  • Webhook signatures are verified, and the delivery history is reviewed at least once a week.

In short

  • The catalog and sales are exported page by page, and changes are caught with events.
  • Orders and bookings are created with an idempotency key: a repeat produces no duplicate.
  • Leads are deduplicated by your externalId within the source.
  • The free time for online booking comes from the resource slots request for a day.

See also: External API, Webhooks, API reference.