> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.clinicea.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Clinicea Inventory Stock Movement API – Integration Guide

This guide is for partners integrating with Clinicea Inventory: sync documents, create stock movements, and consume outbound webhooks using the same JSON shapes. 

### 1. Overview
Clinicea Inventory exposes REST endpoints so partners can sync stock documents and create purchase orders, stock requests, send/receive stock, and returns. Outbound webhooks use the same payload shapes when stock changes in the Clinicea App. 
| **Environment**  | **Base URL**  |
| ---- | ---- |
| Production  | https://api.clinicea.com  |
 
| **Area**  | **Path prefix**  |
| ---- | ---- |
| Stock movement  | /api/v3/stockMovement/...  |
| Stock reduction  | /api/v3/stockReduction/...  |
| Swagger doc ref link | <https://api.clinicea.com/swagger/ui/index#/StockMovement><br><https://api.clinicea.com/swagger/ui/index#/StockReduction><br><https://api.clinicea.com/swagger/ui/index#/StockTake> |
 
### 2. Authentication and permissions
Authenticate with a Clinicea API key for a login that has Inventory feature permission. Patient logins are rejected (HTTP 401). 
•  use the same API-key header pattern as your other Clinicea integrations. 
Always use HTTPS.  

### 3. Common conventions
**3.1 Sync reads (GET)** 
•  lastSyncDTime — ISO datetime. Blank uses Clinicea default minimum sync time. 
•  organisationID — optional clinic GUID. Blank = every clinic in the head organisation. 
•  pageNo — 1-based. pageSize — 10 to 100. 
Persist the latest ModifiedDatetime from responses and pass it on the next sync call. 

**3.2 Creates (POST)** 
•  Content-Type: application/json. Error bodies are plain text. 
•  ID must be blank on create. 
•  VoucherDate is required and must not be in the future (UTC). 
•  Mode and party types are forced by the route — do not rely on VoucherMode from the body. 
Never send empty string ("") for DateTime fields. Use ISO-8601, or 1900-01-01T00:00:00 when a date means "not set". Empty DateTime often yields HTTP 400 with an empty body. 

**3.3 Parties** 
| **Route family**  | **SuppliedBy**  | **SuppliedTo**  |
| ---- | ---- | ---- |
| Purchase order  | Vendor  | Clinic  |
| Stock request / Send / Receive-from-clinic  | Clinic  | Clinic  |
| Return stock  | Clinic  | Vendor or Clinic  |
 
**3.4 Batch tracking** 
| **Document**  | **Batch required?**  |
| ---- | ---- |
| Purchase order / Stock request  | No  |
| Receive / Send / Return (if item maintains batch)  | Yes — BatchNo + future BatchExpiryDate  |
| Clinic→clinic receive / send / return  | Batch must exist on the clinic that loses stock (SuppliedBy)  |
 
**3.5 Linking documents** 
•  Allowed on createReceivedOrder\* and createSendStock: LinkType + LinkTypeID. 
•  Against vendor PO: LinkType = "PurchaseOrder". 
•  Against send-stock: LinkType = "SentOrder" (set explicitly — do not omit). 
•  Forbidden on createPurchaseOrder, createStockRequest, createReturnStock → HTTP 400. 

**3.6 HTTP status** 
| **Code**  | **Meaning**  |
| ---- | ---- |
| 200  | Success (JSON for lists/creates)  |
| 400  | Validation or business error (plain text)  |
| 401  | Not authorized / patient login / missing Inventory permission  |
 
HTTP 200 on create means the voucher was saved. Stock quantity changes follow App rules (e.g. return reduces clinic stock; vendor inventory is not increased). 

### 4. Stock Movement API — GET (sync)
GET /api/v3/stockMovement/{route}?lastSyncDTime=&organisationID=&pageNo=1&pageSize=10&api_key= 

**4.1 Posted documents** 
| **Route**  | **Returns**  |
| ---- | ---- |
| getPurchaseOrders  | Vendor → clinic purchase orders  |
| getStockRequests  | Clinic → clinic stock requests  |
| getReceivedOrders  | Received stock (not debit/credit/return)  |
| getReturnStock  | Returns  |
| getDebitNotes  | Debit notes  |
| getCreditNotes  | Credit notes  |
| getSendStock  | Posted send-stock orders  |
 
**4.2 Drafts** 
getPurchaseOrderDrafts, getStockRequestDrafts, getReceivedOrderDrafts, getReturnStockDrafts, getSendStockDrafts — IsDraft = true. 

