Започнете оттук — първата заявка за 5 минути

Три стъпки, без четене: ключ → една заявка → един webhook. Всичко по-долу е изпълнено срещу продукционната среда; отговорите са реални (id-та, имейли и телефони са маскирани).

Стъпка 1 — ключ от мърчанта

Мърчантът отваря админа на velik.ai → Настройки → 🔌 Интеграции → API ключове → Нов ключ, избира пресет (📦 Фулфилмънт за склад/WMS, 👁 Само четене за отчети, ⚙️ Персонализиран за всичко друго) и ви дава ключа vk_… веднъж. Ключът е акаунтът на мърчанта: един ключ = един акаунт, план Pro и нагоре.

Пазете го като парола. Никога в браузър или мобилно приложение — /api/v1 нарочно няма CORS.

Стъпка 2 — първата заявка

curl -sS "https://velik.ai/api/v1/orders?status=new&limit=5" \
  -H "Authorization: Bearer $VELIK_API_KEY"

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "number": 16,
      "order_number": 1546,
      "status": "new",
      "payment_status": "pending",
      "payment_method": "cod",
      "funnel_step": "original",
      "parent_order_id": null,
      "total": 29,
      "delivery_price": null,
      "discount_amount": null,
      "coupon_code": null,
      "refund_amount_cents": null,
      "refunded_at": null,
      "customer": {
        "name": "Тест V. C. V.",
        "email": "bo…@convertbuilder.com",
        "phone": "+359 8•• ••• •12",
        "vat": null
      },
      "shipping": {
        "address": "ул. Те ••• (masked)",
        "city": "София",
        "zip": "1000",
        "method": null,
        "courier_slug": "econt",
        "courier_delivery_mode": "home",
        "courier_office_id": null
      },
      "courier": null,
      "tracking_number": null,
      "tracking_url": null,
      "line_items": [
        {
          "qty": 1,
          "sku": null,
          "kind": "main",
          "name": "Хранителна добавка за сън",
          "product_id": "00000000-0000-4000-8000-000000000002",
          "variant_id": null,
          "total_cents": 2900,
          "delivery_type": "physical",
          "unit_price_cents": 2900
        }
      ],
      "product_name": "Хранителна добавка за сън",
      "product_sku": null,
      "quantity": 1,
      "unit_price": 29,
      "notes": null,
      "admin_notes": null,
      "return_note": null,
      "page_id": "00000000-0000-4000-8000-000000000003",
      "invoice_number": null,
      "shipment": null,
      "created_at": "2026-09-04T14:10:54.525378+00:00",
      "updated_at": "2026-09-05T14:34:46.691317+00:00"
    },
    {
      "id": "00000000-0000-4000-8000-000000000004",
      "number": 15,
      "order_number": 1544,
      "status": "new",
      "payment_status": "pending",
      "payment_method": "cod",
      "funnel_step": "original",
      "parent_order_id": null,
      "total": 41,
      "delivery_price": null,
      "discount_amount": null,
      "coupon_code": null,
      "refund_amount_cents": null,
      "refunded_at": null,
      "customer": {
        "name": "Тест V. C.",
        "email": "bo…@convertbuilder.com",
        "phone": "+359 8•• ••• •12",
        "vat": null
      },
      "shipping": {
        "address": "ул. Те ••• (masked)",
        "city": "София",
        "zip": "1000",
        "method": null,
        "courier_slug": "econt",
        "courier_delivery_mode": "home",
        "courier_office_id": null
      },
      "courier": null,
      "tracking_number": null,
      "tracking_url": null,
      "line_items": [
        {
          "qty": 1,
          "sku": null,
          "kind": "main",
          "name": "Хранителна добавка за сън",
          "product_id": "00000000-0000-4000-8000-000000000002",
          "variant_id": null,
          "total_cents": 2900,
          "delivery_type": "physical",
          "unit_price_cents": 2900
        }
      ],
      "product_name": "Хранителна добавка за сън",
      "product_sku": null,
      "quantity": 1,
      "unit_price": 29,
      "notes": "+ Downsell: Serenity Balance Woman — €12 вместо €39 — €12.00",
      "admin_notes": null,
      "return_note": null,
      "page_id": "00000000-0000-4000-8000-000000000003",
      "invoice_number": null,
      "shipment": {
        "id": "00000000-0000-4000-8000-000000000005",
        "courier_slug": "econt",
        "tracking_number": "1051•••91",
        "status": "cancelled",
        "last_status_label": "Анулирана",
        "last_status_at": "2026-09-05T15:12:02.308+00:00"
      },
      "created_at": "2026-09-04T12:22:17.798464+00:00",
      "updated_at": "2026-09-05T15:12:03.084937+00:00"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOS0wNFQxMjoyMjoxNy43OTg0NjQrMDA6MDAiLCJpIjoiMjFlOTI4OTItMGQ0NC00OTE4LWJiNzktMDQ0ZDAxZGYwYzE3In0"
}

Всеки списък се странира еднакво (limit ≤ 200, непрозрачен cursor, has_more), всяко писане приема X-Velik-Dry-Run: 1 за проверка без запис, всяка грешка е { "error": { "code", "message" } } — вижте Грешки и лимити.

Стъпка 3 — velik.ai да вика вас

Абонирайте се за нужните събития (секретът се връща веднъж — с него се подписва всяка доставка):

curl -sS -X POST "https://velik.ai/api/v1/webhooks" \
  -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/velik-webhook", "events": ["order.created", "order.status_changed", "shipment.status_changed"] }'

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000035",
    "url": "https://velik.ai/api/webhooks/sink",
    "description": "Fulfilment WMS (probe)",
    "events": [
      "order.created",
      "order.updated",
      "order.status_changed",
      "shipment.created",
      "shipment.status_changed"
    ],
    "active": true,
    "secret_prefix": "whsec_efcd8722…",
    "last_triggered_at": null,
    "last_status_code": null,
    "dead_notified_at": null,
    "created_at": "2026-09-05T16:06:29.476938+00:00",
    "updated_at": "2026-09-05T16:06:29.476938+00:00"
  },
  "secret": "<64 hex characters — shown once, store it>"
}

После POST /api/v1/webhooks/{id}/test праща test плик и връща първия опит с HTTP кода, с който е отговорил вашият адрес. Проверете X-Velik-Signature с референтния код на Node, Python или PHP; пълният договор е в Webhooks (EN).

