AI Agent Reference

Compact reasoning layer for automated agents. The agent is expected to read parameters, schemas, types, and status codes directly from the OpenAPI spec; the material below supplies intent, ordering, side effects, and safety not expressible there.

Operation Intent Table

operation_id	Goal
`GetVehicleLookup`	Retrieve state vehicle record(s); may yield `stateTransactionId`.
`GetCustomerLookup`	Retrieve state customer record(s) for EVR data assembly.
`GetOwnershipLookup`	Retrieve state ownership record(s) for a VIN.
`CreateTransaction`	Submit a new title/registration transaction (async).
`UpdateTransaction`	Modify an existing transaction (async).
`CancelTransaction`	Cancel an existing transaction (async).
`GetTransactionIdByRefNumber`	Resolve a `refNumber` UUID to a numeric transaction ID.
`GetTransactionFees`	List fees calculated by a transaction.
`GetTransactionForms`	List documents produced by a transaction.
`DownloadTransactionForms`	Download the transaction's document bundle (PDF).
`DownloadTransactionDocument`	Download one document by `documentId` (PDF).

Prerequisite / Dependency Tree

Valid OAuth token (scope oneapi:access)   -> required for ALL operations
Vitu-issued locationId                    -> required for all lookups
GetVehicleLookup (by VIN)                 -> may produce stateTransactionId
  └─ stateTransactionId                   -> required for plate/title-number lookups
CreateTransaction                         -> produces transaction (ID + refNumber)
  ├─ GetTransactionIdByRefNumber          -> needs an existing refNumber
  ├─ GetTransactionFees                   -> needs transaction + processing progressed
  ├─ GetTransactionForms                  -> needs transaction + documents produced
  │    └─ DownloadTransactionDocument     -> needs documentId from GetTransactionForms
  ├─ DownloadTransactionForms             -> needs transaction with produced docs
  ├─ UpdateTransaction                    -> needs existing transaction
  └─ CancelTransaction                    -> needs existing (non-terminal) transaction

Per-Operation Reasoning Contracts

OPERATION: GetVehicleLookup / GetCustomerLookup / GetOwnershipLookup
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: valid locationId (REQUIRED); state (REQUIRED);
                 stateTransactionId (OPTIONAL, REQUIRED for plate/title lookups)
  SIDE_EFFECTS:  none (read-only)
  SUCCESS_SIGNAL: 200 with result DTO; may include stateTransactionId

OPERATION: CreateTransaction
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: FLEVRTransactionDTO body (REQUIRED);
                 callbackUrl (OPTIONAL); transactionType (OPTIONAL)
  SIDE_EFFECTS:  creates a transaction; begins async state processing (MUTATING)
  SUCCESS_SIGNAL: 202 accepted == RECEIPT ONLY, not completion.
                  Final outcome arrives via callback (correlate on refNumber)
                  or via later status/fees/forms retrieval.
  AGENT_NOTE:    Do not fetch fees/forms until a completion signal is observed.

OPERATION: UpdateTransaction
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: existing transaction identifier (REQUIRED); revised body (REQUIRED)
  SIDE_EFFECTS:  modifies transaction; re-triggers async processing (MUTATING)
  SUCCESS_SIGNAL: 202 accepted (receipt only)

OPERATION: CancelTransaction
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: existing transaction identifier (REQUIRED);
                 message (OPTIONAL)
  SIDE_EFFECTS:  cancels transaction (MUTATING; effectively terminal for that txn)
  SUCCESS_SIGNAL: 202 accepted (receipt only); confirm via status/callback

OPERATION: GetTransactionIdByRefNumber
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: existing refNumber UUID (REQUIRED)
  SIDE_EFFECTS:  none (read-only)
  SUCCESS_SIGNAL: 200 with numeric transaction ID

OPERATION: GetTransactionFees / GetTransactionForms
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: existing transaction (REQUIRED); processing produced data (REQUIRED)
  SIDE_EFFECTS:  none (read-only)
  SUCCESS_SIGNAL: 200 with array; empty/partial array is valid pre-completion.

