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 TX title/registration transaction for asynchronous processing.
`UpdateTransaction`	Modify an existing transaction (addressed by integer ID or `refNumber`) and resubmit for processing.

Prerequisite / Dependency Tree

OAuth token (scope oneapi:access)
  └─ CreateTransaction  → produces transaction (refNumber + system transactionId)
        └─ UpdateTransaction  (requires an existing transaction identifier)
        └─ onStatusChange callback(s)  (requires a reachable callbackUrl supplied at create/update)

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
  AUTH:            REQUIRED — oauth2 keycloak, scope oneapi:access
  PRECONDITIONS:   REQUIRED — valid TXEVRTransactionDTO body; caller-generated refNumber recommended
                   OPTIONAL — callbackUrl (HTTPS, reachable) to receive outcome
                   OPTIONAL — transactionType query param; x-on-behalf-of-user header
  SIDE_EFFECTS:    REQUIRED — creates a persisted transaction; triggers async DMV processing;
                              causes later callback POST(s) to callbackUrl
  SUCCESS_SIGNAL:  Async-accepted response confirms RECEIPT ONLY.
                   True outcome = callback with callbackType SUCCESS/EVR (vs FAILURE).
  AGENT_NOTE:      Do not treat the acceptance response as completion. No status/GET op exists to poll.

OPERATION: UpdateTransaction
  AUTH:            REQUIRED — oauth2 keycloak, scope oneapi:access
  PRECONDITIONS:   REQUIRED — existing transaction addressable by integer transactionId OR refNumber
                   REQUIRED — full TXEVRTransactionDTO body (treat as full replacement)
                   OPTIONAL — transactionType query param; x-on-behalf-of-user header
  SIDE_EFFECTS:    REQUIRED — mutates the existing transaction; re-triggers async processing;
                              causes later callback POST(s)
  SUCCESS_SIGNAL:  Async-accepted response = receipt only; outcome via subsequent callback.
  AGENT_NOTE:      404 class ⇒ identifier not found or not yet persisted; do not retry blindly.

Safety Classification

operation_id	Classification	Notes
`CreateTransaction`	mutating	Creates state; initiates DMV-facing processing.
`UpdateTransaction`	mutating	Alters existing transaction; re-initiates processing.
(incoming callback receipt)	n/a (inbound)	Agent is the receiver; verify HMAC when configured.

No read-only (safe) and no delete/irreversible operations are defined in the spec.

Failure-Handling Rules

ON_FAILURE_AUTH        (401 class)
  MEANS:   Missing/expired/invalid token.
  RETRY:   Yes — refresh token, retry once.
  BACKOFF: None; single retry.
  STOP:    Second consecutive auth failure ⇒ stop, surface credential/config error.

ON_FAILURE_FORBIDDEN   (403 class)
  MEANS:   Authenticated but lacks permission/scope.
  RETRY:   No.
  STOP:    Immediately; escalate entitlement issue.

ON_FAILURE_VALIDATION  (400 class — Errors schema)
  MEANS:   Malformed body or business-rule violation.
  RETRY:   No (not without changing the request).
  STOP:    Immediately; correct per returned messages, then resubmit as a new attempt.

ON_FAILURE_NOT_FOUND   (404 class)
  MEANS:   Target transaction not located by given identifier.
  RETRY:   No blind retry. May retry once briefly if transaction may not yet be persisted.
  STOP:    After verifying identifier; escalate if persistently absent.

ON_FAILURE_RATE_LIMIT  (429 class)
  MEANS:   Throttled.
  RETRY:   Yes.
  BACKOFF: Honor Retry-After; else exponential backoff + jitter, guided by RateLimit-Reset.
  STOP:    After a bounded max attempts.

ON_FAILURE_SERVER      (500 class)
  MEANS:   Vitu-side error.
  RETRY:   Yes.
  BACKOFF: Exponential + jitter.
  STOP:    After bounded max attempts; escalate to [email protected].

ON_FAILURE_CALLBACK_DELIVERY
  MEANS:   Outcome callback not received.
  RETRY:   Redelivery policy NOT specified in spec (KNOWN_ISSUE).
  STOP:    No documented re-fetch path (no status op). Escalate to Vitu for reconciliation.

Workflow Recipes

RECIPE: Submit and confirm a title/registration transaction

1. Acquire token (client-credentials, scope oneapi:access).
2. CreateTransaction { body: TXEVRTransactionDTO (set refNumber), query: callbackUrl, transactionType }.
3. Expect async-accepted response → record refNumber ↔ your internal id.
4. On inbound callback: verify HMAC (if configured); switch on callbackType.
   - - SUCCESS/EVR → mark complete; capture control/plate/indicia data.
   - - FAILURE     → read errors; correct; go to RECIPE "Update".
   - - INVOICED    → reconcile fees.

RECIPE: Update (correct/complete) a pending transaction

1. Acquire/reuse token.
2. UpdateTransaction { path: refNumber (or transactionId), body: full TXEVRTransactionDTO }.
3. Expect async-accepted response.
4. Await fresh callback; branch on callbackType as above.
  NOTE: Body is full replacement — include complete intended state.

AGENT_NOTE (global): Success is always determined by the callback, never by the synchronous
response. There is no polling/status operation. Correlate exclusively via refNumber / transactionId.