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.

Catalog synchronization lets an ERP or back-office integrator push item master data and opening stock balances into Dragon Guard over a REST API without requiring a database-level connection. Dragon Guard upserts each item record (creating it if it does not exist, updating it if it does) and applies opening stock as a single idempotent posting. All catalog sync endpoints require an X-Api-Key header for tenant resolution — JWT is not used on these routes.
Catalog sync endpoints are available under both api/v1/integration/ (canonical) and api/integration/ (legacy alias). Both prefixes are fully supported and identical in behavior.
Catalog sync is disabled for ERP-owned providers such as GrupoMASNative and BusinessCentralNative. Calling these endpoints from a tenant configured with IntegrationMode = ERP_EXECUTION returns 409 Conflict. Use GET /api/v1/integration/capabilities to verify supportsItemSync before calling.

​
Item Upsert

​
Validate a Single Item (Dry Run)

POST /api/v1/integration/items/validate Validates the item payload without persisting any data. Use this endpoint in a pre-flight check to confirm the payload is acceptable before calling the live upsert. Request body — IntegrationItemValidateDto
​
itemNo
string
required
ERP item code. Used as the upsert key. Must be non-empty and unique per tenant.
​
description
string
Human-readable item name.
​
uom
string
required
Primary unit of measure (e.g. EA, BOX, KG).
​
baseUOM
string
required
Base unit of measure used for stock calculations.
​
salesUOM
string
Unit of measure used in sales documents.
​
purchaseUOM
string
Unit of measure used in purchase documents.
​
itemType
string
required
Item classification (e.g. PRODUCT, SERVICE).
​
barcode
string
Primary barcode for the item.
​
altBarcode
string
Alternate barcode (secondary scan code).
​
isLotTracked
boolean
Whether the item requires lot tracking.
​
isSerialTracked
boolean
Whether the item requires serial number tracking.
​
isExpirationTracked
boolean
Whether the item tracks expiration dates.
​
unitWeight
number
Weight per unit.
​
unitVolume
number
Volume per unit.
​
length
number
Physical length dimension.
​
width
number
Physical width dimension.
​
height
number
Physical height dimension.
​
categoryCode
string
Item category code.
​
brand
string
Brand name.
​
partNo
string
Manufacturer part number.
​
alternativeCode
string
Alternate item code (also referred to as alternateItemNo in bulk payloads).
​
isActive
boolean
Whether the item is active. Defaults to true.
​
allowNegativeAvailable
boolean
Whether negative available stock is permitted for this item.
​
initialQuantity
number
Blocked. Passing a non-zero value here is rejected. Use the dedicated /stock/opening endpoint to seed initial stock.
​
locationCode
string
Default location code for the item.
​
binCode
string
Default bin code for the item.
Validation response 
{
  "success": true,
  "companyCode": "ACME",
  "message": "Payload valido.",
  "correlationId": "trace-id-001",
  "errors": []
}

​
Upsert a Single Item

POST /api/v1/integration/items Creates or updates a single item. The request body is the same IntegrationItemValidateDto schema described above. Example request 
curl -X POST https://api.dragonguard.io/api/v1/integration/items \
  -H "X-Api-Key: YOUR_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "itemNo": "SKU-100",
    "description": "Caja de cartón 50x40x30",
    "uom": "EA",
    "baseUOM": "EA",
    "itemType": "PRODUCT",
    "isActive": true,
    "allowNegativeAvailable": false
  }'
Example response 
{
  "success": true,
  "companyCode": "ACME",
  "message": "Item actualizado.",
  "correlationId": "trace-id-001",
  "item": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "itemNo": "SKU-100",
    "description": "Caja de cartón 50x40x30",
    "uOM": "EA",
    "baseUOM": "EA",
    "itemType": "PRODUCT",
    "isActive": true,
    "action": "UPDATED"
  },
  "errors": []
}
​
item.action
string
CREATED when the item did not exist before this call; UPDATED when it was already present.

​
Bulk Item Upsert

​
Validate a Bulk Payload (Dry Run)

POST /api/v1/integration/items/bulk/validate Validates an entire batch payload without persisting data. Returns per-line results with an Action of CREATED or UPDATED based on whether each itemNo already exists in Dragon Guard.

​
Upsert a Batch of Items

POST /api/v1/integration/items/bulk Upserts up to 1 000 items in a single request. Request body — IntegrationBulkItemUpsertDto
​
batchReferenceNo
string
Caller-assigned batch reference identifier. Used for traceability and idempotency auditing on your side.
​
remarks
string
Optional free-text notes for the batch operation.
​
items
array
required
Array of item payloads. Each element uses the same IntegrationItemValidateDto schema as single-item upsert. Maximum 1 000 elements per request.
Limits and rules
  • Maximum 1 000 items per batch request. Larger payloads are rejected.
  • Duplicate itemNo values within the same batch payload are rejected with a validation error.
  • initialQuantity is blocked at the catalog sync layer — pass it as 0 or omit it. Use /stock/opening to seed stock separately.
