API¶

API на Gem Logic Ви позволява да интегрирате външни системи и да автоматизирате работни процеси. Можете да го използвате за програмно управление на продукти, продажби, контакти, ремонти, инвентарни преброявания и задачи за печат.

Отидете на Настройки ‣ API, за да създадете и управлявате API ключовете си.

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

Всички API заявки трябва да включват API ключ в HTTP заглавката x-api-key. Можете да създадете ключове от страницата Настройки ‣ API. Ключовете могат да бъдат деактивирани или изтрити по всяко време.

Примерна заявка:

curl -X GET https://your-instance.gem-logic.com/api/marketplaces/ \
  -H "x-api-key: YOUR_API_KEY"

Danger

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

Базов URL¶

Всички крайни точки са относителни спрямо URL адреса на Вашата инстанция, под префикса /api/:

https://your-instance.gem-logic.com/api/

Формат на отговора¶

Всички отговори се връщат като JSON. Успешните заявки връщат код за статус 200 (за GET) или 201 (за POST). Грешките връщат съответния код за статус със съобщение:

200 OK — успешна GET заявка
201 Created — успешна POST заявка
400 Bad Request — невалидни или липсващи данни
401 Unauthorized — невалиден или липсващ API ключ
404 Not Found — ресурсът не съществува

Крайни точки¶

Канали за продажби¶

Метод	`GET`
URL	`/api/marketplaces/`
Описание	Връща списък на всички канали за продажби.

Полета на отговора:

Поле	Тип	Описание
`id`	integer	Уникален идентификатор
`marketplace`	string	Име на маркетплейс

Продукти¶

Списък с продукти

Метод	`GET`
URL	`/api/products/{marketplace_id}`
Описание	Връща продукти, филтрирани по маркетплейс. Използвайте ID на маркетплейса от крайната точка marketplaces.

Полета на отговора:

Поле	Тип	Описание
`id`	integer	Уникален идентификатор
`item_sku`	string	SKU на продукта
`created`	datetime	Дата на създаване
`status`	string	Статус на продукта
`images`	array	Списък от изображения на продукта (`id`, `image`)
`item_weight`	decimal	Тегло
`item_height`	decimal	Височина
`item_length`	decimal	Дължина
`item_width`	decimal	Ширина

Създаване на изображение на продукт

Метод	`POST`
URL	`/api/products/create/image/`
Описание	Качва изображение на продукт с base64 кодиране. Ако SKU на продукта все още не съществува, нов продукт се създава автоматично.

Полета на заявката:

Поле	Тип	Задължително	Описание
`item_sku`	string	Да	SKU на продукта, към който да се прикачи изображението
`image`	string (base64)	Да	Данни на изображението, кодирани в base64

Продажби¶

Списък на продажбите

Метод	`GET`
URL	`/api/sales/`
Описание	Връща списък на всички поръчки за продажба.

Полета на отговора:

Поле	Тип	Описание
`order_id`	string	Уникален идентификатор на поръчката

Създаване на продажба

Метод	`POST`
URL	`/api/sales/create/`
Описание	Създава нова поръчка за продажба.

Контакти¶

Метод	`GET`
URL	`/api/contacts/`
Описание	Връща списък на всички контакти.

Полета на отговора:

Поле	Тип	Описание
`id`	integer	Уникален идентификатор
`complete_name`	string	Пълно име
`contact_type`	string	Тип контакт
`email`	string	Имейл адрес
`phone`	string	Телефонен номер
`language`	string	Предпочитан език

Ремонти¶

Създаване на ремонт

Метод	`POST`
URL	`/api/repairs/create/`
Описание	Създава нова поръчка за ремонт със свързан артикул за ремонт. Ако не е предоставен канал за продажби или подразделение, се използва първият наличен.

Полета на заявката:

