Warehouse Receiving: Headers, Lines, and Posting in Dragon Guard

Dragon Guard models inbound warehouse activity as a two-stage workflow. First, a Receiving Header document is created (optionally from a purchase order) and its Receiving Lines are populated with expected items and quantities. Second, the operator confirms received quantities — typically from a handheld device — and a supervisor or operator triggers the Post action to commit inventory movements and optionally notify an ERP through an outbound acknowledgment. All receiving endpoints are company-scoped: CompanyId is resolved from the bearer token and enforced on every query and mutation.

Status Lifecycle

A receiving header moves through the following statuses:

OPEN  ──►  RELEASED  ──►  RECEIVING  ──►  CLOSED (fully posted)
                │                              │
                └──────────── CANCELLED ◄──────┘

Status	Meaning
`OPEN`	Draft, not yet visible to handheld operators.
`RELEASED`	Visible to handheld operators for execution.
`RECEIVING`	Posting has started but remaining lines are still open.
`CLOSED`	All lines fully posted.

The additive documentStatus and processingStatus fields on list/detail responses expose a client-friendly representation without removing the raw status value.

Receiving Headers

List receipt headers

GET /api/receivingheaders

string

Free-text match on receiptNo, vendorName, externalDocumentNo, or status.

status

string

Filter by normalized status: OPEN, RELEASED, RECEIVING, CLOSED, CANCELLED.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page.

Handheld / OPERATOR tokens only see RELEASED and RECEIVING headers. ADMIN and SUPERVISOR tokens see all statuses.

Response PagedResponse<ReceivingHeaderDto>

data[].id

uuid

Header UUID.

data[].receiptNo

string

Auto-generated receipt number (format RCP-NNNNNNN).

data[].purchaseOrderNo

string

Associated purchase order number.

data[].externalDocumentNo

string

ERP-side document number.

data[].vendorCode

string

Vendor code.

data[].vendorName

string

Vendor display name.

data[].locationCode

string

Receiving warehouse location code.

data[].referenceNo

string

Internal reference number.

data[].status

string

Raw status value.

data[].documentStatus

string

Client-friendly status: Open, Released, Closed, Cancelled.

data[].processingStatus

string

Pending, PartiallyReceived, or Posted.

data[].receiptDate

datetime

Receipt date.

data[].createdAt

datetime

Creation timestamp.

data[].createdBy

string

User who created the header.

Get receipt header detail

GET /api/receivingheaders/{id}

Returns the full ReceivingHeaderDetailDto including all lines, per-line postedQuantityReceived and remainingQuantity computed from PostedReceivingLines, the isHandheldInUse flag, and the activeOperatorEmail of any handheld operator currently working on the document.

Create a receipt header

POST /api/receivingheaders

Request body (CreateReceivingHeaderDto)

purchaseOrderNo

string

PO number. Auto-generated from sequence if omitted (format PO-NNNNNN).

externalDocumentNo

string

ERP reference number.

vendorCode

string

Vendor code.

vendorName

string

Vendor name.

receiptDate

datetime

Date of receipt. Defaults to UTC now.

locationCode

string

Receiving location code. Resolved from tenant default when omitted.

referenceNo

string

Internal reference number.

remarks

string

Free-text remarks.

status

string

Initial status: OPEN (hidden from handheld) or RELEASED (visible to handheld). Defaults to OPEN.

lines

array

required

At least one receiving line is required.

lines[].itemId

uuid

required

Item to receive.

lines[].quantityExpected

decimal

required

Expected quantity (must be > 0).

lines[].uom

string

required

Unit of measure.

lines[].binId

uuid

Target putaway bin. Falls back to tenant default bin.

Response

{ "headerId": "...", "receiptNo": "RCP-0000001" }

Update a receipt header

PUT /api/receivingheaders/{id}