Example request 
curl -X POST https://api.dragonguard.io/api/v1/integration/items/bulk \
  -H "X-Api-Key: YOUR_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batchReferenceNo": "BATCH-2026-001",
    "remarks": "Initial catalog load from ERP",
    "items": [
      {
        "itemNo": "SKU-100",
        "description": "Producto A",
        "uom": "EA",
        "baseUOM": "EA",
        "itemType": "PRODUCT",
        "isActive": true
      },
      {
        "itemNo": "SKU-101",
        "description": "Producto B",
        "uom": "KG",
        "baseUOM": "KG",
        "itemType": "PRODUCT",
        "isActive": true
      }
    ]
  }'
Example response 
{
  "success": true,
  "companyCode": "ACME",
  "message": "Payload bulk valido.",
  "correlationId": "trace-id-002",
  "batch": {
    "batchReferenceNo": "BATCH-2026-001",
    "totalItems": 2,
    "createdCount": 1,
    "updatedCount": 1,
    "errorCount": 0
  },
  "items": [
    { "index": 0, "itemNo": "SKU-100", "action": "UPDATED", "success": true },
    { "index": 1, "itemNo": "SKU-101", "action": "CREATED", "success": true }
  ],
  "errors": []
}
​
batch.totalItems
integer
Count of items in the submitted payload.
​
batch.createdCount
integer
Items that did not previously exist and were inserted.
​
batch.updatedCount
integer
Items that already existed and were updated.
​
batch.errorCount
integer
Items that failed validation. Errors are listed in the top-level errors array with field paths like items[2].itemNo.

​
Opening Stock

​
Validate Opening Stock (Dry Run)

POST /api/v1/integration/stock/opening/validate Validates the opening stock payload without applying any stock movements.

​
Apply Opening Stock

POST /api/v1/integration/stock/opening Posts the initial stock balance for a tenant. Opening stock is applied as an idempotent operation — sending the same referenceNo with the same payload a second time returns the existing result without creating duplicate movements. Request body — IntegrationStockOpeningValidateDto
​
referenceNo
string
Caller-assigned reference number for this opening stock posting. Used for idempotency.
​
postingDate
string
ISO 8601 date for the opening stock entries.
​
remarks
string
Optional notes for this posting.
​
lines
array
required
Stock lines to apply.
​
lines[].itemNo
string
required
Item code. Must already exist in Dragon Guard’s item master.
​
lines[].locationCode
string
required
Warehouse location code.
​
lines[].binCode
string
required
Bin code within the location.
​
lines[].quantity
number
required
Opening stock quantity.
​
lines[].uom
string
Unit of measure. Falls back to the item’s base UOM if omitted.
​
lines[].movementType
string
Optional movement type classification for the stock entry.
Example request 
curl -X POST https://api.dragonguard.io/api/v1/integration/stock/opening \
  -H "X-Api-Key: YOUR_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceNo": "OPEN-2026-001",
    "postingDate": "2026-01-01",
    "lines": [
      {
        "itemNo": "SKU-100",
        "locationCode": "MAIN",
        "binCode": "A-01",
        "quantity": 250,
        "uom": "EA"
      }
    ]
  }'
Example response 
{
  "success": true,
  "companyCode": "ACME",
  "message": "Stock inicial aplicado.",
  "correlationId": "trace-id-003",
  "document": {
    "referenceNo": "OPEN-2026-001",
    "status": "APPLIED",
    "postingDate": "2026-01-01T00:00:00Z",
    "idempotent": false,
    "linesProcessed": 1,
    "totalQuantity": 250.0
  },
  "errors": []
}
​
document.idempotent
boolean
true when the same referenceNo was already applied previously and this call returned the cached result without re-processing.
Always call /stock/opening/validate before /stock/opening when integrating for the first time. The validate endpoint surfaces item-not-found, location-not-found, and UOM mismatch errors without consuming the idempotency slot.

​
On-Demand Catalog Sync Trigger

For tenants using the GrupoMAS Native connector, Dragon Guard can pull a one-shot item catalog refresh directly from Grupo Mas ERP rather than waiting for a scheduled poll. This endpoint is served on a separate route from the push-based integration endpoints above and uses standard JWT authentication (not X-Api-Key). POST /api/items/catalog-sync Triggers an immediate catalog sync for the authenticated user’s company. Safe to call as a fire-and-forget from a mobile client at login time. Returns 400 Bad Request when the company is not configured for GrupoMAS Native catalog sync. 
curl -X POST https://api.dragonguard.io/api/items/catalog-sync \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Endpoint Summary

MethodPathDescription
POST/api/v1/integration/items/validateDry-run validate single item
POST/api/v1/integration/itemsUpsert single item
POST/api/v1/integration/items/bulk/validateDry-run validate bulk items
POST/api/v1/integration/items/bulkUpsert batch of items (max 1 000)
POST/api/v1/integration/stock/opening/validateDry-run validate opening stock
POST/api/v1/integration/stock/openingApply opening stock
POST/api/items/catalog-syncTrigger one-shot GrupoMAS catalog pull (JWT auth)

Build docs developers (and LLMs) love

Get started for freeTalk to us