Накъде нататък

Искам да…	четете
свържа фулфилмънт център / WMS от край до край (поръчки → приемане → изпращане → склад)	Бърз старт: фулфилмънт
знам всеки endpoint, поле и статус	API справочник · `openapi.v1.yaml`
пробвам в Postman / Insomnia / Bruno	Postman колекция (генерирана от спецификацията); Insomnia и Bruno импортират `openapi.v1.yaml` директно
дам същия достъп на AI агент (Claude Desktop, Claude Code)	MCP сървър (EN)
разбера грешките, лимитите, странирането, пробния режим	Общ преглед §5–§8
обясня това на собственика на бизнеса (без код)	За собственика на бизнеса

Примери за копиране: curl.sh · node.mjs · python.py. Въпроси: support@velik.ai — вижте Поддръжка.

velik.ai Platform API (български)

Базов адрес: https://velik.ai · REST: /api/v1/… · MCP: POST /api/mcp · Спецификация: openapi.v1.yaml (визуализирана) · English (пълният договор): README.md

Това е преводът на основния документ. Договорът — имената на полетата, кодовете за грешка, OpenAPI спецификацията — е на английски и английският текст е меродавен при разминаване. Стъпка по стъпка за фулфилмънт център: quickstart-fulfilment.bg.md.

Платформеното API дава на интегратори — фулфилмънт центрове, складови системи, ERP/BI инструменти и AI агенти — програмен достъп до поръчките, пратките, склада, продуктите, клиентите и webhooks на един мърчант. Същите данни и същите операции като в админа на velik.ai, през два транспорта с един договор:

транспорт	за кого	автентикация
REST `https://velik.ai/api/v1/…`	вашият бекенд, WMS, ERP	`Authorization: Bearer vk_…`
MCP `POST https://velik.ai/api/mcp` (JSON-RPC 2.0, Streamable HTTP, без сесии)	AI агенти (Claude Desktop, Claude Code, всеки MCP клиент)	същият ключ
Webhooks (ние изпращаме към вас)	известяване вместо периодично питане	подпис с таен ключ на абонамента

Всеки пример в документите е пуснат срещу продукционната система; показаните отговори са реалните, с маскирани id-та, имейли и телефони.

1. Как се получава ключ

Ключа издава мърчантът (интеграторът не може да създава ключове за чужд акаунт):

