Documentatie API

Aceasta sectiune contine documentatia tehnica a API-ului REST Planograma pentru integratori si parteneri: endpoint-uri, metode HTTP, parametri, structuri de date si exemple de cereri si raspunsuri. API-ul este folosit de sistemele externe (ERP-uri, platforme de e-commerce).

Note

Numele campurilor, parametrii, caile si exemplele JSON sunt prezentate exact asa cum apar in aplicatie. Textul explicativ este in limba romana, dar denumirile tehnice raman neschimbate.

Autentificare

Toate cererile catre /api/** necesita antetul Authorization; lipsa lui returneaza 401 Unauthorized cu mesajul Invalid API KEY.

Endpoint-urile de integrare (produse, stoc, comenzi, NIR-uri etc.) folosesc credentialele de utilizator Planograma trimise in antetul Authorization, sub forma utilizator:parola:

Authorization: Bearer <utilizator>:<parola>

Sistemul desparte valoarea dupa caracterul : si autentifica utilizatorul in cadrul tenantului curent (determinat din subdomeniu/host). Daca formatul nu este corect sau credentialele sunt invalide, raspunsul este 401 Unauthorized.

Warning

Foloseste un cont dedicat de integrare cu permisiunile minime necesare. Credentialele se transmit doar pe HTTPS.

Forma raspunsurilor

Majoritatea endpoint-urilor de integrare returneaza un plic standard BaseApiResponse:

Camp	Tip	Descriere
error	Boolean	true daca cererea a esuat
errorMessage	String?	mesajul de eroare (cand error=true)
status	Int?	codul de status
data	T?	datele utile (lista sau obiect, in functie de endpoint)

Endpoint-urile de tip "read" returneaza in data o lista de obiecte info (de exemplu ProductInfo, OrderInfo).

Note

Cheile de identificare externa (thirdPartyReference, externalReference, externalOrderId, externalLineId) permit integratorilor sa lege documentele din Planograma de propriile lor inregistrari, fara a depinde de ID-urile interne Planograma.

---

API de integrare

Produse

Resursa de baza: /api/product.

Metoda	Cale	Descriere
POST	/api/product/read	listare produse cu filtre
PUT	/api/product/add	adaugare produs
POST	/api/product/update	actualizare produse
DELETE	/api/product/delete	stergere produse
GET	/api/product/third-party-reference/{thirdPartyReference}/check	verifica existenta unui produs dupa referinta externa (returneaza Boolean)

Citirea (POST /api/product/read) primeste ReadProductsFilterRequest (paginare prin page implicit 1 si limit implicit 100, plus filtre: productIds, models, categoryIds, thirdPartyReferenceIds, active etc.) si returneaza ProductApiResponse cu o lista de ProductInfo.

Campuri principale 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

Adaugarea (PUT /api/product/add) primeste AddProductApiRequest (camp obligatoriu name, code; categoria se indica prin categoryId sau categoryExternalReference; plus atributele de trasabilitate requiresSerialNumber, requiresBatchCode etc.). Actualizarea (EditProductApiRequest) tinteste produsele prin productIds, iar stergerea (DeleteProductApiRequest) prin productIds sau productModels.

Stoc

Resursa de baza: api/stock.

Metoda	Cale	Descriere
POST	api/stock/remaining-stock/{productId}	stocul disponibil pentru un produs
POST	api/stock/all	listare paginata a stocurilor
POST	api/stock/detailed-report	raport detaliat de stoc

POST api/stock/remaining-stock/{productId} primeste CheckStockClientRequest (source, includeReservations, location). Daca location=true, stocul este defalcat pe locatii; altfel se returneaza totalul agregat.

POST api/stock/all accepta parametrii de paginare page (implicit 0) si size (implicit 10) si corpul GetStocksRequest:

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

Raspuns PagedStockResponse:

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

unde StockResponse are: productId, productName, productCode, remainingQuantity si, cand location=true, locationCode si locationName.

POST api/stock/detailed-report accepta parametrii page (0), size (50), sortBy (productName), sortDirection (asc) si returneaza un raport detaliat.

Comenzi

Resursa de baza: /api/order.

Metoda	Cale	Descriere
POST	/api/order/read	listare comenzi cu filtre
PUT	/api/order/add	adaugare comanda
POST	/api/order/update	actualizare comenzi
POST	/api/order/order-ready	verifica daca o comanda este gata
DELETE	/api/order/delete	stergere comenzi
PUT	/api/order/print-document	tiparire document comanda
POST	/api/order/picking-info	informatii de picking
POST	/api/order/start-picking	pornire picking
PATCH	/api/order/update-status	actualizare status comanda
PATCH	/api/order/update-awb-link	actualizare link AWB extern
POST	/api/order/check-orders-in-waiting-for-supply	reverificare comenzi in asteptarea stocului

Citirea (ReadOrdersFilterRequest) filtreaza dupa orderIds, externalOrderIds, companyExternalReferences, warehouseIds, statuses, orderType, thirdPartyReferenceIds si returneaza OrderApiResponse cu o lista de OrderInfo.

Campuri principale OrderInfo:

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

Adaugarea (PUT /api/order/add) primeste CreateOrderApiRequest. Exemplu simplificat:

{
  "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 este obligatoriu si trebuie sa fie unic. Liniile (CreateOrderProductApiRequest) identifica produsul prin productModel (sau productId); locationCode rezerva stocul dintr-o anumita locatie.

Actualizarea (UpdateOrderApiRequest) tinteste comenzile prin orderIds, externalOrderIds sau thirdPartyReferenceIds, iar campurile noi se trec in updateFields. PATCH /api/order/update-status (UpdateOrderStatusRequest: orderId, status, awbExternalLink) schimba statusul unei comenzi.

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

Receptii (NIR)

Resursa de baza: /api/nir.

Metoda	Cale	Descriere
PUT	/api/nir/add	adaugare NIR
PATCH	/api/nir/update	actualizare NIR
POST	/api/nir/read	listare NIR-uri cu filtre
POST	/api/nir/validation-info	informatii de validare
DELETE	/api/nir/delete	stergere NIR-uri
PATCH	/api/nir/update-external-reference	actualizare referinta externa
PATCH	/api/nir/update-packaging-type	actualizare tip ambalaj

Adaugarea (CreateNirApiRequest) cere externalReference (obligatoriu), warehouseId, supplierId, lista nirProducts (NirProductApiInfo: code si quantity obligatorii, externalLineId) si validationRequired (implicit true).

Citirea (ReadNirsFilterRequest) filtreaza dupa nirIds, externalOrderIds, externalClientIds, warehouseIds, thirdPartyReferenceIds si returneaza NirApiResponse cu lista de NirInfo (nirId, externalReference, warehouseId, validated, status, nirProducts, thirdPartyReference, purchaseOrders).

POST /api/nir/validation-info (NirValidationInfoApiRequest: nirId sau externalReference) returneaza NirValidationInfoApiResponse cu validated, scanInfoList, userUsername etc.

Retururi

Resursa de baza: /api/return.

Metoda	Cale	Descriere
PUT	/api/return/add	adaugare retur
POST	/api/return/read	listare retururi cu filtre
POST	/api/return/validation-info	informatii de validare retur

PUT /api/return/add primeste CreateReturnApiRequest: externalReference si externalClientId (obligatorii), warehouseId, initialExternalOrderId, lista returnedProducts (ReturnProductApiInfo: code, quantity).

Transferuri

Resurse: /api/transfer si /api/transfer-product.

Metoda	Cale	Descriere
POST	/api/transfer/validate-transfer/{transferId}	validare transfer
POST	/api/transfer/change-transfer-status/{transferId}/{transferStatus}	schimbare status transfer
DELETE	/api/transfer/delete-transfer/{transferId}	stergere transfer
POST	/api/transfer-product/add-transfer-product	adaugare produs in transfer
DELETE	/api/transfer-product/delete-transfer-product/{transferProductId}	stergere produs din transfer

Adaugarea unui produs (ScanClientRequest) include: documentId, productId, quantity, sourceLocationCode, destinationLocationCode, batchCode, sn, ssccCode etc. Raspunsul este ClientBaseResponse (message, status).

Inventar

Resursa de baza: /api/inventory.

Metoda	Cale	Descriere
POST	/api/inventory/stock-adjustment	ajustare de stoc
GET	/api/inventory/{id}	informatii inventar
GET	/api/inventory/{id}/delta	diferentele (delta) inventarului

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

Comenzi de achizitie

Resursa de baza: /api/purchase-order (necesita permisiunea PURCHASE_ORDER).

Metoda	Cale	Descriere
POST	/api/purchase-order/add	adaugare comanda de achizitie
GET	/api/purchase-order/{purchaseOrderId}	detalii comanda de achizitie
PATCH	/api/purchase-order/update	actualizare
PATCH	/api/purchase-order/{purchaseOrderId}/status/{status}	schimbare status
PATCH	/api/purchase-order/{purchaseOrderId}/close	inchidere
DELETE	/api/purchase-order/{purchaseOrderId}	stergere
POST	/api/purchase-order/add-product	adaugare produs
DELETE	/api/purchase-order/remove-product/{id}	stergere produs

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

Productie

Resursa de baza: /api/production.

Metoda	Cale	Descriere
POST	/api/production/read	listare ordine de productie cu filtre
PUT	/api/production/add	adaugare ordin de productie
POST	/api/production/close-simplified-production/order/{orderId}	inchidere productie simplificata

Adaugarea (AddProductionOrderRequest) cere productId, quantity si thirdPartyReference. Raspunsul (ProductionOrderApiResponse) contine o lista de ProductionOrderInfo.

Nomenclatoare

Categorii (/api/category)

Metoda	Cale	Descriere
POST	/api/category/read	listare categorii
PUT	/api/category/add	adaugare
POST	/api/category/update	actualizare
DELETE	/api/category/delete	stergere

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

Unitati de masura (/api/measurement-unit)

Metoda	Cale	Descriere
PUT	/api/measurement-unit/add	adaugare
POST	/api/measurement-unit/read	listare
POST	/api/measurement-unit/update	actualizare
DELETE	/api/measurement-unit/delete	stergere

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

Companii (/api/company)

Metoda	Cale	Descriere
POST	/api/company/read	listare companii (clienti/furnizori)
PUT	/api/company/add	adaugare
POST	/api/company/update	actualizare
DELETE	/api/company/delete	stergere
GET	/api/company/third-party-reference/{thirdPartyReference}/check	verifica existenta dupa referinta externa

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

Metadate

Resursa de baza: /api/metadata. Endpoint-uri usoare pentru verificarea existentei/maparii inregistrarilor, inainte de o sincronizare completa.

Metoda	Cale	Descriere
POST	/api/metadata/category	metadate categorii
POST	/api/metadata/product	metadate produse
POST	/api/metadata/product/by_model	metadate produse dupa model
POST	/api/metadata/order	metadate comenzi

Toate primesc ReadMetadataApiRequest (active, thirdPartyReferenceIds, models).

Notificari, documente si triggere

Metoda	Cale	Descriere
POST	/api/notifies	trimite o notificare interna (ExternalNotifyRequest: title, message, recipientId)
POST	/api/printable-document/notice/{orderId}	genereaza avizul comenzii in format PDF (application/pdf)
GET	/softone/trigger/order/{id}	declanseaza sincronizarea unei comenzi
GET	/softone/trigger/nir/{id}	declanseaza sincronizarea unui NIR
GET	/softone/trigger/delete/order/{id}	declanseaza stergerea unei comenzi

---

Note

Aceasta documentatie acopera structura curenta a API-ului. Pentru integrari noi, contacteaza echipa Planograma pentru un cont de integrare si pentru maparea statusurilor specifice sistemului tau.