Transaction Lifecycle Endpoints for GSM Operations

Transactions are the core operational record in the GSM Operations service. Each transaction is identified by a TrxPrefix that encodes the business context — for example, PRDLBR indicates a productivity-labor transaction. A transaction progresses through a defined lifecycle: it is initially CREATED, transitions to INPROGRESS when work begins, and is ultimately resolved as either COMPLETED or CANCELLED. State changes are recorded as entries in the TrxStates collection, providing a complete audit trail. Each transaction can carry arbitrary key/value attributes (TrxAttributes), associated product lines (TrxProducts), and typed detail lines (TrxDetails), making the structure flexible enough to represent diverse operational workflows without schema changes.

Create Transaction

Create a new transaction header with its initial state, attributes, products, and detail lines.

Endpoint

POST /api/operations/v1/operations/create-trx

Authentication

Authorization

string

required

Bearer token. Format: Bearer <token>

Request Body

trxPrefix

string

required

Business-type prefix that classifies the transaction. This value determines processing rules and reporting groupings. Example values: PRDLBR (productivity-labor), RCVHB (herb receipt), DSPHB (herb dispatch).

descr

string

Optional free-text description for the transaction.

username

string

required

Username of the operator creating the transaction. Used for audit trail purposes.

location

string

Optional physical location or site identifier where the transaction originates.

trxAttributes

array

Arbitrary key/value metadata attached to the transaction. Can be used to store custom attributes without modifying the schema.

Show TrxAttributesDTO (each item)

attributeKey

string

required

The attribute name or key.

attributeValue

string

required

The attribute value as a string.

trxProducts

array

Product lines included in the transaction.

Show TrxProductsDTO (each item)

idVariety

integer

required

Reference to the product variety (from master products catalog).

varietyName

string

Display name for the variety (denormalised for convenience).

sku

string

SKU code for the variety.

qty

number

Quantity of this variety involved in the transaction.

trxStates

object

required

The initial state record for the transaction.

Show TrxStatesDTO

trxState

string

required

The state value for this entry. Standard lifecycle states: CREATED, INPROGRESS, COMPLETED, CANCELLED.

comments

string

Optional comment accompanying the state change.

stateDate

string (ISO 8601)

Timestamp of the state. Defaults to the current UTC time if omitted.

trxDetails

array

required

Typed detail lines that carry the transaction’s operational data.

Show TrxDetailsDTO (each item)

detailType

string

required

The category or type of this detail line (e.g. "EMPLOYEE", "NOTE", "TASK").

detailValue

string

The value or payload for this detail line.

HTTP Status Codes

Code	Meaning
`200 OK`	Transaction created. `data` contains confirmation (typically the new `TrxDocument` identifier).
`400 Bad Request`	Required fields missing or validation failed.
`401 Unauthorized`	Token missing or invalid.

Example

curl --request POST \
  --url 'https://your-gateway.example.com/api/operations/v1/operations/create-trx' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "trxPrefix": "PRDLBR",
    "descr": "Morning harvest labor record",
    "username": "jsmith",
    "location": "Farm A - Block 3",
    "trxAttributes": [
      { "attributeKey": "SHIFT", "attributeValue": "MORNING" }
    ],
    "trxProducts": [
      { "idVariety": 10, "varietyName": "Lavender Fine", "sku": "LAV-001-F", "qty": 25.5 }
    ],
    "trxStates": {
      "trxState": "CREATED",
      "comments": "Initial record",
      "stateDate": "2024-06-01T07:00:00Z"
    },
    "trxDetails": [
      { "detailType": "EMPLOYEE", "detailValue": "EMP-042" },
      { "detailType": "NOTE", "detailValue": "Harvested from east quadrant." }
    ]
  }'

{
  "success": true,
  "message": "Transaction created successfully.",
  "data": "PRDLBR-20240601-0001",
  "errorType": null,
  "traceId": "00-3c4d5e6f7a8b9c01-01",
  "details": null
}

Update Transaction

Apply a partial update to an existing transaction. Only the collections provided in the body are updated; omitted collections remain unchanged.

Endpoint

PATCH /api/operations/v1/operations/{idTrxHeader}

Path Parameters

idTrxHeader

integer (long)

required

The numeric ID of the transaction header to update.

Request Body

trxAttributes

array

Updated or additional key/value attribute lines.

Show TrxAttributesDTO (each item)

attributeKey

string

required

Attribute key to set or update.

attributeValue

string

required

New attribute value.

trxProducts

array

Updated product lines.

Show TrxProductsDTO (each item)

idVariety

integer

required

Variety reference.

varietyName

string

Variety display name.

sku

string

SKU code.

qty

number

Updated quantity.

trxStates

object

New state entry to append to the transaction’s state history. Use this to advance the lifecycle (e.g. from INPROGRESS to COMPLETED).

Show TrxStatesDTO

trxState

string

required

New lifecycle state: INPROGRESS, COMPLETED, or CANCELLED.

