Безплатна консултация
API v1

Документация на партньорското API

Заредете нашия каталог, цени по вашата листа и наличности в магазина си и поръчвайте директно — през един REST API.

Вход в клиентската зона Станете партньор
REST · JSON HTTPS Ключ от клиентската зона Цени в EUR без ДДС
Започване

Бърз старт в 3 стъпки

1Профил в клиентската зона

Като партньор получавате профил от вашия акаунт мениджър — с еднократен линк за парола и задължително приложение за 2FA.

Станете партньор
2Създайте ключ

В „API интеграции“ създавате ключ с нужните права и срок. Показва се само веднъж — запишете го на сървъра.

Как работят ключовете
3Първа заявка

Извикайте GET /me от сървъра си — отговорът показва правата, лимита и ценовата ви листа. После синхронизирайте.

GET /me
Започване

API ключове: два начина, едни правила

Сами — в клиентската зона

Влизате с парола и код от приложение за удостоверяване. Създаването и отнемането на ключ изисква паролата ви отново. Виждате всички ключове, кога и от кое IP са ползвани, и журнала на заявките.

Вход в клиентската зона
От нас — от профила ви при нас

Ако предпочитате, вашият акаунт мениджър издава ключа от профила на фирмата в нашата система и ви го предава лично или по сигурен канал. Никога по имейл.

  • Ключът се показва само веднъж. Пазим единствено неговия SHA-256 отпечатък — не можем да го видим и възстановим.
  • Всеки ключ има срок — до 365 дни. Препоръчваме 90 дни и ротация.
  • До 5 активни ключа на интеграция — отделен ключ за production и staging.
  • Ключовете започват с dfnd_, за да бъдат разпознати от скенерите за изтекли тайни (GitHub и др.).
  • Всяко създаване и отнемане се записва и уведомява нашия екип.
Започване

Удостоверяване

Всяка заявка носи ключа в хедъра Authorization като Bearer token. Отговорите са JSON; изпращайте и Accept: application/json.

Никога не слагайте ключа в код, който се изпълнява в браузъра или в мобилно приложение, и не го пращайте по имейл или чат. Пазете го като променлива на средата на сървъра.

Заявка
curl https://defend.bg/api/v1/me \
  -H "Authorization: Bearer $DEFEND_KEY" \
  -H "Accept: application/json"
Започване

Сигурност

API-то е проектирано така, че един изтекъл ключ да може да направи възможно най-малко — и да бъде спрян веднага.

2FA за клиентската зона

Вход само с парола от поне 12 знака и код от приложение. Без изключения.

Минимални права

Ключът има само нужните права: catalog:read, stock:read, orders:read, orders:write.

Разрешени IP адреси

Задайте IP адреса на сървъра си в клиентската зона — ключът няма да работи от другаде.

Само HTTPS

Всички заявки са по TLS. Заявки по HTTP не се обслужват.

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

Лимит на клиент в минута, с хедъри X-RateLimit-*.

Журнал на заявките

Всяка заявка се записва с час, адрес, статус и IP за 90 дни — виждате го и вие.

Започване

Как да синхронизирате

Веднъж дневноGET /products

Пълен каталог: имена, снимки, описания, категории. Сваляйте снимките при себе си.

На 15–60 минутиGET /stock?updated_since=…

Само променените наличности и цени от последната успешна синхронизация.

При всяка поръчкаPOST /orders

С вашия номер като external_ref. Повторен опит е безопасен.

Каталог

GET/me

Вашият достъп

Кой сте за системата: клиент, фирма, права на ключа, лимит на заявките и ценовата листа, по която получавате цени. Добра първа заявка, за да проверите ключа.

Право: catalog:read

Заявка
curl https://defend.bg/api/v1/me \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": {
    "client": "Пример Shop",
    "company": "Пример ЕООД",
    "abilities": ["catalog:read", "stock:read"],
    "rate_limit_per_minute": 120,
    "currency": "EUR",
    "prices": "net, without VAT",
    "price_list": "PARTNER-A"
  }
}

GET/categories

Категории

Плоският списък на категориите във вашия обхват. Дървото се сглобява по parent_id.

Право: catalog:read

