AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, enums, and status codes directly from the OpenAPI spec; this section supplies only what the spec cannot express.

Operation Intent

operation_id	Goal
`CreateTransaction`	Submit a new ID EVR title/registration filing for asynchronous DMV processing.
`UpdateTransaction`	Amend an existing or draft transaction identified by `transactionId` or `refNumber`.

Prerequisite / Dependency Tree

OAuth token (scope oneapi:access)
 └─ CreateTransaction
     ├─ requires: assembled IDEVRTransactionDTO (vehicle + owner + registration action + applicationType)
     ├─ optional: reachable HTTPS callbackUrl to receive results
     └─ produces: transactionId + refNumber (correlation keys)
         └─ UpdateTransaction
             └─ requires: an existing transaction identifier (transactionId or refNumber)

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
  AUTH:            REQUIRED — keycloak client-credentials, scope oneapi:access
  PRECONDITIONS:   REQUIRED — valid IDEVRTransactionDTO; conditional field
                   requirements per applicationType/registration.action are
                   NOT schema-encoded
                   OPTIONAL — callbackUrl (HTTPS, reachable); transactionType;
                   x-on-behalf-of-user
  SIDE_EFFECTS:    REQUIRED — creates a transaction queued for async DMV
                   processing; may later emit callbacks; may generate shipments/
                   indicia and invoicing downstream
  SUCCESS_SIGNAL:  Acceptance response = queued, NOT completed. True outcome is a
                   CallbackDTO where callbackType=SUCCESS/EVR/INVOICED and the
                   relevant status field (TransactionStatusEnum / UniversalStatusEnum)
                   reaches a terminal value. Do NOT treat the sync response as done.
  AGENT_NOTE:      Set and persist refNumber before sending; it is the correlation key.

OPERATION: UpdateTransaction
  AUTH:            REQUIRED — keycloak client-credentials, scope oneapi:access
  PRECONDITIONS:   REQUIRED — existing transaction id (transactionId OR refNumber)
                   in an editable state; revised IDEVRTransactionDTO
                   OPTIONAL — transactionType; x-on-behalf-of-user
  SIDE_EFFECTS:    REQUIRED — mutates the target transaction; re-triggers async
                   processing and subsequent callbacks
  SUCCESS_SIGNAL:  Acceptance response = accepted for reprocessing. Confirm via
                   subsequent CallbackDTO status, not the sync response.

Safety Classification

operation_id	Classification	Rationale
`CreateTransaction`	mutating	Creates a transaction and initiates DMV-bound async processing.
`UpdateTransaction`	mutating	Alters an existing transaction and re-triggers processing.

No read-only (safe) operation exists in this spec. No explicit delete/void operation is exposed; voiding, if any, is reflected only through status enums in callbacks (e.g. UniversalStatusEnum / EDealStatus VOID) — treat the practical effect of a filing as difficult to reverse and confirm reversal paths with Vitu.

Failure-Handling Rules

ON_FAILURE_AUTH_UNAUTHENTICATED:
  MEANS:   token missing/expired/invalid
  RETRY:   yes, once, after acquiring a fresh token
  BACKOFF: none (single refresh-and-retry)
  STOP:    second consecutive failure => config/credential error; halt

ON_FAILURE_AUTH_FORBIDDEN:
  MEANS:   authenticated but lacks permission/scope
  RETRY:   no
  STOP:    immediately; escalate for access

ON_FAILURE_VALIDATION:
  MEANS:   malformed or business-invalid payload (body: Errors schema)
  RETRY:   no — not without modifying the request
  BACKOFF: n/a
  STOP:    parse Errors detail; correct fields; resubmit via UpdateTransaction
           or a corrected CreateTransaction

ON_FAILURE_NOT_FOUND:
  MEANS:   referenced transaction id does not exist
  RETRY:   no
  STOP:    verify transactionId/refNumber; do not blind-retry

ON_FAILURE_RATE_LIMIT:
  MEANS:   request throttled
  RETRY:   yes
  BACKOFF: honor Retry-After header; else exponential + jitter, guided by
           RateLimit-Limit / RateLimit-Reset
  STOP:    after capped attempts; then alert

ON_FAILURE_SERVER:
  MEANS:   transient server-side error (body: Errors schema)
  RETRY:   yes
  BACKOFF: exponential + jitter
  STOP:    after capped attempts; then alert

Workflow Recipes

RECIPE: submit_new_filing

1. token = obtain_oauth_token(scope=oneapi:access)
2. body  = assemble IDEVRTransactionDTO (vehicle, owner(s), registration.action, applicationType)
3. refNumber = generate_or_reuse_uuid(); set on body
4. CreateTransaction(body, callbackUrl, [transactionType])  -> expect acceptance
5. persist(refNumber, returned ids)
6. await CallbackDTO; dispatch on callbackType:
   - - SUCCESS/EVR/INVOICED -> record outcome
   - - FAILURE              -> goto RECIPE: correct_rejected_filing

RECIPE: correct_rejected_filing

1. read errors (Errors / bundleErrors); for DMVDESK check bundleError.fixable
2. if not fixable -> stop, escalate
3. token = ensure_valid_token()
4. UpdateTransaction(id=refNumber|transactionId, corrected_body) -> expect acceptance
5. await CallbackDTO; repeat until terminal SUCCESS or unfixable FAILURE

RECIPE: progress_saved_draft

1. earlier: CreateTransaction with saveForLater=true (draft)
2. token = ensure_valid_token()
3. UpdateTransaction(id, body with saveForLater=false)  [CONFIRM state machine with Vitu]
4. await CallbackDTO for outcome

AGENT_NOTE (global): all operations are async. Never conclude success from the
2xx acceptance response; conclude only from a terminal callback status field.