RFID Scan Events: Audit Trail for Tag Reads and Operations

Every RFID tag read that matters is recorded as an RfidScanEvent. Events are immutable, tenant-scoped, and designed to serve as the RFID evidence layer — the ERP never needs to know an EPC was involved. A single table covers all four warehouse modules (Items, Receipts, Shipments, Movements), and each record captures everything needed for audit, troubleshooting, and analytics: the raw and normalised EPC, the module, the document reference, the resolution outcome, the validation outcome, the operator, the device, and the timestamp of the physical read.

Submit a scan event

POST /api/rfid/events

Called by the handheld application each time a tag read should be persisted. Returns 201 Created with the saved RfidScanEventDto including the system-assigned id and any resolved item linkage.

Request fields (`CreateRfidScanEventDto`)

captureMode

string

required

How the read was triggered. Typical values: RFID_SCAN, BARCODE_SCAN, MANUAL_ENTRY.

module

string

required

The warehouse module context for this read: Items, Receipts, Shipments, or Movements.

eventType

string

required

Type of event being recorded. Examples: TAG_READ, TAG_VALIDATED, TAG_REJECTED, TAG_NOT_FOUND.

rawEpc

string

required

The EPC string exactly as read from the antenna or decoder.

normalizedEpc

string

The canonicalised EPC used for registry lookup. If omitted, the service derives it from rawEpc.

handheldDeviceId

guid

ID of the HandheldDevice record that performed the read.

rfidTagRegistryId

guid

ID of the RfidTagRegistry row that was resolved for this EPC, if known at submission time.

rfidTagAssignmentId

guid

ID of the active tag assignment, if the read was tied to a specific document assignment.

resolutionStatus

string

Outcome of EPC-to-item resolution. Examples: RESOLVED, NOT_FOUND, AMBIGUOUS_DUPLICATE, INACTIVE.

validationStatus

string

Outcome of the operational validation check. Examples: VALID, INVALID, SKIPPED, MISMATCH.

itemId

guid

ID of the resolved item, if EPC resolution succeeded.

itemNoSnapshot

string

Item number captured at the time of the read (for historical accuracy if item data changes).

documentType

string

Type of the warehouse document being operated (e.g. RECEIPT, SHIPMENT, MOVEMENT).

documentNo

string

Document number being processed when the read occurred.

documentLineNo

string

Line number within the document, when the read is tied to a specific line.

locationCodeSnapshot

string

Location code at the moment of the read.

binCodeSnapshot

string

Bin code at the moment of the read.

quantity

decimal

Quantity associated with this read (e.g. units on the scanned pallet).

triggerSource

string

What initiated the read. Examples: OPERATOR_TRIGGER, AUTO_SCAN, API_CALL.

deviceKeySnapshot

string

Device key captured at the time of the read.

operatorEmail

string

E-mail address of the operator who performed the scan.

correlationId

string

A client-supplied ID to group multiple related reads (e.g. all scans within one receiving session).

sessionId

string

A client-supplied session identifier for the handheld application session.

resolutionSource

string

How the tag was resolved (e.g. TAG_REGISTRY, TAG_ASSIGNMENT).

effectiveMode

string

The RFID operating mode that was active at the time of this read (Disabled, InquiryOnly, OperationalAssist, StrictValidation).

validationRule

string

The specific validation rule that was applied, if any.

scannedAtUtc

datetime

UTC timestamp of the physical read on the device. If omitted, the server records the time of receipt.

errorMessage

string

Error detail when the read could not be resolved or validated.

metadataJson

string

Optional freeform JSON payload for SDK-specific metadata (signal strength, antenna index, reader firmware, etc.).

Example

curl -X POST https://api.dragonguard.io/api/rfid/events \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "captureMode": "RFID_SCAN",
    "module": "Receipts",
    "eventType": "TAG_VALIDATED",
    "rawEpc": "3034257BF400B80000000001",
    "normalizedEpc": "3034257BF400B80000000001",
    "handheldDeviceId": "b1c2d3e4-0000-0000-0000-000000000001",
    "resolutionStatus": "RESOLVED",
    "validationStatus": "VALID",
    "itemId": "a1b2c3d4-0000-0000-0000-000000000001",
    "itemNoSnapshot": "ITEM-001",
    "documentType": "RECEIPT",
    "documentNo": "RCT-2025-00042",
    "documentLineNo": "1",
    "locationCodeSnapshot": "DOCK-A",
    "quantity": 1,
    "operatorEmail": "[email protected]",
    "correlationId": "session-abc-001",
    "effectiveMode": "StrictValidation",
    "scannedAtUtc": "2025-01-15T10:30:00Z"
  }'

