Partner API guide

1. Quick start

1. Open the bot's mini app → Profile → API and create a token: name, expiry, access ("catalog only" or "catalog and orders"), and a channel when offered (warehouse + currency, same as bot directions). The section is visible only if a manager has enabled API access for you.
2. A general token covers every channel the manager allowed. A narrow token is limited to one channel: catalog and orders use only that warehouse and currency.
3. The token is shown once. Keep it in a secrets store; never put it in a repository or client-side code. If it leaks, revoke it there and issue a new one.
4. Send the token with every request: Authorization: Bearer fcp_….

export FC_API="https://api.unimtrn.com/api/partner"
curl -H "Authorization: Bearer $FC_TOKEN" "$FC_API/schedule"

API base URL: https://api.unimtrn.com/api/partner. The API is server-to-server: browser requests (CORS) are not supported, call it from your backend.

2. General rules

• Price is what you see in the bot (price type, markup, currency from your client card). You never send a price: the server sets it, including quantity tiers.
• Warehouses and currency come from the token's channels (client card ∩ manager policy ∩ issue choice). With a single warehouse you may omit warehouse. A narrow single-currency token returns prices only in that currency.
• Working hours. The bot has a schedule: it accepts orders only during working hours. You can get today's hours with GET /schedule (it always answers, including when the bot is closed); your manager will also tell you the hours.
  • Order changes (add an item, change quantity, remove a line, cancel the order) are not accepted outside working hours: the response is 423 bot_closed. This always applies.
  • The catalog (/catalog, /brands, /categories) is closed outside working hours only if your manager has enabled schedule compliance for you; then it also returns 423 bot_closed. If it is not enabled, the catalog is available around the clock.
  • 423 bot_closed is not a request error. Retry it during working hours; use the same Idempotency-Key on the retry: a schedule rejection is not stored, and the action will be executed afresh.
  • When today's working time is known, it comes right in the response, in error.details: the opening and closing times and the time zone they are given in. If it is only known that the bot is not accepting requests right now, the response has no details field. Example:

    HTTP 423
    {
      "error": {
        "code": "bot_closed",
        "message": "Бот закрыт. Сегодня работает с 10:00 до 18:00 (Asia/Dubai)",
        "details": { "opensAt": "10:00", "closesAt": "18:00", "timezone": "Asia/Dubai" }
      }
    }

• Rate limits are set by your manager. Exceeding them returns 429 rate_limited: wait and retry. Many invalid tokens in a row from one IP also lead to 429.
• There is no version in the path. Incompatible changes are shipped as new fields and endpoints: ignore unknown response fields.

3. Error format

HTTP 403
{ "error": { "code": "scope_missing", "message": "…" } }

Rely on code, not the message text. Main groups:

Order error examples

Stale lineId:

HTTP 409
{
  "error": { "code": "line_changed", "message": "Строка заказа изменилась, перечитайте заказ" },
  "order": { "id": "6ae9aefdd12dd7057d4bf68e", "lines": [ "…" ] }
}

No stock:

HTTP 422
{ "error": { "code": "order_rejected", "message": "Товар недоступен в нужном количестве" } }

Action disabled by manager:

HTTP 403
{ "error": { "code": "forbidden", "message": "Удаление строк заказа через API отключено для этого клиента" } }

Numbers, item codes, prices and ids in examples are illustrative.

8. Idempotency-Key

Why. If the response is lost, a blind retry is unsafe. The key guarantees a retry with the same key returns the first response instead of running the action twice.

Where. All mutating order requests: POST /orders/lines, PATCH, DELETE, POST …/cancel. Without it — 400 idempotency_key_required. Not needed for GET.

Who creates it. Your system, before the request (e.g. UUID v4). New action — new key. Keep the key until you get a response.

KEY=$(uuidgen)
curl -sS -X PATCH "https://api.unimtrn.com/api/partner/orders/$ORDER/lines/$LINE" \
  -H "Authorization: Bearer $FC_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"qty": 5}'
# no response — retry with the same $KEY
# → 200 and Idempotent-Replay: true

• One key — one action. 8–128 chars: A-Za-z0-9_.:-.
• Same key with a different request — 422 idempotency_key_reused.
• While the first request is still running — 409 request_in_progress; wait and retry.
• Business failures (409, 422) are stored. Temporary ones (423, 429, 503) are not.

9. FAQ

• 403 api_disabled / orders_disabled. API or orders are not enabled for you by the manager.
• 422 order_rejected. No stock, quota exhausted, or item unavailable — reason in message.
• 422 onec_error. The accounting system rejected the change. Contact your manager if it repeats.
• Token stopped working. Check expiry and revocation in Profile → API; the 401 code says what happened.