**4.3 Transactions and template** 
•  getTransactions — one row per inventory adjustment. Quantity is signed. TransactionType: Consumable | Adjustment | Bill | Voucher. 
•  getReceiveStockCustomFieldTemplate — empty ReceiveStockDetails layout for createReceivedOrderFromVendor. 

### 5. Stock Movement API — POST (create)
POST /api/v3/stockMovement/{route}?api_key=   Body & response: DTOInventoryStockVoucher 

**5.1 createPurchaseOrder** 
Vendor → clinic. No stock movement. Batch not required. Link forbidden. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "PurchaseOrderDueDate": "2026-11-30T00:00:00", 
  "ReferenceNo": "PO-TEST-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{vendor-guid}", 
  "SuppliedToID": "{clinic-guid}", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 2, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "", 
      "BatchExpiryDate": "1900-01-01T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 
 
**5.2 createStockRequest** 
Clinic → clinic. Batch not required. Link forbidden. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "PurchaseOrderDueDate": "2026-11-30T00:00:00", 
  "ReferenceNo": "SR-TEST-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{requesting-clinic-guid}", 
  "SuppliedToID": "{fulfilling-clinic-guid}", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 2, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "", 
      "BatchExpiryDate": "1900-01-01T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 
 
**5.3 createSendStock** 
Clinic → clinic send. Reduces stock at SuppliedByID. Batch required when item is batched. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "ReferenceNo": "SEND-TEST-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{sending-clinic-guid}", 
  "SuppliedToID": "{receiving-clinic-guid}", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 2, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "{batch-on-sender}", 
      "BatchExpiryDate": "2027-07-31T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 
 
**5.4 createReturnStock** 
Clinic returns to vendor/clinic. StockTransfer + Rejection. Reduces clinic stock. Link forbidden. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "ReferenceNo": "RET-TEST-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{clinic-guid}", 
  "SuppliedToID": "{vendor-or-clinic-guid}", 
  "SuppliedTo": "Vendor", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 1, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "{batch-on-clinic}", 
      "BatchExpiryDate": "2027-07-31T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 
 
**5.5 createReceivedOrderFromVendor** 
Receive into clinic from vendor. Optional LinkType=PurchaseOrder + LinkTypeID to link/close a PO. Omit link for direct receive. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "ReferenceNo": "RCV-VENDOR-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{vendor-guid}", 
  "SuppliedToID": "{receiving-clinic-guid}", 
  "LinkType": "PurchaseOrder", 
  "LinkTypeID": "{optional-po-guid}", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 2, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "BATCH-001", 
      "BatchExpiryDate": "2027-06-30T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 
 
**5.6 createReceivedOrderFromClinic** 
Receive from another clinic. Batches from sending clinic (SuppliedByID). Against send-stock: LinkType=SentOrder. 
{ 
  "ID": "", 
  "VoucherDate": "2026-11-15T10:00:00", 
  "ReferenceNo": "RCV-CLINIC-001", 
  "Comments": "Optional", 
  "SuppliedByID": "{sending-clinic-guid}", 
  "SuppliedToID": "{receiving-clinic-guid}", 
  "LinkType": "SentOrder", 
  "LinkTypeID": "{optional-send-stock-guid}", 
  "VoucherItems": \[ 
    { 
      "InventoryID": "{inventory-guid}", 
      "PackQuantity": 2, 
      "FreePackQuantity": 0, 
      "DiscountPercentage": 0, 
      "BuyingPrice": 10.5, 
      "SellingPrice": 20, 
      "BatchNo": "{batch-on-sender}", 
      "BatchExpiryDate": "2027-07-31T00:00:00", 
      "ItemNotes": "" 
    } 
  ] 
} 

### 6. Recommended workflows
| **Workflow**  | **Steps**  |
| ---- | ---- |
| Vendor PO → receive  | 1) createPurchaseOrder  2) createReceivedOrderFromVendor with LinkType=PurchaseOrder + LinkTypeID  |
| Direct vendor receive  | createReceivedOrderFromVendor without LinkTypeID  |
| Clinic send → receive  | 1) createSendStock  2) optional createReceivedOrderFromClinic with LinkType=SentOrder  |
| Stock request  | createStockRequest between clinics  |
| Return to vendor  | createReturnStock (clinic SuppliedByID, vendor SuppliedToID)  |

### 7. Stock Reduction API 
**GET /api/v3/stockReduction/getChanges** 
Query: lastSyncDTime, organisationID, pageNo, pageSize, api_key 
Returns stock reduction documents changed after lastSyncDTime. Each document includes Items. Line Quantity is negative. Deleted documents are appended after the live page. Ordered by ModifiedDatetime. 
Response: List of DTOInventoryStockReduction.