{
  "id": "eeee1111-0000-0000-0000-000000000042",
  "captureMode": "RFID_SCAN",
  "module": "Receipts",
  "eventType": "TAG_VALIDATED",
  "rawEpc": "3034257BF400B80000000001",
  "normalizedEpc": "3034257BF400B80000000001",
  "resolutionStatus": "RESOLVED",
  "validationStatus": "VALID",
  "itemId": "a1b2c3d4-0000-0000-0000-000000000001",
  "itemNoSnapshot": "ITEM-001",
  "documentType": "RECEIPT",
  "documentNo": "RCT-2025-00042",
  "documentLineNo": "1",
  "locationCodeSnapshot": "DOCK-A",
  "quantity": 1.0,
  "operatorEmail": "[email protected]",
  "correlationId": "session-abc-001",
  "effectiveMode": "StrictValidation",
  "scannedAtUtc": "2025-01-15T10:30:00Z",
  "createdAtUtc": "2025-01-15T10:30:01Z",
  "createdBy": "[email protected]"
}

Query scan events

Tenant view

GET /api/rfid/events

Returns a paged list of RfidScanEventDto records scoped to the calling tenant.

Query parameter	Type	Description
`module`	`string`	Filter by warehouse module
`resolutionStatus`	`string`	Filter by resolution outcome (`RESOLVED`, `NOT_FOUND`, etc.)
`validationStatus`	`string`	Filter by validation outcome (`VALID`, `INVALID`, etc.)
`search`	`string`	Free-text search across EPC, item number, and document number
`documentType`	`string`	Filter by document type
`documentNo`	`string`	Filter by exact document number
`correlationId`	`string`	Filter by client correlation ID
`sessionId`	`string`	Filter by client session ID
`fromUtc`	`datetime`	Start of time window (inclusive)
`toUtc`	`datetime`	End of time window (inclusive)
`errorsOnly`	`bool`	When `true`, returns only events that have a non-null `errorMessage`
`page`	`int`	Page number (1-based)
`pageSize`	`int`	Records per page

Export to Excel

GET /api/rfid/events/export

Accepts the same query parameters as the list endpoint and returns an .xlsx file containing all matching events. Useful for compliance reporting and offline analysis. The response has Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet and a filename of the form rfid_scan_events_YYYYMMDD_HHmmss.xlsx.

Admin view (Supreme)

GET /api/supreme/companies/{id}/integration/rfid-events

Provides a super-admin view of scan events for a specific tenant. Supports the same query parameters as the tenant endpoint.

Document scan commit

Before the handheld posts individual RfidScanEvent rows, it can commit a batch of scans atomically against a specific document. This endpoint is designed for receiving and shipment workflows where all tag reads for a document are collected in a session and committed together.

Commit document scans

POST /api/rfid/scans/commit

Commits up to 500 scans for a single document in one request.

documentType

string

required

Type of the document being operated (e.g. RECEIPT, SHIPMENT).

documentNo

string

required

Document number being processed.

module

string

required

Warehouse module context: Items, Receipts, Shipments, or Movements.

sessionId

string

Client session identifier to link these scans to a handheld session.

correlationId

string

Client correlation ID for grouping related commit calls.

scans

array

required

Array of scan items. Each element (RfidDocumentScanItemDto) supports:

Field	Type	Description
`rawEpc`	`string?`	Raw EPC as read from the antenna
`normalizedEpc`	`string?`	Canonical EPC
`documentLineNo`	`string?`	Line number within the document
`itemId`	`guid?`	Expected item ID
`itemNo`	`string?`	Expected item number
`quantity`	`decimal?`	Quantity for this scan
`deviceKeySnapshot`	`string?`	Device key at the time of the read
`handheldDeviceId`	`guid?`	ID of the reading device

Response (RfidDocumentScanCommitResultDto):

Field	Type	Description
`documentType`	`string`	Document type that was processed
`documentNo`	`string`	Document number that was processed
`totalScans`	`int`	Total number of scans submitted
`committedCount`	`int`	Number of scans successfully committed
`skippedCount`	`int`	Number of scans skipped (e.g. duplicates)
`lines`	`array`	Per-scan result (`RfidDocumentScanCommitLineDto`) with `index`, `normalizedEpc`, `committed`, and `message`

Get document evidence

GET /api/rfid/scans/evidence