Permitted while the document is in OPEN or RELEASED status. Accepts the same body shape as create. Lines with posted history cannot be removed and their quantityExpected cannot be reduced below the already-posted quantity. The endpoint acquires a per-receipt SQL application lock to prevent concurrent edits.

Reopening RELEASED → OPEN is blocked when a handheld operator has already entered quantities (quantityReceived > 0 on any line). The response includes the activeOperatorEmail so the web UI can prompt the supervisor to coordinate with the operator before reopening.

Receiving Lines

List receiving lines

GET /api/receivinglines

receivingHeaderId

uuid

Filter lines to a specific receipt.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page.

Returns PagedResponse<ReceivingLineDto> with postedQuantityReceived and remainingQuantity computed from PostedReceivingLines.

Get receiving line detail

GET /api/receivinglines/{id}/detail

Returns full ReceivingLineDetailDto for a single line, including receiptNo, itemCode, itemDescription, binCode, and computed postedQuantityReceived and remainingQuantity.

Get lines by header

GET /api/receivinglines/by-header/{headerId}

Convenience endpoint for handheld detail loading. For GrupoMASNative tenants where the header was sourced from MAS, lines are read from the MAS released receipt payload directly.

pageNumber

integer

default:"1"

Page number.

pageSize

integer

default:"20"

Records per page.

Update a receiving line

PUT /api/receivinglines/{id}

The primary handheld write endpoint. Updates the draft quantityReceived before posting.

quantityReceived

decimal

required

Quantity scanned/counted by the operator. Must be ≥ 0.

binId

uuid

Override the putaway bin. Must be active, not blocked, and allow putaway.

Rules enforced:

alreadyPosted + quantityReceived cannot exceed quantityExpected.
Line status is updated to OPEN, PARTIAL, or CLOSED based on total processed quantity.
A per-receipt SQL application lock is acquired to prevent concurrent writes.

Post a Receipt

Operators scan quantities

Handheld operators use PUT /api/receivinglines/{id} to record quantityReceived for each line and optionally assign a putaway bin.

Supervisor posts the receipt

A supervisor or operator calls POST /api/receivingheaders/{id}/post to commit the inventory.

Inventory and history created

Dragon Guard creates a PostedReceivingHeader, one PostedReceivingLine per processed line, and one InventoryMovements record per line with movementType = "IN".

ERP notified (when configured)

An OutboundAcknowledgment entry is queued and dispatched to the tenant CallbackUrl. Callback failure never blocks the post.

POST /api/receivingheaders/{id}/post

Roles ADMIN, SUPERVISOR, and OPERATOR may post receipts.

Validations enforced at post time:

Receipt must not already be fully posted.
Every posted line must have a valid binId.
alreadyPosted + quantityReceived cannot exceed quantityExpected (over-receiving requires vendor-level allowOverReceipt flag).
RFID evidence check runs when RFID enforcement is configured for RECEIPTS.
The company must have a non-empty code (required for ERP outbound payload).

Response

{
  "message": "Recibo registrado correctamente.",
  "postedReceiveNo": "PR-000001",
  "outboundAcknowledgmentId": "...",
  "outboundAcknowledgmentStatus": "QUEUED"
}

Partial posting is supported: after posting, header status moves to RECEIVING if any lines remain, or CLOSED if all lines are fulfilled. Subsequent posts on the same receipt append more PostedReceivingLines to the same history.

Posted Receiving History

List posted headers

GET /api/posted-receiving-headers

Paginated list of all posted receipt headers for the active company. Supports ?search= to filter by postedReceivingNo, receiptNo, vendorCode, or vendorName.

Get posted header detail

GET /api/posted-receiving-headers/{id}

Full detail of a single posted receipt header.

By original receipt

GET /api/posted-receiving-headers/by-receiving/{receivingHeaderId}

Find all posted receipts created from a specific source receipt.

Posted lines

GET /api/posted-receiving-lines
GET /api/posted-receiving-lines/{id}
GET /api/posted-receiving-lines/by-header/{postedHeaderId}