### 8. Payload reference
**8.1 DTOInventoryStockVoucher** 
•  Header: ID, InvoiceNo, ReferenceNo, VoucherMode, VoucherType, VoucherDate 
•  Org: OrganisationID, HeadOrganisationID, OrganisationName 
•  Status: PurchaseOrderStatus, IsAuthorizationDue, IsDraft, Comments, PurchaseOrderDueDate 
•  Link: LinkType, LinkTypeID, LinkTypeNo (+ collated/split PO flags) 
•  Parties: SuppliedBy/ID/Name, SuppliedTo/ID/Name 
•  Lines: VoucherItems\[], ReceiveStockCustomDetails\[] 
•  Lists also include DTOAPIBase sync fields (ModifiedDatetime, IsDeleted, …) 

**8.2 DTOInventoryStockVoucherItem** 
InventoryID, InventoryName, BatchNo, BatchExpiryDate, PackSize, PackQuantity, FreePackQuantity, Quantity, StockDirection, QOH, BatchQOH, BuyingPrice, SellingPrice (nullable; null = master; 0 = explicit zero), DiscountPercentage, TaxID, ItemNotes. 

**8.3 DTOInventoryStockTransaction / Reduction / Adjust** 
•  Transaction — getTransactions row; signed Quantity; TransactionType Consumable|Adjustment|Bill|Voucher. 
•  Reduction — ReductionNumber, ClinicID/Name, Reason, ReductionDate, Comments, Items (Quantity negative). 
•  Adjust (webhook) — hand add/new batch/reduce only; not used for voucher lines. 

### 9. Webhooks
Register URLs in Clinicea Organisation webhook settings. Clinicea POSTs JSON asynchronously after a successful save. Webhook failure does not roll back the save. 

**9.1 Feature map** 
| **Feature**  | **When**  | **Payload**  |
| ---- | ---- | ---- |
| StockAdjust  | Hand inventory increase / decrease / new batch  | DTOInventoryStockAdjust  |
| StockVoucher  | Posted send / receive / return  | DTOInventoryStockVoucher  |
| PurchaseOrderRequest  | Vendor PO + clinic stock request  | DTOInventoryStockVoucher  |
| PurchaseOrderRequestDraft  | Drafts of PO / stock request  | DTOInventoryStockVoucher  |
| StockVoucherDraft  | Drafts of send / receive / return  | DTOInventoryStockVoucher  |
| StockReduction  | Stock reduction document (+ Delete)  | DTOInventoryStockReduction  |
| StockTake  | Completed stock take  | DTOInventoryStockTake  |
 
**9.2 API / App → webhook** 
| **Action**  | **Webhook feature**  |
| ---- | ---- |
| createPurchaseOrder / App PO  | PurchaseOrderRequest  |
| createStockRequest  | PurchaseOrderRequest  |
| createSendStock / createReceivedOrder* / createReturnStock  | StockVoucher  |
| Matching drafts  | PurchaseOrderRequestDraft or StockVoucherDraft  |
| Manual App stock adjust  | StockAdjust  |
| App stock reduction  | StockReduction  |

### 10. Validation catalogue (creates)
•  Body not null; ID blank; VoucherDate valid and not future 
•  SuppliedByID / SuppliedToID required GUIDs; parties exist 
•  Return: SuppliedTo Vendor or Clinic when provided 
•  Link forbidden on PO / stock request / return 
•  Items required; InventoryID GUID; PackQuantity > 0; FreePackQuantity >= 0; Discount 0–100 
•  Inventory exists in owning clinic; tax exists if overridden 
•  Batch rules per section 3.4; BatchExpiryDate future when present 
•  Receive-from-vendor: required custom fields must have PrimaryValue when posted 
•  Insufficient stock: -Ve###{InventoryID}###{BatchNo} 

### 11. Error examples 
| **HTTP**  | **Example body / meaning**  |
| ---- | ---- |
| 400  | Operation Failed: Object cannot be null (JSON bind / empty DateTime)  |
| 400  | LinkType and LinkTypeID are not allowed for purchase order, stock request, or return stock.  |
| 400  | Batch number is required for inventory … because batch tracking is on.  |
| 400  | BatchExpiryDate … must be a future date.  |
| 400  | -Ve###{inventoryId}###{batchNo}  |
| 401  | You are not Authorized to view this content  |