API Documentation

This section contains the technical documentation of the Planograma REST API for integrators and partners: endpoints, HTTP methods, parameters, data structures and examples of requests and responses. The API is used by external systems (ERPs, e-commerce platforms).

Note

Field names, parameters, paths and JSON examples are presented exactly as they appear in the application. The explanatory text is in English, but the technical names remain unchanged.

Authentication

All requests to /api/** require the Authorization header; its absence returns 401 Unauthorized with the message Invalid API KEY.

The integration endpoints (products, stock, orders, NIRs, etc.) use the Planograma user credentials sent in the Authorization header, in the form user:password:

Authorization: Bearer <user>:<password>

The system splits the value on the : character and authenticates the user within the current tenant (determined from the subdomain/host). If the format is incorrect or the credentials are invalid, the response is 401 Unauthorized.

Warning

Use a dedicated integration account with the minimum required permissions. Credentials are transmitted only over HTTPS.

Response format

Most integration endpoints return a standard BaseApiResponse envelope:

Field	Type	Description
error	Boolean	true if the request failed
errorMessage	String?	the error message (when error=true)
status	Int?	the status code
data	T?	the useful payload (list or object, depending on the endpoint)

"Read" endpoints return in data a list of info objects (for example ProductInfo, OrderInfo).

Note

The external identification keys (thirdPartyReference, externalReference, externalOrderId, externalLineId) allow integrators to link Planograma documents to their own records, without depending on the internal Planograma IDs.

---

Integration API

Products

Base resource: /api/product.

Method	Path	Description
POST	/api/product/read	list products with filters
PUT	/api/product/add	add product
POST	/api/product/update	update products
DELETE	/api/product/delete	delete products
GET	/api/product/third-party-reference/{thirdPartyReference}/check	check the existence of a product by external reference (returns Boolean)

Reading (POST /api/product/read) receives ReadProductsFilterRequest (pagination via page default 1 and limit default 100, plus filters: productIds, models, categoryIds, thirdPartyReferenceIds, active, etc.) and returns ProductApiResponse with a list of ProductInfo.

Main ProductInfo fields:

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

Adding (PUT /api/product/add) receives AddProductApiRequest (required field name, code; the category is indicated through categoryId or categoryExternalReference; plus the traceability attributes requiresSerialNumber, requiresBatchCode, etc.). Updating (EditProductApiRequest) targets products through productIds, while deletion (DeleteProductApiRequest) through productIds or productModels.

Stock

Base resource: api/stock.

Method	Path	Description
POST	api/stock/remaining-stock/{productId}	the available stock for a product
POST	api/stock/all	paginated listing of stocks
POST	api/stock/detailed-report	detailed stock report

POST api/stock/remaining-stock/{productId} receives CheckStockClientRequest (source, includeReservations, location). If location=true, the stock is broken down by location; otherwise the aggregated total is returned.

POST api/stock/all accepts the pagination parameters page (default 0) and size (default 10) and the body GetStocksRequest:

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

Response PagedStockResponse:

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

where StockResponse has: productId, productName, productCode, remainingQuantity and, when location=true, locationCode and locationName.

POST api/stock/detailed-report accepts the parameters page (0), size (50), sortBy (productName), sortDirection (asc) and returns a detailed report.

Orders

Base resource: /api/order.

Method	Path	Description
POST	/api/order/read	list orders with filters
PUT	/api/order/add	add order
POST	/api/order/update	update orders
POST	/api/order/order-ready	check whether an order is ready
DELETE	/api/order/delete	delete orders
PUT	/api/order/print-document	print order document
POST	/api/order/picking-info	picking information
POST	/api/order/start-picking	start picking
PATCH	/api/order/update-status	update order status
PATCH	/api/order/update-awb-link	update external AWB link
POST	/api/order/check-orders-in-waiting-for-supply	recheck orders waiting for stock

Reading (ReadOrdersFilterRequest) filters by orderIds, externalOrderIds, companyExternalReferences, warehouseIds, statuses, orderType, thirdPartyReferenceIds and returns OrderApiResponse with a list of OrderInfo.

Main OrderInfo fields:

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

Adding (PUT /api/order/add) receives CreateOrderApiRequest. Simplified example:

{
  "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 is required and must be unique. The lines (CreateOrderProductApiRequest) identify the product through productModel (or productId); locationCode reserves the stock from a specific location.

Updating (UpdateOrderApiRequest) targets orders through orderIds, externalOrderIds or thirdPartyReferenceIds, and the new fields are passed in updateFields. PATCH /api/order/update-status (UpdateOrderStatusRequest: orderId, status, awbExternalLink) changes the status of an order.

POST /api/order/picking-info responds with PickingInfoApiResponse: picked, numberOfPackages, numberOfEnvelopes, totalWeight, pickerId, pickerUsername.

Goods receipts (NIR)

Base resource: /api/nir.

Method	Path	Description
PUT	/api/nir/add	add NIR
PATCH	/api/nir/update	update NIR
POST	/api/nir/read	list NIRs with filters
POST	/api/nir/validation-info	validation information
DELETE	/api/nir/delete	delete NIRs
PATCH	/api/nir/update-external-reference	update external reference
PATCH	/api/nir/update-packaging-type	update packaging type

Adding (CreateNirApiRequest) requires externalReference (required), warehouseId, supplierId, the list nirProducts (NirProductApiInfo: code and quantity required, externalLineId) and validationRequired (default true).

Reading (ReadNirsFilterRequest) filters by nirIds, externalOrderIds, externalClientIds, warehouseIds, thirdPartyReferenceIds and returns NirApiResponse with a list of NirInfo (nirId, externalReference, warehouseId, validated, status, nirProducts, thirdPartyReference, purchaseOrders).

POST /api/nir/validation-info (NirValidationInfoApiRequest: nirId or externalReference) returns NirValidationInfoApiResponse with validated, scanInfoList, userUsername, etc.

Returns

Base resource: /api/return.

Method	Path	Description
PUT	/api/return/add	add return
POST	/api/return/read	list returns with filters
POST	/api/return/validation-info	return validation information

PUT /api/return/add receives CreateReturnApiRequest: externalReference and externalClientId (required), warehouseId, initialExternalOrderId, the list returnedProducts (ReturnProductApiInfo: code, quantity).

Transfers

Resources: /api/transfer and /api/transfer-product.

Method	Path	Description
POST	/api/transfer/validate-transfer/{transferId}	validate transfer
POST	/api/transfer/change-transfer-status/{transferId}/{transferStatus}	change transfer status
DELETE	/api/transfer/delete-transfer/{transferId}	delete transfer
POST	/api/transfer-product/add-transfer-product	add product to transfer
DELETE	/api/transfer-product/delete-transfer-product/{transferProductId}	remove product from transfer

Adding a product (ScanClientRequest) includes: documentId, productId, quantity, sourceLocationCode, destinationLocationCode, batchCode, sn, ssccCode, etc. The response is ClientBaseResponse (message, status).

Inventory

Base resource: /api/inventory.

Method	Path	Description
POST	/api/inventory/stock-adjustment	stock adjustment
GET	/api/inventory/{id}	inventory information
GET	/api/inventory/{id}/delta	the inventory differences (delta)

POST /api/inventory/stock-adjustment receives StockAdjustmentRequest: locationCode, inventoryId, model, quantity, recordedQuantity, stockBatchId, snList, stockBatchCode, expirationDate, productionDate, validate.

Purchase orders

Base resource: /api/purchase-order (requires the PURCHASE_ORDER permission).

Method	Path	Description
POST	/api/purchase-order/add	add purchase order
GET	/api/purchase-order/{purchaseOrderId}	purchase order details
PATCH	/api/purchase-order/update	update
PATCH	/api/purchase-order/{purchaseOrderId}/status/{status}	change status
PATCH	/api/purchase-order/{purchaseOrderId}/close	close
DELETE	/api/purchase-order/{purchaseOrderId}	delete
POST	/api/purchase-order/add-product	add product
DELETE	/api/purchase-order/remove-product/{id}	remove product

CreatePurchaseOrderDTO: date (required, format dd.MM.yyyy), arrivalDate, supplier (required), warehouseId, nirs, comment, documentNumber.

Production

Base resource: /api/production.

Method	Path	Description
POST	/api/production/read	list production orders with filters
PUT	/api/production/add	add production order
POST	/api/production/close-simplified-production/order/{orderId}	close simplified production

Adding (AddProductionOrderRequest) requires productId, quantity and thirdPartyReference. The response (ProductionOrderApiResponse) contains a list of ProductionOrderInfo.

Nomenclatures

Categories (/api/category)

Method	Path	Description
POST	/api/category/read	list categories
PUT	/api/category/add	add
POST	/api/category/update	update
DELETE	/api/category/delete	delete

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

Measurement units (/api/measurement-unit)

Method	Path	Description
PUT	/api/measurement-unit/add	add
POST	/api/measurement-unit/read	list
POST	/api/measurement-unit/update	update
DELETE	/api/measurement-unit/delete	delete

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

Companies (/api/company)

Method	Path	Description
POST	/api/company/read	list companies (clients/suppliers)
PUT	/api/company/add	add
POST	/api/company/update	update
DELETE	/api/company/delete	delete
GET	/api/company/third-party-reference/{thirdPartyReference}/check	check existence by external reference

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

Metadata

Base resource: /api/metadata. Lightweight endpoints for checking the existence/mapping of records, before a full synchronization.

Method	Path	Description
POST	/api/metadata/category	category metadata
POST	/api/metadata/product	product metadata
POST	/api/metadata/product/by_model	product metadata by model
POST	/api/metadata/order	order metadata

All receive ReadMetadataApiRequest (active, thirdPartyReferenceIds, models).

Notifications, documents and triggers

Method	Path	Description
POST	/api/notifies	send an internal notification (ExternalNotifyRequest: title, message, recipientId)
POST	/api/printable-document/notice/{orderId}	generate the order notice in PDF format (application/pdf)
GET	/softone/trigger/order/{id}	trigger the synchronization of an order
GET	/softone/trigger/nir/{id}	trigger the synchronization of a NIR
GET	/softone/trigger/delete/order/{id}	trigger the deletion of an order

---

Note

This documentation covers the current structure of the API. For new integrations, contact the Planograma team for an integration account and for the mapping of the statuses specific to your system.