Поле	Тип	Задължително	Описание
`client_id`	integer	Не	Идентификатор на клиент/контакт
`marketplace`	низ / цяло число	Не	Идентификатор или име на канал за продажби
`division_id`	integer	Не	Идентификатор на подразделение
`title`	string	Не	Заглавие или описание на артикула за ремонт
`repair_info_1`	string	Не	Допълнителен коментар за ремонт
`repair_info_2`	string	Не	Допълнителен коментар за ремонт
`repair_info_3`	string	Не	Допълнителен коментар за ремонт
`quantity`	decimal	Не	Количество (по подразбиране: 1)
`weight`	decimal	Не	Тегло на артикула
`weight_unit`	string	Не	Мерна единица за тегло
`size`	string	Не	Размер на артикула
`color`	string	Не	Цвят на артикула
`engravement`	string	Не	Текст за гравиране
`client_reference` \| string		Не	Референтен номер на клиента

Примерен отговор:

{"message": "Repair created successfully.", "order_id": "R-0001"}

Добавяне на артикул към ремонт

Метод	`POST`
URL	`/api/repairs/add-item/`
Описание	Добавя нов артикул към съществуваща поръчка за ремонт.

Полета на заявката:

Поле	Тип	Задължително	Описание
`order_id`	string	Да	Идентификатор на поръчката за ремонт, към която да се добави артикулът
`item_sku`	string	Не	SKU на продукта за свързване с артикула
`title`	string	Не	Заглавие или описание
`repair_info_1`	string	Не	Допълнителен коментар за ремонт
`repair_info_2`	string	Не	Допълнителен коментар за ремонт
`repair_info_3`	string	Не	Допълнителен коментар за ремонт
`quantity`	decimal	Не	Количество (по подразбиране: 1)
`weight`	decimal	Не	Тегло на артикула
`weight_unit`	string	Не	Мерна единица за тегло
`size`	string	Не	Размер на артикула
`color`	string	Не	Цвят на артикула
`engravement`	string	Не	Текст за гравиране
`client_reference` \| string		Не	Референтен номер на клиента
`cost`	decimal	Не	Цена на артикула

Инвентаризации¶

Създаване на инвентаризация

Метод	`POST`
URL	`/api/inventory-counts/`
Описание	Създава нова сесия за инвентаризация.

Полета на отговора:

Поле	Тип	Описание
`id`	string	Идентификатор на инвентаризацията
`created_at`	datetime	Времеви печат на създаването
`status`	string	Винаги `active`
`tag_count`	integer	Брой преброени продукти

Списък с продукти от инвентаризацията

Метод	`GET`
URL	`/api/inventory-counts/{inventory_count_id}/products/`
Описание	Връща всички продукти, преброени в конкретна инвентаризация.

Полета на отговора:

Поле	Тип	Описание
`id`	string	Уникален идентификатор
`created_at`	datetime	Кога продуктът е преброен
`product_sku`	string	SKU на продукта
`product_name`	string	Име на продукта
`quantity`	integer	Преброено количество

Задачи за печат¶

Метод	`POST`
URL	`/api/print-pdf/`
Описание	Качете PDF файл към опашката за печат за конкретен принтер. Файлът се валидира за формат и сигурност. Максимален размер на файл: 20 MB. Използвайте типа съдържание `multipart/form-data`.

Полета на заявката:

Поле	Тип	Задължително	Описание
`pdf`	файл	Да	PDF файл за печат (макс. 20 MB)
`printer_uuid`	UUID	Да	UUID на целевия принтер
`landscape`	булев	Не	Печат в пейзажен режим (по подразбиране: false)

Примерна заявка:

curl -X POST https://your-instance.gem-logic.com/api/print-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "pdf=@document.pdf" \
  -F "printer_uuid=YOUR_PRINTER_UUID"

Примерен отговор:

{"status": "queued", "print_job_id": 42}

Интерактивен API изследовател¶

Gem Logic включва вграден интерактивен API изследовател, базиран на Swagger UI. Можете да го достъпите чрез връзката API документация на страницата Настройки ‣ API. Изследователят Ви позволява да изпробвате всяка крайна точка директно от Вашия браузър.