Returns a summary of committed RFID evidence for a specific document. Used by the handheld to check whether the evidence requirement has been satisfied before posting the document.

Query parameter	Required	Description
`documentType`	✓	Document type
`documentNo`	✓	Document number
`module`	✓	Warehouse module

Response (RfidDocumentEvidenceDto):

Field	Type	Description
`documentType`	`string`	Document type
`documentNo`	`string`	Document number
`requiresEvidence`	`bool`	Whether the active policy requires RFID evidence for this document
`evidenceSatisfied`	`bool`	Whether the evidence requirement has been met
`committedScanCount`	`int`	Total number of committed scans on file for this document
`committedEpcs`	`array`	List of EPC strings that have been committed

Operational validation (pre-flight)

Before committing a warehouse operation — for example, confirming a receipt line or completing a shipment pick — the handheld can ask Dragon Guard to validate a single EPC against the expected operational context.

Single EPC validation

POST /api/rfid/validate-operation

module

string

required

Warehouse module context: Items, Receipts, Shipments, or Movements.

rawEpc

string

The raw EPC as read from the antenna.

normalizedEpc

string

The canonicalised EPC. At least one of rawEpc or normalizedEpc must be provided.

documentType

string

Type of the warehouse document being validated against.

documentNo

string

Document number being processed.

documentLineNo

string

Line number within the document.

itemId

guid

Expected item ID — used to check whether the scanned EPC matches the expected item.

itemNo

string

Expected item number (alternative to itemId).

expectedLocationCode

string

Location code where the operation is expected to take place.

expectedBinCode

string

Bin code within the location.

expectedQuantity

decimal

Quantity expected for this tag read.

handheldDeviceId

guid

ID of the reading device.

deviceKeySnapshot

string

Device key at the time of the read.

operatorEmail

string

E-mail of the operator submitting the validation.

correlationId

string

Client correlation ID to link this validation to a session or batch.

sessionId

string

Client session identifier.

effectiveMode

string

Operating mode the handheld is currently running under (used for policy resolution).

validationRule

string

Specific validation rule to apply, if overriding the policy default.

triggerSource

string

What triggered the validation request.

metadataJson

string

Optional SDK metadata JSON.

Response (`RfidOperationalValidationResultDto`)

success

bool

Whether the validation call itself succeeded (not the same as isValid).

isResolved

bool

Whether the EPC was found in the RfidTagRegistry.

isValid

bool

Whether the resolved tag matches all expected operational attributes (item, location, quantity).

shouldBlock

bool

Whether the active policy requires blocking the operation based on this result.

allowManualFallback

bool

Whether the active policy permits manual fallback after this validation outcome.

allowBarcodeFallback

bool

Whether the active policy permits barcode fallback after this validation outcome.

module

string

The module that was evaluated.

effectiveMode

string

The operating mode that was applied.

resolutionStatus

string

EPC resolution outcome (RESOLVED, NOT_FOUND, AMBIGUOUS_DUPLICATE, INACTIVE).

validationStatus

string

Validation outcome (VALID, INVALID, SKIPPED, MISMATCH).

resolutionSource

string

How the tag was resolved (TAG_REGISTRY, TAG_ASSIGNMENT, etc.).

validationRule

string?

The specific rule that produced the validation outcome.

message

string?

Human-readable explanation of the outcome.

correlationId

string?

Echo of the client-supplied correlation ID.

resolvedTag

RfidTagResolveDto?

Full resolved tag context when isResolved = true.

Batch validation

POST /api/rfid/validate-batch

Validates up to 100 EPCs in a single request. The request body contains an items array where each element is an RfidOperationalValidationRequestDto. Batch size is validated server-side; submitting more than 100 items returns 400 Bad Request.

{
  "items": [
    {
      "module": "Shipments",
      "normalizedEpc": "3034257BF400B80000000001",
      "documentNo": "SHP-2025-00010",
      "itemNo": "ITEM-001"
    },
    {
      "module": "Shipments",
      "normalizedEpc": "3034257BF400B80000000002",
      "documentNo": "SHP-2025-00010",
      "itemNo": "ITEM-002"
    }
  ]
}

Response summary fields (RfidValidateBatchResultDto):

totalCount

int

Number of items submitted.

validCount

int

Number of items where isValid = true.

invalidCount

int

Number of items where isValid = false.

blockedCount

int

Number of items where the policy requires blocking the operation.

anyBlocked

bool

true if at least one item in the batch has shouldBlock = true. The handheld should halt the operation if this flag is set and the module is in StrictValidation mode.

