B2B документация

B2B API – автоматизирано извличане на информация за поръчки и продукти

Нашето REST API е достъпно за всеки клиент с клиентски акаунт и позволява автоматизирано извличане на информация за поръчки и продукти и интегрирането ѝ в собствени системи.

vpn_key Отвори API достъп в акаунта Страница за бизнес клиенти

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

Всички API заявки изискват валиден API ключ, който се изпраща в HTTP заглавката. API достъпът е свързан с вашия клиентски акаунт и по принцип е достъпен за клиентски акаунти.

info Не ви е необходима отделна B2B заявка: Влезте с вашия клиентски акаунт, отворете раздела API и генерирайте там вашия API ключ. Към API достъп →

Формат на заглавката

HTTP Request Header

X-API-Key: YOUR_API_KEY_HERE
Content-Type: application/json
Accept: application/json

Пример с cURL

cURL

curl -X GET "https://artumos.com/api/v1/orders" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Base URL

Всички endpoints са относителни спрямо следния Base URL:

Base URL

https://artumos.com/api/v1

Всички отговори се връщат като JSON се връщат (Content-Type: application/json).

Rate Limits

Plan	Заявки / минута	Заявки / ден
Клиентски акаунт	60	5.000
Разширен лимит	при поискване	при поискване

При превишаване се връща HTTP 429 Too Many Requests се връща. Заглавката Retry-After съдържа времето за изчакване в секунди.

Кодове за грешки

HTTP-Code	Значение
`200 OK`	Заявката е успешна
`400 Bad Request`	Невалидни параметри
`401 Unauthorized`	Липсващ или невалиден API ключ
`403 Forbidden`	Няма права за този ресурс
`404 Not Found`	Ресурсът не е намерен
`429 Too Many Requests`	Превишен Rate Limit
`500 Internal Server Error`	Сървърна грешка – моля, свържете се с поддръжката

Формат на отговора при грешка

JSON

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Endpoint: Поръчки

GET /api/v1/orders Всички поръчки на акаунта

Parameter	Тип	Описание
`page`	integer	Страница (по подразбиране: 1)
`per_page`	integer	Записи на страница (макс. 100)
`status`	string	`paid` \| `pending` \| `all`

Beispiel-Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ORD-12345",
        "status": "paid",
        "total": 49.99,
        "currency": "EUR",
        "created_at": "2026-01-15T10:30:00Z",
        "items_count": 2
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 42
    }
  }
}

GET /api/v1/orders/{order_id} Извличане на единична поръчка

Endpoint: Информация за продукти и поръчки

GET /api/v1/orders/{order_id}/codes Цялата информация за продуктите на дадена поръчка

Beispiel-Response

{
  "success": true,
  "data": {
    "order_id": "ORD-12345",
    "codes": [
      {
        "id": "CODE-789",
        "product_name": "Beispielprodukt vom Marktplatz",
        "product_sku": "ART-PRODUCT-001",
        "product_info": "Hinweise laut Verkäuferangaben",
        "delivery_url": "https://...",
        "delivered_at": "2026-01-15T10:31:00Z",
        "status": "active"
      }
    ]
  }
}

GET /api/v1/codes/{code_id} Извличане на единична информация за продукт

warning Информацията за продукти и поръчки може да се използва само в рамките на съответната поръчка и данните на продавача. Злоупотреба с препредаването може да наруши Условията за ползване.

Endpoint: Продукти

GET /api/v1/products Извличане на продуктов каталог

Parameter	Тип	Описание
`category`	string	Филтриране по slug на категория
`in_stock`	boolean	Само налични продукти
`page`	integer	Страница

Beispiel-Response

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 42,
        "sku": "ART-PRODUCT-001",
        "name": "Beispielprodukt vom Marktplatz",
        "price": 49.99,
        "currency": "EUR",
        "in_stock": true,
        "category": "handmade"
      }
    ]
  }
}

Webhooks

Webhooks позволяват получаване на известия в реално време, когато поръчки или кодове се предоставят. Webhook URL адреси могат да се зададат в клиентския акаунт.

Налични Events

Event	Описание
`order.paid`	Поръчката беше платена
`codes.delivered`	Кодовете бяха предоставени
`order.refunded`	Поръчката беше възстановена

Webhook Payload

POST – Вашият Webhook endpoint

{
  "event": "codes.delivered",
  "timestamp": "2026-01-15T10:31:05Z",
  "data": {
    "order_id": "ORD-12345",
    "codes_count": 2
  },
  "signature": "sha256=..."
}

Проверете подписа с вашия Webhook Secret: HMAC-SHA256(payload, webhook_secret)

Често задавани въпроси

Кой може да използва B2B API?

Всеки клиент с клиентски акаунт може да използва API достъпа. Влезте в клиентския си акаунт и използвайте свързания API ключ за удостоверени заявки.

Какъв формат имат отговорите?

Всички отговори се връщат като JSON. Root обектът винаги съдържа success: true/false както и или data или error.

Мога ли да правя поръчки чрез API?

В първата версия API служи за извличане на поръчки, информация за поръчки и продукти. Записващи endpoints за поръчки ще бъдат активирани отделно, веднага щом са налични.

Има ли Sandbox среда?

Да. Sandbox може да се активира в клиентския акаунт в раздела „API достъп“ и е директно свързана със съответния API ключ.