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

Този раздел съдържа техническата документация на REST API на Planograma за интегратори и партньори: endpoint-и, HTTP методи, параметри, структури от данни и примери за заявки и отговори. API се използва от външни системи (ERP системи, e-commerce платформи).

Note

Имената на полетата, параметрите, пътищата и примерите в JSON са представени точно така, както се появяват в приложението. Обяснителният текст е на български език, но техническите наименования остават непроменени.

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

Всички заявки към /api/** изискват заглавката Authorization; нейната липса връща 401 Unauthorized със съобщение Invalid API KEY.

Интеграционните endpoint-и (продукти, наличност, поръчки, NIR и др.) използват потребителските данни на потребител на Planograma, изпратени в заглавката Authorization, във вида потребител:парола:

Authorization: Bearer <потребител>:<парола>

Системата разделя стойността по символа : и удостоверява потребителя в рамките на текущия наемател (определен от поддомейна/хоста). Ако форматът не е правилен или данните за вход са невалидни, отговорът е 401 Unauthorized.

Warning

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

Форма на отговорите

Повечето интеграционни endpoint-и връщат стандартен плик BaseApiResponse:

Поле	Тип	Описание
error	Boolean	true, ако заявката е неуспешна
errorMessage	String?	съобщение за грешка (когато error=true)
status	Int?	код на статуса
data	T?	полезните данни (списък или обект, в зависимост от endpoint-а)

Endpoint-ите от тип "read" връщат в data списък от info обекти (например ProductInfo, OrderInfo).

Note

Ключовете за външна идентификация (thirdPartyReference, externalReference, externalOrderId, externalLineId) позволяват на интеграторите да свържат документите от Planograma със своите собствени записи, без да зависят от вътрешните ID-та на Planograma.

---

Интеграционно API

Продукти

Базов ресурс: /api/product.

Метод	Път	Описание
POST	/api/product/read	списък на продукти с филтри
PUT	/api/product/add	добавяне на продукт
POST	/api/product/update	актуализиране на продукти
DELETE	/api/product/delete	изтриване на продукти
GET	/api/product/third-party-reference/{thirdPartyReference}/check	проверява съществуването на продукт по външна референция (връща Boolean)

Четенето (POST /api/product/read) получава ReadProductsFilterRequest (странициране чрез page по подразбиране 1 и limit по подразбиране 100, плюс филтри: productIds, models, categoryIds, thirdPartyReferenceIds, active и др.) и връща ProductApiResponse със списък от ProductInfo.

Основни полета на ProductInfo:

productId, productName, productCode, sku, thirdPartyReference,
categoryId, categoryName, vatId, vatPercentage,
purchasePrice, sellingPrice, minimumStock,
totalQuantityInStock, totalReservedQuantity, totalFreeQuantity, stockInfo,
requiresSerialNumber, requiresBatchCode, requiresBatchDetails,
requiresProductionDate, requiresExpirationDate,
width, height, length, weight, volume, diameter, material, color, active

Добавянето (PUT /api/product/add) получава AddProductApiRequest (задължителни полета name, code; категорията се посочва чрез categoryId или categoryExternalReference; плюс атрибутите за проследимост requiresSerialNumber, requiresBatchCode и др.). Актуализирането (EditProductApiRequest) насочва продуктите чрез productIds, а изтриването (DeleteProductApiRequest) чрез productIds или productModels.

Наличност

Базов ресурс: api/stock.

Метод	Път	Описание
POST	api/stock/remaining-stock/{productId}	наличното количество за продукт
POST	api/stock/all	странициран списък на наличностите
POST	api/stock/detailed-report	подробен отчет за наличността

POST api/stock/remaining-stock/{productId} получава CheckStockClientRequest (source, includeReservations, location). Ако location=true, наличността се разбива по локации; в противен случай се връща агрегираната обща сума.

POST api/stock/all приема параметрите за странициране page (по подразбиране 0) и size (по подразбиране 10) и тялото GetStocksRequest:

{
  "includeReservations": false,
  "isActive": true,
  "location": false
}

Отговор PagedStockResponse:

content: [ StockResponse ], totalElements, totalPages, size, number

където StockResponse има: productId, productName, productCode, remainingQuantity и, когато location=true, locationCode и locationName.

POST api/stock/detailed-report приема параметрите page (0), size (50), sortBy (productName), sortDirection (asc) и връща подробен отчет.

Поръчки

Базов ресурс: /api/order.

Метод	Път	Описание
POST	/api/order/read	списък на поръчки с филтри
PUT	/api/order/add	добавяне на поръчка
POST	/api/order/update	актуализиране на поръчки
POST	/api/order/order-ready	проверява дали поръчката е готова
DELETE	/api/order/delete	изтриване на поръчки
PUT	/api/order/print-document	отпечатване на документ за поръчка
POST	/api/order/picking-info	информация за пикинг
POST	/api/order/start-picking	стартиране на пикинг
PATCH	/api/order/update-status	актуализиране на статуса на поръчка
PATCH	/api/order/update-awb-link	актуализиране на външен AWB линк
POST	/api/order/check-orders-in-waiting-for-supply	повторна проверка на поръчки в очакване на наличност

Четенето (ReadOrdersFilterRequest) филтрира по orderIds, externalOrderIds, companyExternalReferences, warehouseIds, statuses, orderType, thirdPartyReferenceIds и връща OrderApiResponse със списък от OrderInfo.

Основни полета на OrderInfo:

orderId, externalOrderId, thirdPartyReference,
warehouseId, warehouseName, warehouseCode, status, orderType,
requiresValidation, dateAdded, isReady, picked, comment,
awbExternalLink, invoiceExternalLink,
numberOfEnvelopes, numberOfPackages, totalWeight, fulfilledWeight,
orderProducts, orderRequirements,
companyThirdPartyReference, companyExternalReference

Добавянето (PUT /api/order/add) получава CreateOrderApiRequest. Опростен пример:

{
  "externalOrderId": "WEB-1001",
  "warehouseId": 1,
  "orderType": 1,
  "validationRequired": 1,
  "company": { "name": "Client SRL", "cui": "RO123" },
  "orderProducts": [
    { "productModel": "ABC-123", "quantity": 2, "externalLineId": "L1", "locationCode": "A-01" }
  ]
}

externalOrderId е задължителен и трябва да бъде уникален. Редовете (CreateOrderProductApiRequest) идентифицират продукта чрез productModel (или productId); locationCode резервира наличността от определена локация.

Актуализирането (UpdateOrderApiRequest) насочва поръчките чрез orderIds, externalOrderIds или thirdPartyReferenceIds, а новите полета се подават в updateFields. PATCH /api/order/update-status (UpdateOrderStatusRequest: orderId, status, awbExternalLink) променя статуса на поръчка.

POST /api/order/picking-info отговаря с PickingInfoApiResponse: picked, numberOfPackages, numberOfEnvelopes, totalWeight, pickerId, pickerUsername.

Приемания (NIR)

Базов ресурс: /api/nir.

Метод	Път	Описание
PUT	/api/nir/add	добавяне на NIR
PATCH	/api/nir/update	актуализиране на NIR
POST	/api/nir/read	списък на NIR с филтри
POST	/api/nir/validation-info	информация за валидиране
DELETE	/api/nir/delete	изтриване на NIR
PATCH	/api/nir/update-external-reference	актуализиране на външна референция
PATCH	/api/nir/update-packaging-type	актуализиране на типа опаковка

Добавянето (CreateNirApiRequest) изисква externalReference (задължително), warehouseId, supplierId, списък nirProducts (NirProductApiInfo: code и quantity задължителни, externalLineId) и validationRequired (по подразбиране true).

Четенето (ReadNirsFilterRequest) филтрира по nirIds, externalOrderIds, externalClientIds, warehouseIds, thirdPartyReferenceIds и връща NirApiResponse със списък от NirInfo (nirId, externalReference, warehouseId, validated, status, nirProducts, thirdPartyReference, purchaseOrders).

POST /api/nir/validation-info (NirValidationInfoApiRequest: nirId или externalReference) връща NirValidationInfoApiResponse с validated, scanInfoList, userUsername и др.

Връщания

Базов ресурс: /api/return.

Метод	Път	Описание
PUT	/api/return/add	добавяне на връщане
POST	/api/return/read	списък на връщания с филтри
POST	/api/return/validation-info	информация за валидиране на връщане

PUT /api/return/add получава CreateReturnApiRequest: externalReference и externalClientId (задължителни), warehouseId, initialExternalOrderId, списък returnedProducts (ReturnProductApiInfo: code, quantity).

Трансфери

Ресурси: /api/transfer и /api/transfer-product.

Метод	Път	Описание
POST	/api/transfer/validate-transfer/{transferId}	валидиране на трансфер
POST	/api/transfer/change-transfer-status/{transferId}/{transferStatus}	смяна на статуса на трансфер
DELETE	/api/transfer/delete-transfer/{transferId}	изтриване на трансфер
POST	/api/transfer-product/add-transfer-product	добавяне на продукт в трансфер
DELETE	/api/transfer-product/delete-transfer-product/{transferProductId}	изтриване на продукт от трансфер

Добавянето на продукт (ScanClientRequest) включва: documentId, productId, quantity, sourceLocationCode, destinationLocationCode, batchCode, sn, ssccCode и др. Отговорът е ClientBaseResponse (message, status).

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

Базов ресурс: /api/inventory.

Метод	Път	Описание
POST	/api/inventory/stock-adjustment	корекция на наличност
GET	/api/inventory/{id}	информация за инвентаризация
GET	/api/inventory/{id}/delta	разликите (delta) на инвентаризацията

POST /api/inventory/stock-adjustment получава StockAdjustmentRequest: locationCode, inventoryId, model, quantity, recordedQuantity, stockBatchId, snList, stockBatchCode, expirationDate, productionDate, validate.

Поръчки за доставка

Базов ресурс: /api/purchase-order (изисква правото PURCHASE_ORDER).

Метод	Път	Описание
POST	/api/purchase-order/add	добавяне на поръчка за доставка
GET	/api/purchase-order/{purchaseOrderId}	детайли за поръчка за доставка
PATCH	/api/purchase-order/update	актуализиране
PATCH	/api/purchase-order/{purchaseOrderId}/status/{status}	смяна на статус
PATCH	/api/purchase-order/{purchaseOrderId}/close	затваряне
DELETE	/api/purchase-order/{purchaseOrderId}	изтриване
POST	/api/purchase-order/add-product	добавяне на продукт
DELETE	/api/purchase-order/remove-product/{id}	изтриване на продукт

CreatePurchaseOrderDTO: date (задължително, формат dd.MM.yyyy), arrivalDate, supplier (задължително), warehouseId, nirs, comment, documentNumber.

Производство

Базов ресурс: /api/production.

Метод	Път	Описание
POST	/api/production/read	списък на производствени поръчки с филтри
PUT	/api/production/add	добавяне на производствена поръчка
POST	/api/production/close-simplified-production/order/{orderId}	затваряне на опростено производство

Добавянето (AddProductionOrderRequest) изисква productId, quantity и thirdPartyReference. Отговорът (ProductionOrderApiResponse) съдържа списък от ProductionOrderInfo.

Номенклатори

Категории (/api/category)

Метод	Път	Описание
POST	/api/category/read	списък на категории
PUT	/api/category/add	добавяне
POST	/api/category/update	актуализиране
DELETE	/api/category/delete	изтриване

CategoryInfo: categoryId, externalReference, categoryName, categoryDetails, thirdPartyReference, active.

Мерни единици (/api/measurement-unit)

Метод	Път	Описание
PUT	/api/measurement-unit/add	добавяне
POST	/api/measurement-unit/read	списък
POST	/api/measurement-unit/update	актуализиране
DELETE	/api/measurement-unit/delete	изтриване

MeasurementUnitInfo: muId, name, code, details, status, thirdPartyReference.

Компании (/api/company)

Метод	Път	Описание
POST	/api/company/read	списък на компании (клиенти/доставчици)
PUT	/api/company/add	добавяне
POST	/api/company/update	актуализиране
DELETE	/api/company/delete	изтриване
GET	/api/company/third-party-reference/{thirdPartyReference}/check	проверява съществуването по външна референция

CompanyInfo: companyId, externalReference, name, cui, regNo, bank, iban, address, phone, email, website, type, active, thirdPartyReference.

Метаданни

Базов ресурс: /api/metadata. Леки endpoint-и за проверка на съществуването/съответствието на записите преди пълна синхронизация.

Метод	Път	Описание
POST	/api/metadata/category	метаданни за категории
POST	/api/metadata/product	метаданни за продукти
POST	/api/metadata/product/by_model	метаданни за продукти по модел
POST	/api/metadata/order	метаданни за поръчки

Всички получават ReadMetadataApiRequest (active, thirdPartyReferenceIds, models).

Известия, документи и тригери

Метод	Път	Описание
POST	/api/notifies	изпраща вътрешно известие (ExternalNotifyRequest: title, message, recipientId)
POST	/api/printable-document/notice/{orderId}	генерира известието за поръчката във формат PDF (application/pdf)
GET	/softone/trigger/order/{id}	задейства синхронизацията на поръчка
GET	/softone/trigger/nir/{id}	задейства синхронизацията на NIR
GET	/softone/trigger/delete/order/{id}	задейства изтриването на поръчка

---

Note

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