results

array

Per-item array of RfidValidateBatchLineResultDto, each containing index, normalizedEpc, and a full RfidOperationalValidationResultDto.

Audit field coverage

Every RfidTagRegistry row and every RfidScanEvent record carries a complete audit trail:

Field	Present on	Description
`createdAtUtc`	Tags, Events	UTC timestamp of record creation
`createdBy`	Tags, Events	E-mail of the operator or system that created the record
`updatedAtUtc`	Tags	UTC timestamp of the last update
`updatedBy`	Tags	E-mail of the operator or system that performed the update

Use correlationId and sessionId when submitting scan events and validation requests from the handheld. These fields make it easy to reconstruct every scan that occurred during a single receiving or picking session when querying the audit trail later.

Tag batch orders (Supreme)

For tenants that need physical ZPL labels printed before commissioning tags in the registry, Supreme provides a tag batch ordering workflow.

Method	Endpoint	Description
`GET`	`/api/supreme/companies/{companyId}/rfid/tag-batches`	List tag batch orders for the tenant
`POST`	`/api/supreme/companies/{companyId}/rfid/tag-batches`	Request a new batch of physical RFID tags to be printed
`PATCH`	`/api/supreme/companies/{companyId}/rfid/tag-batches/{orderId}/fulfill`	Mark a pending batch order as fulfilled (completed)

Batch statuses:

Status	Meaning
`PENDING`	Batch has been requested and is awaiting processing
`PROCESSING`	EPCs are being generated or labels are being prepared
`COMPLETED`	All EPCs have been issued and ZPL strings are available
`CANCELLED`	Batch was cancelled before completion

Immediate EPC issuance

POST /api/supreme/companies/{companyId}/rfid/tag-batch

The singular tag-batch endpoint (as opposed to tag-batches) generates EPCs immediately and returns ZPL label strings suitable for direct submission to a Zebra label printer. Use this for on-demand commissioning at the point of packing or receiving. Tags are pre-registered in the registry with status = AVAILABLE and the response includes ZPL strings with ^RFW commands so the RFID chip is programmed during the print pass (TCP port 9100). Request body (RfidTagIssuanceRequestDto):

Field	Type	Description
`batchReference`	`string?`	Optional reference label for this issuance
`remarks`	`string?`	Free-text notes
`lines`	`array`	Array of `RfidTagIssuanceLineDto` items (see below)

Each line (RfidTagIssuanceLineDto):

Field	Type	Description
`itemId`	`guid?`	Item to associate with the generated tags
`itemNo`	`string?`	Item number (resolved within the tenant if `itemId` is null)
`objectType`	`string`	Tag object type. Default `ITEM_UNIT`. One of `ITEM_UNIT`, `CASE`, `PACK`, `PALLET`, `BIN`, `LOCATION`, `ASSET`
`quantityPerTag`	`decimal`	Quantity each tag represents. Default `1`
`tagCount`	`int`	Number of tags to generate for this line (1–200)

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

RFID Scan Events: Audit Trail for Tag Reads and Operations

Submit a scan event

Request fields (`CreateRfidScanEventDto`)

Example

Query scan events

Tenant view

Export to Excel

Admin view (Supreme)

Document scan commit

Commit document scans

Get document evidence

Operational validation (pre-flight)

Single EPC validation

Response (`RfidOperationalValidationResultDto`)

Batch validation

Audit field coverage

Tag batch orders (Supreme)

Immediate EPC issuance

Build docs developers (and LLMs) love

Get Started

Authentication

Core Modules

RFID

ERP Integration

Supreme Admin

Platform

Documentation Index

​Submit a scan event

​Request fields (CreateRfidScanEventDto)

​Example

​Query scan events

​Tenant view

​Export to Excel

​Admin view (Supreme)

​Document scan commit

​Commit document scans

​Get document evidence

​Operational validation (pre-flight)

​Single EPC validation

​Response (RfidOperationalValidationResultDto)

​Batch validation

​Audit field coverage

​Tag batch orders (Supreme)

​Immediate EPC issuance

Build docs developers (and LLMs) love

Submit a scan event

Request fields (`CreateRfidScanEventDto`)

Example

Query scan events

Tenant view

Export to Excel

Admin view (Supreme)

Document scan commit

Commit document scans

Get document evidence

Operational validation (pre-flight)

Single EPC validation

Response (`RfidOperationalValidationResultDto`)

Batch validation

Audit field coverage

Tag batch orders (Supreme)

Immediate EPC issuance