Access individual posted receipt line records.

Receipt Configuration Packages

Dragon Guard supports Excel-based bulk operations for receipts and receipt lines.

Export receipts

GET /api/receivingheaders/export-config

Downloads receipts_config_package.xlsx.

Preview receipts

POST /api/receivingheaders/preview-config
Content-Type: multipart/form-data

Returns CREATE/UPDATE preview and validation errors.

Apply receipts

POST /api/receivingheaders/apply-config
Content-Type: multipart/form-data

Applies the validated receipt package.

Receipt header package columns: ReceiptNo, Status, LocationCode, PurchaseOrderNo, ReceiptDate, VendorName, ExternalDocumentNo, ReferenceNo, Remarks.

Export lines

GET /api/receivinglines/export-config

Preview lines

POST /api/receivinglines/preview-config
Content-Type: multipart/form-data

Apply lines

POST /api/receivinglines/apply-config
Content-Type: multipart/form-data

Receipt line package columns: ReceiptNo, LineNo, ItemNo, SourcePurchaseOrderNo, QuantityExpected, QuantityReceived, UOM.

Purchase Orders Integration

GET /api/purchase-orders

Returns purchase order headers for the active tenant. Supports ?search= (matches purchaseOrderNo, vendorName, externalDocumentNo) and ?status= filtering. Purchase orders can be linked to receipt headers via purchaseOrderId / purchaseOrderNo to enable automatic PO progress tracking (quantities received, outstanding, and status OPEN → PARTIALLY RECEIVED → RECEIVED).

ERP Outbound Acknowledgment Flow

When a GrupoMASNative (or other integrated) tenant has a CallbackUrl configured, Dragon Guard queues an outbound acknowledgment after every successful post:

Queue: An OutboundAcknowledgment record is persisted within the posting transaction.
Dispatch: After the transaction commits, Dragon Guard attempts a best-effort POST to the CallbackUrl with the posted receipt payload.
Non-blocking: A callback failure logs a warning but does not roll back or retry the inventory post.
Polling fallback: Integrations that poll GET /api/outbound-acknowledgments remain fully compatible.

The outbound acknowledgment includes postedReceivingNo, vendor, receipt date, and line-level quantities so the ERP can update its own goods-receipt records without re-querying Dragon Guard.

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Warehouse Receiving: Headers, Lines, and Posting in Dragon Guard

Status Lifecycle

Receiving Headers

List receipt headers

Get receipt header detail

Create a receipt header

Update a receipt header

Receiving Lines

List receiving lines

Get receiving line detail

Get lines by header

Update a receiving line

Post a Receipt

Posted Receiving History

List posted headers

Get posted header detail

By original receipt

Posted lines

Receipt Configuration Packages

Export receipts

Preview receipts

Apply receipts

Export lines

Preview lines

Apply lines

Purchase Orders Integration

ERP Outbound Acknowledgment Flow

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Status Lifecycle

​Receiving Headers

​List receipt headers

​Get receipt header detail

​Create a receipt header

​Update a receipt header

​Receiving Lines

​List receiving lines

​Get receiving line detail

​Get lines by header

​Update a receiving line

​Post a Receipt

​Posted Receiving History

List posted headers

Get posted header detail

By original receipt

Posted lines

​Receipt Configuration Packages

Export receipts

Preview receipts

Apply receipts

Export lines

Preview lines

Apply lines

​Purchase Orders Integration

​ERP Outbound Acknowledgment Flow

Build docs developers (and LLMs) love

Status Lifecycle

Receiving Headers

List receipt headers

Get receipt header detail

Create a receipt header

Update a receipt header

Receiving Lines

List receiving lines

Get receiving line detail

Get lines by header

Update a receiving line

Post a Receipt

Posted Receiving History

Receipt Configuration Packages

Purchase Orders Integration

ERP Outbound Acknowledgment Flow