OPERATION: DownloadTransactionForms / DownloadTransactionDocument
  AUTH:          oneapi:access (REQUIRED)
  PRECONDITIONS: existing transaction (REQUIRED);
                 documentId from GetTransactionForms (REQUIRED for single download);
                 target (OPTIONAL); blank flag (OPTIONAL, single download)
  SIDE_EFFECTS:  none (read-only)
  SUCCESS_SIGNAL: 200 with application/pdf binary body.

Safety Classification Table

operation_id	Classification
`GetVehicleLookup`	safe (read-only)
`GetCustomerLookup`	safe (read-only)
`GetOwnershipLookup`	safe (read-only)
`GetTransactionIdByRefNumber`	safe (read-only)
`GetTransactionFees`	safe (read-only)
`GetTransactionForms`	safe (read-only)
`DownloadTransactionForms`	safe (read-only)
`DownloadTransactionDocument`	safe (read-only)
`CreateTransaction`	mutating
`UpdateTransaction`	mutating
`CancelTransaction`	irreversible (terminal for the transaction)

Failure-Handling Rules

ON_FAILURE_AUTH (401):
  MEANING:  missing/expired/invalid token.
  RETRY:    yes, once, after acquiring a fresh token.
  BACKOFF:  none needed for the single retry.
  STOP:     if still 401 after refresh -> stop; escalate credentials issue.

ON_FAILURE_FORBIDDEN (403):
  MEANING:  authenticated but not permitted (scope/location entitlement).
  RETRY:    no.
  STOP:     immediately; do not refresh token blindly. Escalate.

ON_FAILURE_VALIDATION (400):
  MEANING:  malformed request / invalid field values (see Errors schema).
  RETRY:    no, until request corrected.
  STOP:     surface Errors detail; require input correction before resubmit.

ON_FAILURE_NOT_FOUND (404):
  MEANING:  referenced transaction/resource does not exist.
  RETRY:    no (unless racing an async create; then bounded retry with backoff).
  STOP:     verify identifier form (numeric ID vs refNumber) and existence.

ON_FAILURE_RATE_LIMIT (429):
  MEANING:  quota exceeded.
  RETRY:    yes.
  BACKOFF:  honor Retry-After / RateLimit-Reset; exponential backoff + jitter.
  STOP:     after a bounded attempt cap.

ON_FAILURE_SERVER (5xx):
  MEANING:  server-side failure.
  RETRY:    yes for read-only ops; for MUTATING ops verify current state first
            to avoid duplicate transactions.
  BACKOFF:  exponential + jitter.
  STOP:     after attempt cap; escalate.

Workflow Recipes

RECIPE: File a transaction with callback notification

1. GetVehicleLookup (VIN)          # gather vehicle data; capture stateTransactionId
2. GetCustomerLookup / GetOwnershipLookup  # gather owner/ownership data
3. CreateTransaction (body + callbackUrl)  # expect 202; store refNumber
4. WAIT for callback POST -> branch on CallbackDTO.callbackType
   - - SUCCESS-type -> proceed to step 5
   - - FAILURE-type -> read errors; correct via UpdateTransaction or stop
5. GetTransactionFees               # retrieve calculated fees
6. GetTransactionForms              # enumerate produced documents
7. DownloadTransactionDocument(documentId) or DownloadTransactionForms

RECIPE: File a transaction without a callback (polling)

1. CreateTransaction (body, no callbackUrl)  # expect 202; store refNumber
2. GetTransactionIdByRefNumber (if numeric ID needed)
3. POLL GetTransactionForms / GetTransactionFees with backoff
   - - empty/partial -> keep polling until populated or timeout
4. Download documents once forms are available

RECIPE: Correct a rejected transaction

1. Observe FAILURE callback or terminal status
2. Inspect Errors detail
3. UpdateTransaction (corrected body)   # expect 202
4. Re-enter callback/polling wait

RECIPE: Abandon a transaction

1. CancelTransaction (identifier, optional message)  # expect 202
2. Confirm cancellation via status/callback
  # IRREVERSIBLE: treat transaction as terminal afterward.