API документация
Каталожното API е само за четене. С него партньори могат да зареждат продукти и категории. Входът в сайта не се използва за заявки — нужен е отделен API ключ.
Първи стъпки
API-то връща JSON. Базовият адрес е същият като тази страница, а конкретните методи са пътища след него.
Базов адрес
https://kimet.rs16.net/api
Всички пътища по-долу са спрямо този адрес.
Удостоверяване
Bearer / X-Api-Key
Ключът се изпраща с всяка заявка.
Лимит
60 / мин.
На ключ. При превишаване отговорът е HTTP 429.
Монтаж
- Поискайте API ключ през Контакти. Ключът започва с
kmt_и се издава от нас — не се създава от профила. - Добавете ключа към всяка заявка като Authorization: Bearer или като X-Api-Key.
- Започнете с категориите, после зареждайте продуктите по страници от по 50 записа.
Изпратете ключа по един от двата начина — резултатът е еднакъв.
HTTP
Authorization: Bearer YOUR_API_KEY
X-Api-Key: YOUR_API_KEYВръщат се само активни, неархивирани продукти с включен превод за избрания език. Размерът на страницата е фиксиран и не може да се променя от клиента.
Крайни точки
Двата метода по-долу покриват целия каталог. И двата изискват API ключ.
GET
/api/products
Странициран каталог. Полето data е обект, ключовете са идентификаторите на продуктите — не масив.
Параметри
| Име | По подразбиране | Описание |
|---|---|---|
| page | 1 | Номер на страницата. |
| lang | bg | Език на преводите. Налични кодове: bg, en, pl. |
| categoryID | — | Филтър по идентификатор на категория. Вземете стойностите от /api/products/categories. |
| distributor | — | Филтър по код на дистрибутор. Непознат код връща празен резултат. |
| sku | — | Един SKU или списък, разделен със запетая. Пример: AURA-1-BK или AURA-1-BK,AURA-2-WH. |
Кодове на дистрибутори:
- eurolamp
- eko-light
- emibig
- ideus
- kobi
- aldex
- vkled
Полета в продукта
| Поле | Тип | Описание |
|---|---|---|
| title | string | Име на продукта за избрания език. |
| catalog_number | string | SKU / каталожен номер. |
| ean | string|null | Баркод, ако има такъв. |
| distributor | object|null | Обект с code и name, или null ако продуктът няма дистрибутор. |
| gallery_images | string[] | Абсолютни URL адреси на изображенията. Ако няма снимки, масивът съдържа placeholder. |
| image_url | string | Първото изображение, удобно за списъци. |
| price | number | Редовна цена като число. Ако липсва, стойността е 0. |
| promotional_price | number|null | Промоционална цена, или null ако няма промоция. |
| categories | string | Път в дървото, разделен с „>“. Празен низ ако няма категория. |
| stock | number | Налично количество. |
| attributes | object | Ключът е името на атрибута, стойността е избраната опция — и двете на избрания език. |
Заявка
cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://kimet.rs16.net/api/products?lang=bg&page=1"
JavaScript
const response = await fetch('https://kimet.rs16.net/api/products?lang=bg&page=1', {
headers: {
Authorization: 'Bearer YOUR_API_KEY',
},
});
if (!response.ok) {
throw new Error(await response.text());
}
const payload = await response.json();
PHP
$ch = curl_init('https://kimet.rs16.net/api/products?lang=bg&page=1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Accept: application/json',
],
]);
$json = curl_exec($ch);
curl_close($ch);
$payload = json_decode($json, true);Отговор 200
JSON
{
"data": {
"1842": {
"title": "Pendant lamp AURA 1",
"catalog_number": "AURA-1-BK",
"ean": "5901234567890",
"distributor": {
"code": "eurolamp",
"name": "Eurolamp"
},
"gallery_images": [
"https://kimet.rs16.net/images/placeholder-image.png"
],
"image_url": "https://kimet.rs16.net/images/placeholder-image.png",
"price": 129.9,
"promotional_price": 99.9,
"categories": "Lighting > Pendant lamps",
"stock": 14,
"attributes": {
"Color": "Black",
"Material": "Metal"
}
}
},
"links": {
"first": "https://kimet.rs16.net/api/products?page=1",
"last": "https://kimet.rs16.net/api/products?page=8",
"prev": null,
"next": "https://kimet.rs16.net/api/products?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 8,
"path": "https://kimet.rs16.net/api/products",
"per_page": 50,
"to": 50,
"total": 376
}
}links и meta следват стандартната Laravel пагинация. per_page винаги е 50.
GET
/api/products/categories
Списък с активни категории за филтъра categoryID. Връща се масив в data.
Параметри
| Име | По подразбиране | Описание |
|---|---|---|
| lang | bg | Език на имената на категориите. |
Полета
| Поле | Тип | Описание |
|---|---|---|
| id | number | Подава се като categoryID към /api/products. |
| name | string | Име на категорията за избрания език. |
Заявка
cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://kimet.rs16.net/api/products/categories?lang=bg"
JavaScript
const response = await fetch('https://kimet.rs16.net/api/products/categories?lang=bg', {
headers: {
Authorization: 'Bearer YOUR_API_KEY',
},
});
if (!response.ok) {
throw new Error(await response.text());
}
const payload = await response.json();
PHP
$ch = curl_init('https://kimet.rs16.net/api/products/categories?lang=bg');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_KEY',
'Accept: application/json',
],
]);
$json = curl_exec($ch);
curl_close($ch);
$payload = json_decode($json, true);Отговор 200
JSON
{
"data": [
{
"id": 12,
"name": "Pendant lamps"
},
{
"id": 18,
"name": "Floor lamps"
},
{
"id": 24,
"name": "Wall lamps"
}
]
}Грешки
Неуспешните отговори са JSON с поле message.
| HTTP | message | Кога |
|---|---|---|
| 401 | API key is required | Липсва оторизация или X-Api-Key. |
| 401 | Invalid API key | Ключът е грешен или е прекратен. |
| 429 | Too many requests | Превишен е лимитът за минутата. Проверете заглавката Retry-After. |
401 / 429
{
"message": "API key is required"
}
{
"message": "Invalid API key"
}
{
"message": "Too many requests"
}