Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CodexaCP/DG_BACK/llms.txt

Use this file to discover all available pages before exploring further.

The Items API manages the product master catalog for each Dragon Guard tenant and exposes handheld-optimized inquiry endpoints that transparently proxy to GrupoMAS when the tenant is configured for native integration.

​
GET /api/items

Returns a paginated list of items for the specified company. Supports full-text search across item number, description, UOM, and item type. Authentication: Authorization: Bearer <token> (required).
​
companyId
string (uuid)
Tenant company ID. If omitted, resolved from the JWT claims.
​
search
string
Free-text search term matched against ItemNo, Description, UOM, and ItemType.
​
activeOnly
boolean
Filter to active items only. Defaults to true.
​
pageNumber
integer
1-based page number. Defaults to 1.
​
pageSize
integer
Number of records per page. Defaults to 20.
​
data
array
List of item summaries.
​
pageNumber
integer
Current page.
​
pageSize
integer
Records per page.
​
totalRecords
integer
Total matching records.
​
totalPages
integer
Total pages.
curl -X GET "https://api.example.com/api/items?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6&search=widget&pageNumber=1&pageSize=20" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/

Returns full detail for a single item including stock quantities (on-hand, on-purchase order, on-sales order, available) and all images. Authentication: Authorization: Bearer <token> (required).
​
id
string (uuid)
required
Item unique identifier.
​
companyId
string (uuid)
Tenant company ID. Resolved from JWT if omitted.
​
id
string (uuid)
Item ID.
​
itemNo
string
Item number.
​
description
string
Item description.
​
uOM
string
Primary UOM.
​
baseUOM
string
Base UOM.
​
salesUOM
string
Sales UOM.
​
purchaseUOM
string
Purchase UOM.
​
conversionFactor
decimal
UOM conversion factor.
​
isActive
boolean
Active flag.
​
isLotTracked
boolean
Lot tracking enabled.
​
isSerialTracked
boolean
Serial number tracking enabled.
​
isExpirationTracked
boolean
Expiration date tracking enabled.
​
barcode
string
Primary barcode.
​
altBarcode
string
Alternate barcode.
​
part_No
string
Supplier part number.
​
alternative_Code
string
Alternative item code.
​
quantityOnHand
decimal
Current on-hand stock quantity.
​
qtyOnPurchOrder
decimal
Quantity open on purchase orders.
​
qtyOnSalesOrder
decimal
Quantity open on sales orders.
​
qtyAvailable
decimal
Available quantity (on-hand minus sales orders).
​
stockoutWarning
boolean
true when on-hand quantity is zero or negative.
​
images
array
Item images.
Error codes
StatusMeaning
404Item not found for the given ID and company.
curl -X GET "https://api.example.com/api/items/3fa85f64-5717-4562-b3fc-2c963f66afa6?companyId=abc12345-0000-0000-0000-000000000001" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/by-itemno/

Returns full detail for a single item looked up by item number. For GrupoMAS tenants, proxies the lookup to MAS and falls back to the local catalog on error. Authentication: Authorization: Bearer <token> (required).
​
itemNo
string
required
Item number / SKU to look up.
​
companyId
string (uuid)
Tenant company ID. Resolved from JWT if omitted.
Returns the same ItemDetailDto shape as GET /api/items/{id}. Error codes
StatusMeaning
404Item not found for the given item number and company.
curl -X GET "https://api.example.com/api/items/by-itemno/ITM-000001?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/inquiry

Returns a paginated item inquiry with bin-level stock quantities per item. Joins item master, current stock, bins, and locations for each result row. Authentication: Authorization: Bearer <token> (required).
​
companyId
string (uuid)
Tenant company ID.
​
search
string
Free-text search across item number, description, UOM, type, barcode, and alt barcode.
​
activeOnly
boolean
Filter to active items only. Defaults to false.
​
pageNumber
integer
1-based page. Defaults to 1.
​
pageSize
integer
Page size. Defaults to 20.
​
data
array
Paginated item inquiry summaries with per-bin stock breakdown.
​
pageNumber
integer
Current page.
​
pageSize
integer
Page size.
​
totalRecords
integer
Total matching records.
​
totalPages
integer
Total pages.
curl -X GET "https://api.example.com/api/items/inquiry?search=widget&pageSize=25" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/products-inquiry

Handheld-optimized product inquiry. For GrupoMAS tenants, proxies the search to the MAS API and returns live stock data. For local tenants, queries the Dragon Guard catalog with bin-level stock. Authentication: Authorization: Bearer <token> (required).
​
companyId
string (uuid)
Tenant company ID.
​
search
string
Search term matched against item number, description, barcode, alt code, location code, and bin code.
​
locationCode
string
Filter results to a specific warehouse location.
​
hasStockOnly
boolean
When true, only items with quantity greater than zero are returned.
​
pageNumber
integer
1-based page. Defaults to 1.
​
pageSize
integer
Page size. Defaults to 20.
​
pageNumber
integer
Current page.
​
pageSize
integer
Page size.
​
totalRecords
integer
Total matching records.
​
totalPages
integer
Total pages.
​
totalQuantity
decimal
Sum of stock quantities (zero when no search/location filter is active).
​
quantityLabel
string
Display label for quantity (e.g., Cantidad).
​
items
array
List of product lookup lines with item info and per-bin stock.
curl -X GET "https://api.example.com/api/items/products-inquiry?search=widget&hasStockOnly=true&pageSize=50" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/products-locations