Админ на velik.ai → Настройки → 🔌 Интеграции → API ключове → Нов ключ.
Избира пресет (§2) или обхватите поотделно и дава име (напр. „Acme Фулфилмънт").
Пълният ключ vk_… се показва веднъж. Мърчантът ви го предава по сигурен канал. В списъка после се вижда само префиксът (vk_ab12cd34), обхватите и „последно ползван".

Правила:

Един ключ = един акаунт. Ключът действа като собственика на акаунта за ресурсите в обхвата си. Екипните права не важат за ключове. Нищо, което ключ може да направи, не излиза извън акаунта.
До 10 активни ключа на акаунт. Оттеглянето е незабавно (401 unauthorized оттам нататък).
Обхватът е фиксиран при издаване. За промяна мърчантът издава нов ключ и оттегля стария.
Ключовете са за сървър-към-сървър. /api/v1 няма CORS — никога не слагайте ключ в браузър или мобилно приложение.

2. Обхвати и пресети

Обхватите са изрични, ресурс:действие. :write НЕ включва :read — ключ само с orders:write може да обнови поръчка, чието id вече знае, но не може да листва поръчки. Поискайте и двете, когато ви трябват и двете.

обхват	дава	REST	MCP
`orders:read`	списък/четене на поръчки (с резюме на пратката)	`GET /api/v1/orders`, `GET /api/v1/orders/{id}`	`list_orders`, `get_order`
`orders:write`	статус, тракинг номер/линк, куриер, вътрешни бележки	`PATCH /api/v1/orders/{id}`	`update_order`
`shipments:read`	пратки (товарителници), куриерски събития, етикет PDF	`GET /api/v1/orders/{id}/shipment`, `GET /api/v1/shipments/{id}`, `GET /api/v1/shipments/{id}/label`	`get_shipment`
`shipments:write`	издаване/анулиране на товарителници през куриерите на мърчанта	`POST /api/v1/shipments`, `POST /api/v1/shipments/{id}/cancel`	`create_shipment`, `cancel_shipment`
`inventory:read`	наличности, прагове, складов журнал	`GET /api/v1/inventory/stock`, `GET /api/v1/inventory/movements`	`get_inventory_stock`, `list_stock_movements`
`inventory:write`	доставки и корекции	`POST /api/v1/inventory/movements`	`record_stock_movement`
`products:read`	каталог с варианти, цени, SKU, размери	`GET /api/v1/products`, `GET /api/v1/products/{id}`	`list_products`, `get_product`
`products:write`	създаване на продукти; промяна на цена, SKU, име, описание, тегло/размери, активен, прагове — никога наличност, себестойност, снимки или файлове	`POST /api/v1/products`, `PATCH /api/v1/products/{id}`	`create_product`, `update_product`
`customers:read`	клиенти (агрегат от поръчките), записани сегменти	`GET /api/v1/customers`, `GET /api/v1/segments`	`list_customers`, `list_segments`
`customers:write`	сегменти (създаване / преименуване / филтри / изтриване), членове по имейл или телефон, бележки към клиент — никога имейли, телефони, съгласия или изтриване	`POST /api/v1/segments`, `PATCH`/`DELETE /api/v1/segments/{id}`, `POST`/`DELETE /api/v1/segments/{id}/members`, `POST /api/v1/customers/{key}/notes`	`create_segment`, `update_segment`, `delete_segment`, `add_segment_members`, `remove_segment_members`, `add_customer_note`
`webhooks:read`	абонаменти и доставки	`GET /api/v1/webhooks`, `GET /api/v1/webhooks/{id}/deliveries`	`list_webhooks`, `list_webhook_deliveries`
`webhooks:write`	създаване/промяна/изтриване/тест на абонаменти, повторни доставки	`POST /api/v1/webhooks`, `PATCH`/`DELETE /api/v1/webhooks/{id}`, `POST /api/v1/webhooks/{id}/test`, `POST /api/v1/webhook-deliveries/{id}/retry`	`create_webhook`, `update_webhook`, `delete_webhook`, `test_webhook`
`submit_brief`, `get_status`, `get_facts`	мостът към МАШИНАТА (само MCP, отделен договор — mcp.md §5)	—	`submit_brief`, `get_status`, `get_facts`

Пресети при издаване:

пресет	обхвати	за кого
📦 Фулфилмънт	`orders:read`, `orders:write`, `shipments:read`, `shipments:write`, `inventory:read`, `inventory:write`, `products:read`, `webhooks:read`, `webhooks:write`	фулфилмънт център / WMS
👁 Само четене	`orders:read`, `shipments:read`, `inventory:read`, `products:read`, `customers:read`, `webhooks:read`	BI, счетоводство, CRM синхронизация
🔗 МАШИНАТА	`submit_brief`, `get_status`, `get_facts`	мостът към МАШИНАТА
⚙️ Персонализиран	произволна комбинация	всички останали

Няма пресет по подразбиране — мърчантът избира изрично. Ключовете „Фулфилмънт" и „Само четене" не съдържат обхватите на моста и не виждат неговите инструменти. products:write и customers:write не са в никой пресет — дават се поотделно в „Персонализиран" (синхронизация с ERP/CRM е изричен избор).

3. Планове

Платформеното API е от план Pro нагоре. Ключ на Free акаунт се автентикира, но всяко повикване връща 403 plan_required. Ако планът не може да се провери, API-то отказва (fail-closed) с 403 plan_lookup_failed — опитайте по-късно. Служебните акаунти на velik.ai (роля superadmin) прескачат само проверката на плана, никога tenancy — техните ключове виждат само собствения си акаунт.

4. Автентикация

GET /api/v1/orders?status=new HTTP/1.1
Host: velik.ai
Authorization: Bearer vk_…

резултат	статус	`error.code`
липсващ / невалиден / оттеглен ключ, деактивиран акаунт	401	`unauthorized` (+ `WWW-Authenticate: Bearer realm="velik.ai API"`)
ключът няма обхвата на маршрута	403	`scope_missing` (+ `error.scope`)
Free план	403	`plan_required`
планът не може да се провери	403	`plan_lookup_failed`
над лимита на заявките	429	`rate_limited` (+ `Retry-After`)

5. Грешки

Всяка грешка е JSON със стабилен snake_case код. Обработвайте по error.code; error.message е английски текст и може да се промени.

{ "error": { "code": "validation_failed", "message": "id must be a UUID.", "details": { … } } }

`code`	статус	кога
`unauthorized`	401	§4
`scope_missing` · `plan_required` · `plan_lookup_failed`	403	§4
`method_not_allowed`	405	грешен HTTP метод (`Allow` изброява верните; `OPTIONS` → 204)
`validation_failed`	400	лош вход: непознато поле, грешен тип/стойност, id, което не е UUID, лош курсор; `details.allowed` изброява позволените полета; не-UUID id и във филтрите `page_id` / `product_id` / `order_id`; дата извън строг ISO 8601 (`from`, `to`, `since`)
`not_found`	404	няма такъв ред в този акаунт — включително редове на друг акаунт (никога 403)
`conflict`	409	конфликт на състояние: вече има жива пратка, пратката е анулирана/приключена, лимит 20 абонамента, доставката вече е доставена, абонаментът е неактивен
`courier_error`	502	куриерът отказа или не отговори (`details.reason`, `details.detail`)
`migration_pending`	503	функцията още не е включена на тази инсталация
`rate_limited`	429	над 300 заявки/мин за ключа
`internal_error`	500	наш бъг — опитайте пак и ни кажете `X-Deploy-SHA`

Две правила, които си струва да се повторят:

Id-тата са UUID. Всичко друго се отхвърля преди базата: GET /api/v1/orders/1546 → 400 validation_failed „id must be a UUID.". Номерата на поръчките (number, order_number) не са id-та.
Редовете на чужд акаунт са 404, никога 403. API-то не издава дали id съществува другаде.

6. Лимити на заявките

транспорт	лимит	кофа	заглавия
REST `/api/v1`	300 заявки / минута	на ключ	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` (при 429)
MCP `/api/mcp`	120 съобщения / минута (JSON-RPC batch от N се брои като N; най-много 20 в един POST)	на ключ	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` (при 429)
Webhook тест и повтори (`POST /api/v1/webhooks/{id}/test`, `POST /api/v1/webhook-deliveries/{id}/retry`, бутоните в админа, MCP инструментите)	30 / минута всяко	на акаунт	`Retry-After` (при 429)

При 429 изчакайте Retry-After секунди. Предпочитайте webhooks (§9) пред често питане.

7. Страниране и polling

Списъците връщат страница и непрозрачен курсор:

{ "data": [ … ], "has_more": true, "next_cursor": "eyJjIjoi…" }

limit — по подразбиране 50, максимум 200.
cursor — подайте next_cursor за следващата страница. Курсорите са keyset (created_at, id) — нови редове, вмъкнати междувременно, не разместват страниците. Повреден курсор → 400 validation_failed.
Поръчките поддържат since=<ISO 8601> (updated_at ≥) — най-евтиният начин да питате за промени без webhooks: запомнете updated_at на най-новия обработен ред и поискайте всичко след него. Времената са UTC, ISO 8601.
GET /api/v1/customers е агрегат и ползва limit / offset / total.
GET /api/v1/segments и GET /api/v1/webhooks връщат всичко (малки списъци).

8. Пробен режим (dry run)

Няма отделна тестова среда. Вместо това всяка записваща операция приема

X-Velik-Dry-Run: 1

и тогава валидира всичко — собственост, полета, състояние, куриер, склад — но не записва нищо и не вика куриер. Отговорът носи dry_run: true и описва какво би станало. Използвайте го, за да тествате интеграцията върху реалните данни на мърчанта и да преглеждате преди да запишете.

Всеки отговор, успешен или грешка, носи X-Deploy-SHA — ревизията на velik.ai, която го е обслужила. Цитирайте я при проблем.

9. Ресурси

метод и път	обхват	връща
`GET /api/v1/orders`	`orders:read`	страница `Order` — филтри `status`, `payment`, `from`, `to`, `since`, `page_id`, `product_id`, `courier` (`none` = още без тракинг номер), `shipment_status`, `q`
`GET /api/v1/orders/{id}`	`orders:read`	`Order`
`PATCH /api/v1/orders/{id}`	`orders:write`	`status`, `tracking_number`, `tracking_url`, `courier`, `admin_notes`, `notify_customer` → `Order` + `status_changed`, `email_sent`
`GET /api/v1/orders/{id}/shipment`	`shipments:read`	последната `Shipment` на поръчката или `null`
`POST /api/v1/shipments`	`shipments:write`	товарителница през куриера на мърчанта → `Shipment`
`GET /api/v1/shipments/{id}`	`shipments:read`	`Shipment` със `status_events`
`GET /api/v1/shipments/{id}/label`	`shipments:read`	етикетът като `application/pdf`
`POST /api/v1/shipments/{id}/cancel`	`shipments:write`	анулиране при куриера
`GET /api/v1/inventory/stock`	`inventory:read`	наличност по активен физически продукт (+ варианти, прагове)
`GET /api/v1/inventory/movements`	`inventory:read`	складовият журнал (`sale`, `release`, `return`, `delivery`, `correction`)
`POST /api/v1/inventory/movements`	`inventory:write`	записва `delivery` или `correction`
`GET /api/v1/products` · `GET /api/v1/products/{id}`	`products:read`	каталог с варианти; `?status=all` включва деактивираните
`POST /api/v1/products` · `PATCH /api/v1/products/{id}`	`products:write`	създаване / промяна на каталожни полета (цена, SKU, име, размери, активен…) — не наличност, себестойност или медия
`GET /api/v1/customers`	`customers:read`	клиенти, агрегирани от поръчките
`GET /api/v1/segments`	`customers:read`	записаните сегменти
`POST /api/v1/segments` · `PATCH`/`DELETE /api/v1/segments/{id}`	`customers:write`	изчисляеми (филтри) или членски сегменти
`POST`/`DELETE /api/v1/segments/{id}/members`	`customers:write`	добавяне / махане на клиенти (имейл или телефон) в членски сегмент
`POST /api/v1/customers/{key}/notes`	`customers:write`	вътрешна бележка към клиент
`GET /api/v1/webhooks` · `POST /api/v1/webhooks`	`webhooks:read` / `webhooks:write`	абонаменти (секретът се връща веднъж при създаване)
`PATCH /api/v1/webhooks/{id}` · `DELETE /api/v1/webhooks/{id}`	`webhooks:write`	промяна / изтриване
`GET /api/v1/webhooks/{id}/deliveries` · `POST /api/v1/webhooks/{id}/test`	`webhooks:read` / `webhooks:write`	доставки / тестово събитие
`POST /api/v1/webhook-deliveries/{id}/retry`	`webhooks:write`	повторен опит сега

Пълните параметри, тела и схеми: openapi.v1.yaml / velik.ai/developers/api.

Моделът на данните накратко

Order (поръчка) — id (UUID), number (номерът, който мърчантът вижда), status ∈ new · confirmed · processing · shipped · delivered · cancelled · returned · refunded · archived, payment_status, payment_method (cod, bank, card, free…), суми като числа във валутата на страницата (total, delivery_price, discount_amount), customer { name, email, phone, vat }, shipping { address, city, zip, method, courier_slug, courier_delivery_mode, courier_office_id }, courier / tracking_number / tracking_url, line_items[] (замразената сметка, суми в стотинки/центове: kind, product_id, variant_id, name, sku, qty, unit_price_cents, total_cents), shipment (резюме на последната товарителница или null), admin_notes, page_id, дати. Стари поръчки имат line_items: null и единствения продукт в product_name / quantity / unit_price. Атрибуция, IP адреси, идентификатори на платежни доставчици и себестойност никога не се показват.
Shipment (пратка) — товарителница, издадена през velik.ai: courier_slug (econt / speedy / boxnow), tracking_number, нормализиран status ∈ pending · picked_up · in_transit · delivered · cancelled · refused · returned, status_events[] ({ at, code, label } — суровите куриерски събития), delivery_mode (office / home), office_id, cod_amount, shipping_cost, тегло/размери, sender_origin, shipment_terms.
Product (продукт) — name, sku, price, active, delivery_type (physical / digital / free), images[], stock_quantity (null = без следене), low_stock_threshold, weight_g, dim_cm { l, w, h }, variants[].
Stock item / Movement (склад) — product_id, tracked, stock_quantity, effective_threshold, low, variants[]; движение: type, знаково qty, order_id, note.
Customer / Segment (клиенти) — агрегат по имейл (иначе телефон): orders_count, total_spent, първа/последна поръчка; сегмент: name, filters, customer_count.
Webhook / Delivery — url, events[], active, secret_prefix, last_status_code; доставка: event, status ∈ pending · delivered · failed · dead, attempt, next_attempt_at, last_status_code.

10. Webhooks с едно изречение

Абонирате се за order.created, order.updated, order.status_changed, order.paid, shipment.created, shipment.status_changed, shipment.cancelled, inventory.low_stock. Доставките са JSON пликове { id, event, created_at, account_id, api_version, data }, подписани с X-Velik-Signature: t=…,v1=… (HMAC-SHA256 върху t.body), доставени поне веднъж с повторни опити (1 мин → 5 мин → 30 мин → 2 ч → 12 ч; 6 опита), дедупликирани по id. Отговаряте с 2xx. Подробностите, всеки payload и код за проверка на три езика: webhooks.md (EN).

11. Версии и стабилност

Версията е в пътя: /api/v1. Webhook пликовете носят api_version (2026-09-01), защото там няма път.
v1 се променя само адитивно: нови endpoint-и, нови незадължителни полета, нови стойности в изброявания (документирани в CHANGELOG). Полета не се махат, преименуват или сменят тип. Приемайте непознати полета и стойности като съвместими напред.
Чупеща промяна = /api/v2, като v1 се пази поне 12 месеца паралелно, със заглавия Deprecation и Sunset, запис в changelog-а и имейл до мърчантите с активни ключове.
Договорът се пази от тестове в repo-то на velik.ai: всеки маршрут трябва да е в openapi.v1.yaml, всеки отговор се валидира срещу схемата си, а промяна на спецификацията изисква запис в changelog-а.

12. Добри практики

Пазете ключа като парола. Ротирайте с нов ключ и оттегляне на стария.
Ползвайте since или webhooks вместо пълни синхронизации.
Пращайте X-Velik-Dry-Run: 1, когато не сте сигурни.
Задайте User-Agent, който идентифицира интеграцията ви.
Поддръжка: support@velik.ai — с X-Deploy-SHA, пътя и error.code.

13. Поддръжка и статус

Къде: support@velik.ai. Една интеграция на тема; отговаряме в работни дни, инцидентите в продукция са с предимство.
Какво да включите: X-Deploy-SHA от отговора, пътя и метода, error.code и message, часа (UTC) и — при webhooks — X-Velik-Delivery / event_id. Никога не пращайте ключа; префиксът vk_ (първите 11 знака) стига, за да го разпознаем.
Статус на платформата: всеки отговор от /api/v1 носи X-Deploy-SHA (ревизията, която ви обслужва). 503 migration_pending значи, че тече обновяване — опитайте след минута. Отделна статус страница засега няма; инциденти, засягащи интегратори, се съобщават по имейл на мърчантите с активни ключове.
Промени: само адитивни във v1, винаги в Changelog с хеша на договора. Чупеща промяна = /api/v2 с поне 12 месеца v1 паралелно (§11).

Бърз старт: свързване на фулфилмънт център

Цел: да теглите новите поръчки, да ги приемете, да ги изпратите (със свой тракинг номер или през куриера на мърчанта), да държите склада в синхрон и да бъдете уведомявани при промяна — без периодично питане. Всеки отговор по-долу е реален, от продукционната система (id-та/имейли маскирани). English: quickstart-fulfilment.md.

Трябва ви: ключ с пресет 📦 Фулфилмънт, издаден от мърчанта (velik.ai → Настройки → 🔌 Интеграции → API ключове). По един ключ за всеки мърчант, когото обслужвате.

export VELIK_API_KEY=vk_…            # от мърчанта
export BASE=https://velik.ai

Стъпка 1 — теглене на новите поръчки

status=new е работният списък. Следвайте next_cursor, докато has_more стане false.

curl -sS -H "Authorization: Bearer $VELIK_API_KEY" "$BASE/api/v1/orders?status=new&limit=2"

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "number": 16,
      "order_number": 1546,
      "status": "new",
      "payment_status": "pending",
      "payment_method": "cod",
      "funnel_step": "original",
      "parent_order_id": null,
      "total": 29,
      "delivery_price": null,
      "discount_amount": null,
      "coupon_code": null,
      "refund_amount_cents": null,
      "refunded_at": null,
      "customer": {
        "name": "Тест V. C. V.",
        "email": "bo…@convertbuilder.com",
        "phone": "+359 8•• ••• •12",
        "vat": null
      },
      "shipping": {
        "address": "ул. Те ••• (masked)",
        "city": "София",
        "zip": "1000",
        "method": null,
        "courier_slug": "econt",
        "courier_delivery_mode": "home",
        "courier_office_id": null
      },
      "courier": null,
      "tracking_number": null,
      "tracking_url": null,
      "line_items": [
        {
          "qty": 1,
          "sku": null,
          "kind": "main",
          "name": "Хранителна добавка за сън",
          "product_id": "00000000-0000-4000-8000-000000000002",
          "variant_id": null,
          "total_cents": 2900,
          "delivery_type": "physical",
          "unit_price_cents": 2900
        }
      ],
      "product_name": "Хранителна добавка за сън",
      "product_sku": null,
      "quantity": 1,
      "unit_price": 29,
      "notes": null,
      "admin_notes": null,
      "return_note": null,
      "page_id": "00000000-0000-4000-8000-000000000003",
      "invoice_number": null,
      "shipment": null,
      "created_at": "2026-09-04T14:10:54.525378+00:00",
      "updated_at": "2026-09-05T14:34:46.691317+00:00"
    },
    {
      "id": "00000000-0000-4000-8000-000000000004",
      "number": 15,
      "order_number": 1544,
      "status": "new",
      "payment_status": "pending",
      "payment_method": "cod",
      "funnel_step": "original",
      "parent_order_id": null,
      "total": 41,
      "delivery_price": null,
      "discount_amount": null,
      "coupon_code": null,
      "refund_amount_cents": null,
      "refunded_at": null,
      "customer": {
        "name": "Тест V. C.",
        "email": "bo…@convertbuilder.com",
        "phone": "+359 8•• ••• •12",
        "vat": null
      },
      "shipping": {
        "address": "ул. Те ••• (masked)",
        "city": "София",
        "zip": "1000",
        "method": null,
        "courier_slug": "econt",
        "courier_delivery_mode": "home",
        "courier_office_id": null
      },
      "courier": null,
      "tracking_number": null,
      "tracking_url": null,
      "line_items": [
        {
          "qty": 1,
          "sku": null,
          "kind": "main",
          "name": "Хранителна добавка за сън",
          "product_id": "00000000-0000-4000-8000-000000000002",
          "variant_id": null,
          "total_cents": 2900,
          "delivery_type": "physical",
          "unit_price_cents": 2900
        }
      ],
      "product_name": "Хранителна добавка за сън",
      "product_sku": null,
      "quantity": 1,
      "unit_price": 29,
      "notes": "+ Downsell: Serenity Balance Woman — €12 вместо €39 — €12.00",
      "admin_notes": null,
      "return_note": null,
      "page_id": "00000000-0000-4000-8000-000000000003",
      "invoice_number": null,
      "shipment": {
        "id": "00000000-0000-4000-8000-000000000005",
        "courier_slug": "econt",
        "tracking_number": "1051•••91",
        "status": "cancelled",
        "last_status_label": "Анулирана",
        "last_status_at": "2026-09-05T15:12:02.308+00:00"
      },
      "created_at": "2026-09-04T12:22:17.798464+00:00",
      "updated_at": "2026-09-05T15:12:03.084937+00:00"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjIjoiMjAyNi0wOS0wNFQxMjoyMjoxNy43OTg0NjQrMDA6MDAiLCJpIjoiMjFlOTI4OTItMGQ0NC00OTE4LWJiNzktMDQ0ZDAxZGYwYzE3In0"
}