comments

string

Optional comment for this state transition.

stateDate

string (ISO 8601)

Timestamp of the state change. Defaults to current UTC if omitted.

trxDetails

array

Updated or appended detail lines.

Show TrxDetailsDTO (each item)

detailType

string

required

Detail type identifier.

detailValue

string

Detail value payload.

HTTP Status Codes

Code	Meaning
`200 OK`	Transaction updated successfully.
`400 Bad Request`	Validation failed (e.g. invalid state transition).
`401 Unauthorized`	Token missing or invalid.
`404 Not Found`	No transaction found with the given `idTrxHeader`.

Example

curl --request PATCH \
  --url 'https://your-gateway.example.com/api/operations/v1/operations/1001' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "trxStates": {
      "trxState": "COMPLETED",
      "comments": "Harvest completed and verified.",
      "stateDate": "2024-06-01T14:30:00Z"
    }
  }'

Search Transactions

Search and retrieve transactions matching the specified filter criteria.

Endpoint

POST /api/operations/v1/operations/getTrx

Authentication

Authorization

string

required

Bearer token. Format: Bearer <token>

Request Body

trxPrefix

string

Filter by transaction type prefix (e.g. "PRDLBR"). Returns only transactions of this type.

status

string

Filter by current transaction status. Standard values: CREATED, INPROGRESS, COMPLETED, CANCELLED.

location

string

Filter by originating location.

Response

data

array

List of matching transaction records.

Show TrxResponseDTO (each item)

idTrxHeader

integer (long)

required

Unique numeric ID of the transaction header.

trxPrefix

string

required

Business-type prefix classifying the transaction.

trxDocument

string

required

Auto-generated document number (e.g. "PRDLBR-20240601-0001").

descr

string | null

Transaction description.

trxDate

string (ISO 8601)

required

Date and time the transaction was created.

status

string

required

Current lifecycle status of the transaction.

username

string

required

Username of the operator who created the transaction.

location

string | null

Location associated with the transaction.

trxAttributes

array

Key/value metadata lines attached to the transaction.

Show TrxResponseAttributeDTO (each item)

idTrxAttribute

integer (long)

required

Unique ID of the attribute record.

attributeKey

string

required

Attribute name.

attributeValue

string | null

Attribute value.

trxProducts

array

Product lines associated with the transaction.

Show TrxResponseProductDTO (each item)

idTrxProduct

integer (long)

required

Unique ID of the product line record.

idVariety

integer

required

Variety reference ID.

varietyName

string | null

Variety display name.

sku

string | null

SKU code.

qty

number | null

Quantity.

trxStates

array

Full state history for this transaction.

Show TrxResponseStateDTO (each item)

idTrxState

integer (long)

required

Unique ID of the state entry.

trxState

string | null

The state value at this point in the history.

stateDate

string (ISO 8601) | null

Timestamp when this state was recorded.

comments

string | null

Comment associated with this state transition.

trxDetails

array

Typed detail lines for this transaction.

Show TrxResponseDetailDTO (each item)

idTrxDetail

integer (long)

required

Unique ID of the detail record.

detailType

string

required

Type identifier for this detail line.

detailValue

string | null

Value or payload of this detail line.

HTTP Status Codes

Code	Meaning
`200 OK`	Transactions returned (may be empty list).
`400 Bad Request`	Invalid search criteria.
`401 Unauthorized`	Token missing or invalid.

Example

curl --request POST \
  --url 'https://your-gateway.example.com/api/operations/v1/operations/getTrx' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "trxPrefix": "PRDLBR",
    "status": "COMPLETED",
    "location": "Farm A - Block 3"
  }'

{
  "success": true,
  "message": "Transactions retrieved.",
  "data": [
    {
      "idTrxHeader": 1001,
      "trxPrefix": "PRDLBR",
      "trxDocument": "PRDLBR-20240601-0001",
      "descr": "Morning harvest labor record",
      "trxDate": "2024-06-01T07:00:00Z",
      "status": "COMPLETED",
      "username": "jsmith",
      "location": "Farm A - Block 3",
      "trxAttributes": [
        { "idTrxAttribute": 1, "attributeKey": "SHIFT", "attributeValue": "MORNING" }
      ],
      "trxProducts": [
        { "idTrxProduct": 1, "idVariety": 10, "varietyName": "Lavender Fine", "sku": "LAV-001-F", "qty": 25.5 }
      ],
      "trxStates": [
        { "idTrxState": 1, "trxState": "CREATED", "stateDate": "2024-06-01T07:00:00Z", "comments": "Initial record" },
        { "idTrxState": 2, "trxState": "COMPLETED", "stateDate": "2024-06-01T14:30:00Z", "comments": "Harvest completed and verified." }
      ],
      "trxDetails": [
        { "idTrxDetail": 1, "detailType": "EMPLOYEE", "detailValue": "EMP-042" }
      ]
    }
  ],
  "errorType": null,
  "traceId": null,
  "details": null
}