Заявка
curl https://defend.bg/api/v1/categories \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": [
    { "id": 4, "parent_id": null, "slug": "kompyutri", "name": "Компютри" },
    { "id": 12, "parent_id": 4, "slug": "laptopi", "name": "Лаптопи" }
  ]
}

GET/brands

Марки

Марките, разрешени за вашия ключ.

Право: catalog:read

Заявка
curl https://defend.bg/api/v1/brands \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": [
    { "id": 3, "slug": "lenovo", "name": "Lenovo", "website": "https://www.lenovo.com" }
  ]
}

GET/products

Продукти

Каталогът с вашата цена, на страници. SKU-то е наше и никога не се променя — свързвайте продуктите си по него. availability е in_stock, low_stock, on_order или out_of_stock.

Право: catalog:read

Параметри

categoryinteger

Id на категория, включва подкатегориите

brandinteger

Id на марка

qstring

Търсене в името; точно съвпадение по SKU, MPN, EAN

in_stockboolean

Само с наличност > 0

updated_sinceISO 8601

Само променени след този момент

sortstring

updated_at, -updated_at, name, price, -price

per_page1–200

По подразбиране 50

Заявка
curl "https://defend.bg/api/v1/products?category=12&in_stock=1" \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": [{
    "sku": "DF7Q2K9M1A",
    "mpn": "21MA002ABM",
    "ean": "0197529871234",
    "name": "Lenovo ThinkPad E14 Gen 6",
    "brand": { "id": 3, "name": "Lenovo" },
    "category": { "id": 12, "path": "Компютри › Лаптопи" },
    "price": 612.40,
    "price_with_vat": 734.88,
    "vat_rate": 20,
    "currency": "EUR",
    "stock": 14,
    "availability": "in_stock",
    "lead_time_days": 2,
    "warranty_months": 24,
    "images": ["https://…/1.jpg"],
    "updated_at": "2026-10-24T09:12:03+03:00"
  }],
  "links": { "next": "…/products?page=2" },
  "meta": { "current_page": 1, "per_page": 50 }
}

GET/products/{sku}

Един продукт

Същите полета като в списъка, плюс пълното описание (description) и техническите характеристики (specs).

Право: catalog:read

Заявка
curl https://defend.bg/api/v1/products/DF7Q2K9M1A \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": {
    "sku": "DF7Q2K9M1A",
    "name": "Lenovo ThinkPad E14 Gen 6",
    "price": 612.40,
    "description": "<p>…</p>",
    "specs": { "CPU": "Intel Core i5", "RAM": "16 GB" }
  }
}

GET/stock

Наличности и цени

Лекият фийд за честа синхронизация. Подайте момента на последната успешна синхронизация като updated_since и следвайте next_cursor, докато стане null.

Право: stock:read

Параметри

updated_sinceISO 8601

Само променени след този момент

cursorstring

next_cursor от предишния отговор

per_page1–1000

Брой редове

Заявка
curl "https://defend.bg/api/v1/stock?updated_since=2026-10-24T09:00:00Z" \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": [
    { "sku": "DF7Q2K9M1A", "stock": 14, "availability": "in_stock",
      "lead_time_days": 2, "price": 612.40, "vat_rate": 20 }
  ],
  "meta": { "per_page": 1000, "next_cursor": "eyJpZCI6…", "currency": "EUR" }
}
Поръчки

GET/orders

Вашите поръчки

Поръчките, създадени с ключове на вашата фирма, най-новите първи.

Право: orders:read

Параметри

statusstring

new, confirmed, processing, shipped, delivered, cancelled, returned

external_refstring

Вашият номер на поръчка

per_page1–100

По подразбиране 25

Заявка
curl "https://defend.bg/api/v1/orders?status=shipped" \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": [{
    "number": "D-2026-000123",
    "external_ref": "WC-10482",
    "status": "shipped",
    "total": 1469.76,
    "tracking_number": "1234567890"
  }],
  "meta": { "current_page": 1, "per_page": 25 }
}

GET/orders/{number}

Една поръчка

Поръчката с артикулите, сумите, статуса на плащане и адреса за доставка. tracking_number се появява при изпращане.

Право: orders:read