Какво четете от поръчката:

id — UUID-то, което ползвате във всяко следващо повикване (number е номерът, който мърчантът вижда: #16).
line_items[] — какво се опакова: product_id, variant_id, sku, name, qty; сумите са в стотинки/центове. kind: "main" е продуктът, bump / gift / component са добавки и части от пакет.
customer и shipping — получател, телефон, адрес и куриерът/режимът/офисът, избрани при поръчката (shipping.courier_slug, courier_delivery_mode, courier_office_id).
payment_method: "cod" + total — сумата на наложения платеж.

Съвет: courier=none стеснява списъка до поръчки без тракинг номер, а since=<ISO време> връща само променените след даден момент (README §7).

Стъпка 2 — приемане на поръчката

Преместете я в processing, за да вижда мърчантът, че се обработва. Първо пробно, ако искате:

curl -sS -X PATCH -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  -H "X-Velik-Dry-Run: 1" "$BASE/api/v1/orders/$ORDER_ID" -d '{"status":"processing"}'

После наистина:

curl -sS -X PATCH -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/orders/$ORDER_ID" -d '{"status":"processing"}'

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "number": 16,
    "order_number": 1546,
    "status": "processing",
    "payment_status": "pending",
    "payment_method": "cod",
    "funnel_step": "original",
    "parent_order_id": null,
    "total": 29,
    "delivery_price": null,
    "discount_amount": null,
    "coupon_code": null,
    "refund_amount_cents": null,
    "refunded_at": null,
    "customer": {
      "name": "Тест V. C. V.",
      "email": "bo…@convertbuilder.com",
      "phone": "+359 8•• ••• •12",
      "vat": null
    },
    "shipping": {
      "address": "ул. Те ••• (masked)",
      "city": "София",
      "zip": "1000",
      "method": null,
      "courier_slug": "econt",
      "courier_delivery_mode": "home",
      "courier_office_id": null
    },
    "courier": null,
    "tracking_number": null,
    "tracking_url": null,
    "line_items": [
      {
        "qty": 1,
        "sku": null,
        "kind": "main",
        "name": "Хранителна добавка за сън",
        "product_id": "00000000-0000-4000-8000-000000000002",
        "variant_id": null,
        "total_cents": 2900,
        "delivery_type": "physical",
        "unit_price_cents": 2900
      }
    ],
    "product_name": "Хранителна добавка за сън",
    "product_sku": null,
    "quantity": 1,
    "unit_price": 29,
    "notes": null,
    "admin_notes": null,
    "return_note": null,
    "page_id": "00000000-0000-4000-8000-000000000003",
    "invoice_number": null,
    "shipment": null,
    "created_at": "2026-09-04T14:10:54.525378+00:00",
    "updated_at": "2026-09-05T16:06:31.958157+00:00"
  },
  "status_changed": true,
  "email_sent": false
}

