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 IL title/registration transaction for asynchronous processing with the DMV.
`UpdateTransaction`	Amend a previously submitted transaction, referenced by numeric ID or `refNumber` UUID.

Prerequisite / Dependency Tree

Valid OAuth client-credentials token (scope: oneapi:access)
 └─ CreateTransaction
     ├─ produces: numeric transactionId (via callback) + echoes client refNumber
     └─ UpdateTransaction
         └─ requires: an existing transaction (by transactionId OR refNumber)
Reachable callbackUrl (HTTPS)  ── required to observe outcomes; no read operation exists

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
  AUTH: oneapi:access via keycloak (client-credentials Bearer)   [REQUIRED]
  PRECONDITIONS:
    - Valid non-expired token                                    [REQUIRED]
    - Well-formed ILEVRTransactionDTO                            [REQUIRED]
    - callbackUrl provided and network-reachable                 [OPTIONAL but STRONGLY RECOMMENDED — no read op exists]
    - transactionType query param                                [OPTIONAL]
    - x-on-behalf-of-user header                                 [OPTIONAL]
  SIDE_EFFECTS:
    - Creates a new transaction in Vitu; initiates async DMV processing.  [MUTATING]
    - May file with the state; downstream effects are not reversible via this API.
  SUCCESS_SIGNAL:
    - Sync: acknowledgment response (accepted-for-processing) — NOT a completion signal.
    - Authoritative: onStatusChange callback with callbackType=SUCCESS and a terminal
      status field (see TransactionStatusEnum / UniversalStatusEnum). Correlate on refNumber.
  AGENT_NOTE: Do not treat the sync 2xx as done. Await callback or you will act on incomplete state.

OPERATION: UpdateTransaction
  AUTH: oneapi:access via keycloak (client-credentials Bearer)   [REQUIRED]
  PRECONDITIONS:
    - Valid non-expired token                                    [REQUIRED]
    - transactionId path value = numeric ID OR refNumber UUID    [REQUIRED]
    - Existing transaction matching that identifier              [REQUIRED]
    - Complete ILEVRTransactionDTO                               [REQUIRED — assume full-replace semantics]
    - callbackUrl                                                [OPTIONAL but RECOMMENDED]
    - transactionType / x-on-behalf-of-user                      [OPTIONAL]
  SIDE_EFFECTS:
    - Modifies an existing transaction; re-triggers async processing.  [MUTATING]
  SUCCESS_SIGNAL:
    - Sync: accepted-for-processing acknowledgment.
    - Authoritative: subsequent onStatusChange callback reflecting the amendment.

Safety Classification

operation_id	Classification	Rationale
`CreateTransaction`	mutating → potentially irreversible	Creates a transaction and may file with the DMV; no delete/rollback operation exists.
`UpdateTransaction`	mutating	Alters an existing transaction; effects on already-filed data may be irreversible.

No read-only (safe) operation exists in this spec.

Failure-Handling Rules

ON_FAILURE_AUTH (401):
  MEANS: token missing/expired/invalid.
  RETRY: yes, once, after obtaining a fresh token.
  STRATEGY: re-auth then single retry.
  STOP_CONDITION: second 401 with a valid token → config/credential error; escalate.

ON_FAILURE_FORBIDDEN (403):
  MEANS: authenticated but not entitled.
  RETRY: no.
  STOP_CONDITION: immediate; escalate entitlements to Vitu.

ON_FAILURE_VALIDATION (400):
  MEANS: malformed/invalid payload (see Errors schema).
  RETRY: no (not without changes).
  STRATEGY: parse Errors array, correct payload, resubmit as new attempt.
  STOP_CONDITION: unresolved after correction; escalate.

ON_FAILURE_NOT_FOUND (404):
  MEANS: referenced transaction/resource does not exist.
  RETRY: no.
  STRATEGY: verify transactionId/refNumber correctness.
  STOP_CONDITION: immediate.

ON_FAILURE_RATE_LIMIT (429):
  MEANS: throttled.
  RETRY: yes.
  STRATEGY: honor Retry-After header; else exponential backoff + jitter.
  STOP_CONDITION: max attempts exceeded.

ON_FAILURE_SERVER (500):
  MEANS: platform/downstream failure.
  RETRY: yes.
  STRATEGY: exponential backoff + jitter, bounded attempts.
  STOP_CONDITION: attempt cap reached → escalate.
  AGENT_NOTE: create/update are non-idempotent; retrying after an ambiguous timeout risks
              duplicates — correlate on refNumber before resubmitting.

Workflow Recipes

RECIPE: Submit new registration

1. Obtain token (client-credentials, scope oneapi:access).
2. Generate client refNumber (UUID); persist for correlation.
3. CreateTransaction with ILEVRTransactionDTO + callbackUrl + transactionType.
4. Persist sync acknowledgment; DO NOT mark complete.
5. On onStatusChange callback: branch on callbackType.
   - - SUCCESS → read status/universalStatus → mark complete.
   - - FAILURE → read errors → surface/repair.
6. Correlate callback to request via refNumber (and/or transactionId).

RECIPE: Amend a submitted transaction

1. Ensure valid token.
2. Resolve target by numeric transactionId or refNumber.
3. UpdateTransaction with a COMPLETE ILEVRTransactionDTO (full-replace assumption).
4. Await follow-up onStatusChange callback; interpret as in Submit recipe.

RECIPE: Recover a missed outcome
  STATUS: NO DOCUMENTED PATH.
  There is no read/status operation and callback redelivery behavior is unspecified.
  ACTION: escalate to [email protected]; do NOT resubmit blindly (non-idempotent).