Заявка
curl https://defend.bg/api/v1/orders/D-2026-000123 \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": {
    "number": "D-2026-000123",
    "external_ref": "WC-10482",
    "status": "confirmed",
    "payment_status": "unpaid",
    "subtotal": 1224.80,
    "vat_total": 244.96,
    "total": 1469.76,
    "items": [{ "sku": "DF7Q2K9M1A", "qty": 2, "unit_price": 612.40 }],
    "placed_at": "2026-10-24T10:02:11+03:00"
  }
}

POST/orders

Нова поръчка

Изпращате само SKU и количество — цените винаги са нашите, по вашата листа. Изпращайте собствения си номер като external_ref: повторна заявка със същия external_ref връща вече създадената поръчка с хедър X-Idempotent-Replay: true, така повторен опит след таймаут никога не прави дубликат.

Право: orders:write

Тяло на заявката

external_refstring *

Вашият номер на поръчка, до 120 знака

items[].sku, qtystring, int *

До 200 реда; qty от 1 до 10 000

shipping_addressobject *

name, phone, city, address *; email, postcode, courier, office_code

billingobject

company, eik, vat_number, mol, address

customer_notestring

До 2000 знака

Заявка
curl -X POST https://defend.bg/api/v1/orders \
  -H "Authorization: Bearer $DEFEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "WC-10482",
    "items": [{ "sku": "DF7Q2K9M1A", "qty": 2 }],
    "shipping_address": {
      "name": "Иван Петров", "phone": "+359888000000",
      "city": "Пловдив", "address": "ул. Примерна 1",
      "courier": "econt", "office_code": "1234"
    },
    "billing": { "company": "Пример ЕООД", "eik": "123456789" }
  }'
Отговор · 201
HTTP/1.1 201 Created

{
  "data": {
    "number": "D-2026-000123",
    "external_ref": "WC-10482",
    "status": "new",
    "total": 1469.76
  }
}

POST/orders/{number}/cancel

Отказ на поръчка

Възможен, докато статусът е new или confirmed. След това връща 409 not_cancellable — свържете се с нас.

Право: orders:write

Заявка
curl -X POST https://defend.bg/api/v1/orders/D-2026-000123/cancel \
  -H "Authorization: Bearer $DEFEND_KEY"
Отговор · 200
{
  "data": { "number": "D-2026-000123", "status": "cancelled" }
}
Справка

Статуси на поръчка

newНова confirmedПотвърдена processingОбработва се shippedИзпратена deliveredДоставена

Извън основния път: cancelled (отказана) и returned (върната). Статус на плащане: unpaid, partial, paid, refunded.

Грешки

Всяка грешка връща HTTP статус и обект error с машинен code, човешко message и при нужда details.

401unauthenticated

Липсващ, невалиден, изтекъл или отнет ключ

403forbidden

Ключът няма нужното право

403ip_not_allowed

IP адресът не е в разрешения списък

403client_inactive

Интеграцията е спряна

404not_found

Няма такъв продукт или поръчка във вашия обхват

409not_cancellable

Поръчката вече не може да бъде отказана

422validation

Невалидни данни; details съдържа полетата

422unknown_sku

SKU извън вашия обхват; details.skus ги изброява

429too_many_requests

Достигнат лимит — изчакайте Retry-After секунди

422 Unprocessable Content
{
  "error": {
    "code": "unknown_sku",
    "message": "Some SKUs are not available to this client.",
    "details": { "skus": ["DFXXXX"] }
  }
}

Лимити и добри практики

120 заявки в минута

Лимит по подразбиране на клиент, уговаря се в договора. X-RateLimit-Limit и X-RateLimit-Remaining показват докъде сте.

При 429 — изчакайте

Хедърът Retry-After казва след колко секунди да опитате пак.

Снимките при вас

Сваляйте ги веднъж в собственото си хранилище; не ги вграждайте директно от нас.

Безопасни повторни опити

При таймаут повторете POST /orders със същия external_ref — няма да се създаде дубликат.

Готови ли сте за интеграция?

Партньорите получават профил в клиентската зона, където сами управляват ключовете си. OpenAPI описанието е за генератори на клиенти.

Вход в клиентската зона OpenAPI JSON