status_changed: true — преходът е направен (и всеки абонат за webhooks е получил order.status_changed). Повторно изпращане на същия статус е безобидно (status_changed: false).

Стъпка 3 — изпращане

Два модела. Изберете според договора си с куриерите.

(а) Имате собствен договор с куриер — пратете ни тракинг номера

Един PATCH: тракинг номер (+ по избор линк и име на куриер) и status: "shipped" заедно. shipped задейства имейла и SMS/Viber „поръчката е изпратена" на мърчанта към клиента, с вашия тракинг номер вътре — точно както ако мърчантът го е направил в админа. "notify_customer": false го спира (ние го спряхме по-долу, защото поръчката е тестова).

curl -sS -X PATCH -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/orders/$ORDER_ID" -d '{
    "tracking_number": "WMS-2026-000123",
    "tracking_url": "https://tracking.example-wms.com/WMS-2026-000123",
    "courier": "Speedy",
    "status": "shipped",
    "notify_customer": false
  }'

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "number": 16,
    "order_number": 1546,
    "status": "shipped",
    "payment_status": "pending",
    "payment_method": "cod",
    "funnel_step": "original",
    "parent_order_id": null,
    "total": 29,
    "delivery_price": null,
    "discount_amount": null,
    "coupon_code": null,
    "refund_amount_cents": null,
    "refunded_at": null,
    "customer": {
      "name": "Тест V. C. V.",
      "email": "bo…@convertbuilder.com",
      "phone": "+359 8•• ••• •12",
      "vat": null
    },
    "shipping": {
      "address": "ул. Те ••• (masked)",
      "city": "София",
      "zip": "1000",
      "method": null,
      "courier_slug": "econt",
      "courier_delivery_mode": "home",
      "courier_office_id": null
    },
    "courier": "Speedy",
    "tracking_number": "WMS-2026-000123",
    "tracking_url": "https://tracking.example-wms.com/WMS-2026-000123",
    "line_items": [
      {
        "qty": 1,
        "sku": null,
        "kind": "main",
        "name": "Хранителна добавка за сън",
        "product_id": "00000000-0000-4000-8000-000000000002",
        "variant_id": null,
        "total_cents": 2900,
        "delivery_type": "physical",
        "unit_price_cents": 2900
      }
    ],
    "product_name": "Хранителна добавка за сън",
    "product_sku": null,
    "quantity": 1,
    "unit_price": 29,
    "notes": null,
    "admin_notes": null,
    "return_note": null,
    "page_id": "00000000-0000-4000-8000-000000000003",
    "invoice_number": null,
    "shipment": null,
    "created_at": "2026-09-04T14:10:54.525378+00:00",
    "updated_at": "2026-09-05T16:06:32.348452+00:00"
  },
  "status_changed": true,
  "email_sent": false
}

