AI Agent Reference

Compact reasoning layer. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec. This section supplies intent, ordering, side effects, and safety that the spec cannot express.

Operation Intent

operation_id	Goal
`CreateTransaction`	Originate a new KY title/registration transaction and submit it for asynchronous DMV processing.
`UpdateTransaction`	Amend or complete an existing transaction (identified by numeric id or `refNumber`), re-triggering asynchronous processing.

Prerequisite / Dependency Tree

Valid client credentials (Key Management, per environment)
  └─ Access token (scope: oneapi:access)
       ├─ CreateTransaction
       │     requires: valid KYEVRTransactionDTO payload
       │     produces: transaction (addressable by refNumber / transactionId)
       │     produces (async): typed CallbackDTO -> callbackUrl
       └─ UpdateTransaction
             requires: an existing transaction (transactionId OR refNumber)
             requires: valid KYEVRTransactionDTO payload

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
AUTH:            oneapi:access via keycloak scheme (REQUIRED)
PRECONDITIONS:   valid access token (REQUIRED)
                 well-formed KYEVRTransactionDTO body (REQUIRED)
                 client-generated refNumber for correlation (OPTIONAL, STRONGLY RECOMMENDED)
                 callbackUrl, network-accessible HTTPS (OPTIONAL, RECOMMENDED)
                 transactionType query param (OPTIONAL; set per KY EVR)
SIDE_EFFECTS:    creates a new transaction resource; initiates async DMV processing;
                 will emit callback(s) to callbackUrl
SUCCESS_SIGNAL:  synchronous = acceptance acknowledgement (accepted-for-processing, NOT final).
                 authoritative = success-type callback with a terminal status field
                 (consult spec status enums). Do NOT treat the sync response as completion.
AGENT_NOTE:      no idempotency key exists; a retry may duplicate the transaction.
                 Do not blind-retry a create that may have succeeded.

OPERATION: UpdateTransaction
AUTH:            oneapi:access via keycloak scheme (REQUIRED)
PRECONDITIONS:   valid access token (REQUIRED)
                 an existing transaction, addressed by transactionId OR refNumber (REQUIRED)
                 well-formed KYEVRTransactionDTO body (REQUIRED)
SIDE_EFFECTS:    mutates the existing transaction; re-initiates async processing;
                 will emit callback(s) to callbackUrl
SUCCESS_SIGNAL:  synchronous = acceptance acknowledgement. authoritative = subsequent
                 callback reflecting updated state.
AGENT_NOTE:      replace-vs-merge semantics are UNSPECIFIED. Send a complete payload
                 unless Vitu confirms partial-merge is supported.

Safety Classification

operation_id	Classification	Rationale
`CreateTransaction`	mutating (create)	Creates a new transaction and starts DMV processing; no server-side dedupe.
`UpdateTransaction`	mutating	Alters an existing transaction and re-triggers processing.

No read-only (safe) operation is defined. No explicit delete/cancel operation is defined; DMV-facing effects of processing should be treated as potentially irreversible — confirm cancellation paths with Vitu before assuming any submission can be undone.

Failure-Handling Rules

ON_FAILURE_AUTH:
  MEANS:    token missing/expired/invalid.
  RETRY:    yes, exactly once, after acquiring a fresh token.
  BACKOFF:  none for the single refresh-retry.
  STOP:     if it recurs post-refresh -> treat as credential/config error; escalate.

ON_FAILURE_FORBIDDEN:
  MEANS:    authenticated but lacking permission/scope.
  RETRY:    no.
  STOP:     immediately; verify entitlement/scope; escalate to support.

ON_FAILURE_VALIDATION:
  MEANS:    payload rejected (bad request); see Errors schema.
  RETRY:    not without modification.
  ACTION:   parse Errors, correct fields, resubmit (create) or UpdateTransaction.
  STOP:     after correcting; do not loop on identical payloads.

ON_FAILURE_NOT_FOUND:
  MEANS:    referenced transaction/resource does not exist.
  RETRY:    no.
  ACTION:   verify transactionId / refNumber correctness.
  STOP:     immediately.

ON_FAILURE_RATE_LIMIT:
  MEANS:    throttled (too many requests).
  RETRY:    yes.
  BACKOFF:  honor Retry-After; else wait for RateLimit-Reset; exponential + jitter thereafter.
  STOP:     after a capped attempt count; then escalate.

ON_FAILURE_SERVER:
  MEANS:    server-side fault.
  RETRY:    yes, cautiously.
  BACKOFF:  exponential + jitter, capped attempts.
  STOP:     if persistent -> escalate to [email protected].
  AGENT_NOTE: for CreateTransaction, a server error after an accepted request may still
              have created a transaction; verify via callback before retrying to avoid duplicates.

ON_FAILURE_CALLBACK_UNACKNOWLEDGED:
  MEANS:    receiver did not return an acceptance response.
  RETRY:    delivery/retry policy is UNSPECIFIED in the spec.
  ACTION:   make handler idempotent (key: refNumber + callbackType + timestamp);
            confirm delivery policy with Vitu.

Workflow Recipes

RECIPE: Submit and resolve a KY EVR transaction

1. Acquire token (client-credentials, scope oneapi:access).
2. Generate refNumber (UUID); build KYEVRTransactionDTO.
3. CreateTransaction (attach callbackUrl, transactionType).
4. On sync acceptance: persist refNumber (+ returned id); mark state = PENDING.
5. Await callback -> dispatch on callbackType:
   - - SUCCESS  -> record terminal status, indicia/shipment, assigned identifiers.
   - - FAILURE  -> read errors -> go to RECIPE: Correct a rejected transaction.
   - - EVR/DMVDESK/INVOICED -> update local record per channel data.
6. Never mark complete from the sync response alone.

RECIPE: Correct a rejected transaction

1. Receive FAILURE callback (or synchronous validation error).
2. Parse errors; identify offending fields.
3. Amend the KYEVRTransactionDTO (send complete payload; merge semantics unconfirmed).
4. UpdateTransaction addressing the same refNumber/transactionId.
5. Await new callback; repeat until terminal SUCCESS or non-fixable failure.

RECIPE: Draft then finalize

1. CreateTransaction with saveForLater = true.
2. Later, UpdateTransaction with completed payload (saveForLater cleared/false).
3. Await callback for terminal state.
AGENT_NOTE: confirm how draft vs submitted maps to status enums (truncated in spec).