Returns the list of warehouse locations available for the handheld location filter dropdown. For GrupoMAS tenants, the list is fetched live from MAS. Always includes a leading “All locations” option with an empty locationCode. Authentication: Authorization: Bearer <token> (required).
​
companyId
string (uuid)
Tenant company ID.
​
defaultLocationCode
string
The pre-selected location code (empty string = all locations).
​
locations
array
curl -X GET "https://api.example.com/api/items/products-locations?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>"

​
GET /api/items/export-config

Exports the full item catalog for the tenant as an Excel workbook (.xlsx) formatted as a Dragon Guard config package. The workbook contains an Items worksheet and a hidden __wms_package metadata sheet. Authentication: Authorization: Bearer <token> (required).
​
companyId
string (uuid)
Tenant company ID.
Returns application/vnd.openxmlformats-officedocument.spreadsheetml.sheet with filename items_config_package.xlsx. 
curl -X GET "https://api.example.com/api/items/export-config?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>" \
  -o items_config_package.xlsx

​
POST /api/items/preview-config

Previews an items config package import without persisting any changes. Returns validation results and row-level action previews. Authentication: Authorization: Bearer <token> (required).
​
file
file
required
Multipart form upload. Must be a valid Dragon Guard ITEMS_MASTER config package .xlsx.
​
companyId
string (uuid)
Tenant company ID.
​
isValid
boolean
Whether the package passes all validations.
​
created
integer
Number of items that would be created.
​
updated
integer
Number of items that would be updated.
​
errors
array
Row-level validation errors.
​
rows
array
Preview of first 50 rows with planned action.
curl -X POST "https://api.example.com/api/items/preview-config?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>" \
  -F "file=@items_config_package.xlsx"

​
POST /api/items/apply-config

Imports items from a Dragon Guard config package Excel file. Upserts based on ItemNo, Barcode, Part_No, or Alternative_Code. Returns counts of created and updated records. Blocked for ERP-owned tenants. Authentication: Authorization: Bearer <token> (required).
​
file
file
required
Multipart form upload. Must be a valid Dragon Guard ITEMS_MASTER config package .xlsx.
​
confirmationToken
string
required
Confirmation token obtained from POST /api/items/preview-config to prevent accidental applies.
​
companyId
string (uuid)
Tenant company ID.
​
isValid
boolean
Whether the import completed without errors.
​
created
integer
Number of new items created.
​
updated
integer
Number of existing items updated.
​
errors
array
List of row-level validation errors if any.
curl -X POST "https://api.example.com/api/items/apply-config?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>" \
  -F "file=@items_config_package.xlsx" \
  -F "confirmationToken=<token-from-preview>"

​
POST /api/items/create_item

Creates a new item in the local catalog via the web interface. If initialQuantity is greater than zero, an opening stock inventory movement is created against the resolved bin. Blocked for tenants where the item master is owned by an ERP integration (e.g., GrupoMAS). Authentication: Authorization: Bearer <token> with role ADMIN or SUPERVISOR (required).
​
description
string
required
Item description.
​
uOM
string
required
Primary unit of measure.
​
barcode
string
Primary barcode. Must be unique within the tenant.
​
part_No
string
Supplier part number.
​
alternative_Code
string
Alternative item code.
​
brand
string
Brand name.
​
categoryCode
string
Category or group code.
​
initialQuantity
decimal
Opening stock quantity. Requires a valid location or bin. Defaults to 0.
​
locationId
string (uuid)
Location for initial stock placement. Uses default location if omitted.
​
binId
string (uuid)
Specific bin for initial stock. Uses default bin of the location if omitted.
​
message
string
Always Item created successfully on success.
​
id
string (uuid)
New item ID.
​
itemNo
string
Auto-generated item number (e.g., ITM-000001).
Error codes
StatusMeaning
400Missing required fields or invalid bin for initial stock.
403Caller does not have ADMIN or SUPERVISOR role.
409Barcode already exists in this tenant, or item master is ERP-owned.
curl -X POST "https://api.example.com/api/items/create_item" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Blue Widget 500g",
    "uOM": "EA",
    "barcode": "7501234567890",
    "initialQuantity": 100,
    "locationId": "loc-guid-here"
  }'

​
POST /api/items/handheld/create_item

Creates a new item from the handheld device. Requires role ADMIN or SUPERVISOR. Follows the same logic as the web create endpoint but is optimized for the handheld form with simplified fields. Creates movement type HANDHELD_CREATION instead of WEB_CREATION. Authentication: Authorization: Bearer <token> with role ADMIN or SUPERVISOR (required).
​
description
string
required
Item description.
​
uOM
string
required
Primary unit of measure.
​
barcode
string
Primary barcode. Must be unique within the tenant.
​
part_No
string
Supplier part number.
​
alternative_Code
string
Alternative item code.
​
brand
string
Brand name.
​
categoryCode
string
Category or group code.
​
initialQuantity
decimal
Opening stock quantity. Defaults to 0.
​
locationId
string (uuid)
Initial stock location ID.
​
binId
string (uuid)
Initial stock bin ID.
​
companyId
string (uuid)
Tenant company ID.
​
message
string
Always Producto creado correctamente. on success.
​
id
string (uuid)
New item ID.
​
itemNo
string
Auto-generated item number.
Error codes
StatusMeaning
400Missing description or UOM, or invalid bin.
403Caller does not have ADMIN or SUPERVISOR role, or items are ERP-owned.
409Barcode already exists in this tenant.
curl -X POST "https://api.example.com/api/items/handheld/create_item" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Producto Nuevo",
    "uOM": "EA",
    "barcode": "7501234567891",
    "initialQuantity": 0
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us