email_sent казва дали имейлът реално е тръгнал (клиентът има имейл, известията са включени, шаблонът не е изключен от мърчанта).

(б) Изпращане през куриерската интеграция на мърчанта

Ако мърчантът има свързан Еконт / Спиди / BoxNow във velik.ai, едно повикване издава товарителница с неговия акаунт, по куриера/режима/офиса, избрани от клиента при поръчката (може да се презапише с courier, delivery_mode, office_id, weight_g, dim_cm). Наложеният платеж се смята на сървъра. Винаги първо пробно — резолвва всичко освен повикването към куриера:

curl -sS -X POST -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  -H "X-Velik-Dry-Run: 1" "$BASE/api/v1/shipments" -d "{\"order_id\":\"$ORDER_ID\"}"

{
  "dry_run": true,
  "courier": "econt",
  "delivery_mode": "home",
  "office_id": null,
  "weight_g": 500,
  "cod_amount": 41,
  "content_label": "Хранителна добавка за сън",
  "shipment_terms": {
    "cod_type": "cash",
    "open_before": "none",
    "refusal_payer": "sender"
  }
}

Махнете заглавието, за да я издадете. Отговорът е Shipment (тракинг номер, нормализиран status, НП, пратка); поръчката минава в processing, а webhooks изпращат shipment.created. После:

етикет: GET /api/v1/shipments/{shipment_id}/label → application/pdf (реалният Speedy етикет на реална пратка, 92 866 байта):
```
curl -sS -H "Authorization: Bearer $VELIK_API_KEY" -o label.pdf "$BASE/api/v1/shipments/$SHIPMENT_ID/label"
```

статус: GET /api/v1/shipments/{shipment_id} или GET /api/v1/orders/{order_id}/shipment:

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000008",
    "order_id": "00000000-0000-4000-8000-000000000009",
    "courier_slug": "speedy",
    "tracking_number": "6372•••83",
    "status": "pending",
    "last_status_label": "Получена информация за пратка",
    "last_status_at": "2026-08-28T11:52:05+00:00",
    "status_events": [
      {
        "at": "2026-08-28T14:52:05+0300",
        "code": "148",
        "label": "Получена информация за пратка"
      }
    ],
    "delivery_mode": "office",
    "office_id": "9289",
    "recipient_address": null,
    "cod_amount": 38,
    "shipping_cost": 4.56,
    "parcel_weight_g": 500,
    "parcel_dim_cm": null,
    "sender_origin": {
      "mode": "address"
    },
    "shipment_terms": {
      "cod_type": "cash",
      "open_before": "none",
      "refusal_payer": "sender"
    },
    "created_at": "2026-08-28T11:52:05.636473+00:00",
    "updated_at": "2026-08-28T12:00:12.689+00:00"
  }
}

анулиране: POST /api/v1/shipments/{shipment_id}/cancel (пробният режим казва дали още може):

{
  "dry_run": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000008",
    "order_id": "00000000-0000-4000-8000-000000000009",
    "courier_slug": "speedy",
    "tracking_number": "6372•••83",
    "status": "pending",
    "last_status_label": "Получена информация за пратка",
    "last_status_at": "2026-08-28T11:52:05+00:00",
    "status_events": [
      {
        "at": "2026-08-28T14:52:05+0300",
        "code": "148",
        "label": "Получена информация за пратка"
      }
    ],
    "delivery_mode": "office",
    "office_id": "9289",
    "recipient_address": null,
    "cod_amount": 38,
    "shipping_cost": 4.56,
    "parcel_weight_g": 500,
    "parcel_dim_cm": null,
    "sender_origin": {
      "mode": "address"
    },
    "shipment_terms": {
      "cod_type": "cash",
      "open_before": "none",
      "refusal_payer": "sender"
    },
    "created_at": "2026-08-28T11:52:05.636473+00:00",
    "updated_at": "2026-08-28T12:00:12.689+00:00"
  },
  "cancellable": true
}

Ако поръчката вече има жива товарителница — 409 conflict с details.shipment; ако куриерът откаже — 502 courier_error с причината в details.

Стъпка 4 — velik.ai ви казва какво се е променило (webhooks)

Вместо да питате, абонирайте се веднъж за всеки мърчант. Секретът идва само в този отговор:

curl -sS -X POST -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  "$BASE/api/v1/webhooks" -d '{
    "url": "https://wms.example.com/velik-webhook",
    "events": ["order.created", "order.updated", "order.status_changed", "shipment.created", "shipment.status_changed"],
    "description": "Fulfilment WMS"
  }'

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000035",
    "url": "https://velik.ai/api/webhooks/sink",
    "description": "Fulfilment WMS (probe)",
    "events": [
      "order.created",
      "order.updated",
      "order.status_changed",
      "shipment.created",
      "shipment.status_changed"
    ],
    "active": true,
    "secret_prefix": "whsec_efcd8722…",
    "last_triggered_at": null,
    "last_status_code": null,
    "dead_notified_at": null,
    "created_at": "2026-09-05T16:06:29.476938+00:00",
    "updated_at": "2026-09-05T16:06:29.476938+00:00"
  },
  "secret": "<64 hex characters — shown once, store it>"
}

Пратете си тестово събитие и вижте дневника на доставките:

curl -sS -X POST -H "Authorization: Bearer $VELIK_API_KEY" "$BASE/api/v1/webhooks/$WEBHOOK_ID/test"
curl -sS -H "Authorization: Bearer $VELIK_API_KEY" "$BASE/api/v1/webhooks/$WEBHOOK_ID/deliveries?limit=10"

Ето какво пристигна на адреса, когато изпълнихме Стъпка 2 — order.status_changed, подписано:

{
  "user-agent": "velik.ai-webhooks/1",
  "content-type": "application/json",
  "x-velik-event": "order.status_changed",
  "x-velik-delivery": "00000000-0000-4000-8000-000000000101",
  "x-velik-event-id": "00000000-0000-4000-8000-000000000102",
  "x-velik-signature": "t=1788615989,v1=<hex hmac-sha256>",
  "x-velik-timestamp": "1788615989"
}

{
  "id": "00000000-0000-4000-8000-000000000102",
  "data": {
    "order": {
      "id": "00000000-0000-4000-8000-000000000103",
      "notes": null,
      "total": 29,
      "number": 16,
      "status": "new",
      "courier": null,
      "page_id": "00000000-0000-4000-8000-000000000104",
      "customer": {
        "vat": null,
        "name": "Тест V. C. V.",
        "email": "bo…@convertbuilder.com",
        "phone": "+359 8•• ••• •12"
      },
      "quantity": 1,
      "shipment": null,
      "shipping": {
        "zip": "1000",
        "city": "София",
        "method": null,
        "address": "ул. Те ••• (masked)",
        "courier_slug": "econt",
        "courier_office_id": null,
        "courier_delivery_mode": "home"
      },
      "created_at": "2026-09-04T14:10:54.525378+00:00",
      "line_items": [
        {
          "qty": 1,
          "sku": null,
          "kind": "main",
          "name": "Хранителна добавка за сън",
          "product_id": "00000000-0000-4000-8000-000000000105",
          "variant_id": null,
          "total_cents": 2900,
          "delivery_type": "physical",
          "unit_price_cents": 2900
        }
      ],
      "unit_price": 29,
      "updated_at": "2026-09-05T13:46:29.166283+00:00",
      "admin_notes": null,
      "coupon_code": null,
      "funnel_step": "original",
      "product_sku": null,
      "refunded_at": null,
      "return_note": null,
      "order_number": 1546,
      "product_name": "Хранителна добавка за сън",
      "tracking_url": null,
      "delivery_price": null,
      "invoice_number": null,
      "payment_method": "cod",
      "payment_status": "pending",
      "discount_amount": null,
      "parent_order_id": null,
      "tracking_number": null,
      "refund_amount_cents": null
    },
    "source": "api",
    "status": "new",
    "previous_status": "shipped"
  },
  "event": "order.status_changed",
  "account_id": "00000000-0000-4000-8000-000000000106",
  "created_at": "2026-09-05T13:46:29.189Z",
  "api_version": "2026-09-01"
}

order.created → нова поръчка за опаковане (същата форма на data.order).
order.status_changed със status: "delivered" / "returned" / "cancelled" и source: "courier" → куриерът е докладвал изхода; velik.ai го отразява върху поръчката (и при cancelled / returned връща стоката в склада). Ползвайте го, за да затворите поръчката във вашата система.
shipment.status_changed → всяка промяна на нормализирания куриерски статус на товарителница, издадена през velik.ai, със суровото куриерско събитие.

Проверявайте подписа и дедупликирайте по id — webhooks.md (Node / Python / PHP).

Стъпка 5 — складът в синхрон

Наличности (по продукт, с варианти и праг за ниска наличност):

curl -sS -H "Authorization: Bearer $VELIK_API_KEY" "$BASE/api/v1/inventory/stock"

{
  "data": [
    {
      "product_id": "00000000-0000-4000-8000-000000000010",
      "name": "Електрическа четка за зъби",
      "sku": null,
      "tracked": true,
      "stock_quantity": 50,
      "low_stock_threshold": null,
      "effective_threshold": 5,
      "low": false,
      "block_on_zero_stock": false,
      "variants": []
    }
  ],
  "default_threshold": 5
}

Получена стока → delivery (положително количество; по избор unit_cost обновява среднопретеглената себестойност на мърчанта). Разлики от инвентаризация → correction (знаково количество). Продажби, освобождавания и връщания velik.ai записва сам при движение на поръчките. Пробно:

curl -sS -X POST -H "Authorization: Bearer $VELIK_API_KEY" -H "Content-Type: application/json" \
  -H "X-Velik-Dry-Run: 1" "$BASE/api/v1/inventory/movements" \
  -d "{\"product_id\":\"$PRODUCT_ID\",\"type\":\"delivery\",\"qty\":3,\"unit_cost\":2.5,\"note\":\"PO-4411\"}"

{
  "dry_run": true,
  "product_id": "00000000-0000-4000-8000-000000000010",
  "variant_id": null,
  "type": "delivery",
  "qty": 3,
  "unit_cost": 2.5,
  "enables_tracking": false
}

Наистина (после го върнахме с correction −3, така че наличността на мърчанта е непроменена):

{
  "ok": true,
  "applied": 1,
  "new_cost": null
}

Журналът показва всяко движение, включително записаните от velik.ai продажби (GET /api/v1/inventory/movements?product_id=…). Абонирайте се за inventory.low_stock, за да бъдете уведомени (веднъж дневно, по продукт), когато следен продукт падне до прага си.

Стъпка 6 — каталогът

За опаковането ще ви трябват SKU, тегла и размери:

curl -sS -H "Authorization: Bearer $VELIK_API_KEY" "$BASE/api/v1/products/$PRODUCT_ID"

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000010",
    "name": "Електрическа четка за зъби",
    "marketing_name": null,
    "sku": null,
    "price": 69,
    "original_price": null,
    "active": true,
    "delivery_type": "physical",
    "offer_type": "bundles",
    "description": "✓ Премахва до 10 пъти повече плака в сравнение с ръчна четка\n✓ Избелва зъбите видимо още след първата седмица на употреба\n✓ Защитава венците с интелигентен сензор за натиск\n✓ 4 режима на почистване за персонализирана грижа\n✓ Издръжлива батерия – до 4 седмици на едно зареждане",
    "images": [
      "https://hfnlrnkqudnwppvdluvy.supabase.co/storage/v1/object/public/page-images/generated/1782681654586-ypu2ppw3wc.jpeg",
      "https://hfnlrnkqudnwppvdluvy.supabase.co/storage/v1/object/public/page-images/generated/1782681689061-38s58mjnmwm.jpeg",
      "https://hfnlrnkqudnwppvdluvy.supabase.co/storage/v1/object/public/page-images/generated/1782681794489-30mmnr31kb3.jpeg"
    ],
    "stock_quantity": 50,
    "block_on_zero_stock": false,
    "low_stock_threshold": null,
    "weight_g": null,
    "dim_cm": null,
    "shipping_short_name": null,
    "shipping_category": null,
    "catalog_hidden": false,
    "language": "bg",
    "variants": [],
    "created_at": "2026-06-28T21:19:29.41932+00:00",
    "updated_at": "2026-09-05T15:15:22.873699+00:00"
  }
}

Капаните

Id-тата са UUID; #16 е number, не id. Не-UUID id е 400, UUID на друг мърчант е 404 (никога 403).
:write не включва :read. Пресетът „Фулфилмънт" има и двете; персонализиран ключ може да няма.
300 заявки/минута на ключ. Питайте със since, а по-добре — webhooks.
Webhooks са поне-веднъж. Едно и също id може да дойде два пъти — пазете обработените id-та.
Free план → 403 plan_required. Мърчантът трябва да е на Pro или нагоре.
X-Velik-Dry-Run: 1 на всеки запис, докато разработвате — валидира върху реалните данни на мърчанта и не записва нищо.

Готов код: examples/curl.sh, examples/node.mjs, examples/python.py.

Generated from docs/integrations/ in the velik.ai repository. Contract: /openapi.v1.yaml · API справочник · Postman collection · Privacy · Terms