AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec. This section supplies only intent, ordering, side effects, safety, and failure logic.

Operation Intent

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

Prerequisite / Dependency Tree

OAuth token (scope oneapi:access)
- CreateTransaction
  - requires: valid MNEVRTransactionDTO (owner + vehicle populated)
  - produces: assigned transactionId (delivered via callback)
  - optional: callbackUrl registered for async result delivery
    - UpdateTransaction
        - requires: existing refNumber OR transactionId from a prior CreateTransaction

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
  AUTH: keycloak / oneapi:access ......................... REQUIRED
  PRECONDITIONS:
    - Valid access token .............................. REQUIRED
    - MNEVRTransactionDTO body ........................ REQUIRED
    - Caller-generated refNumber (UUID) for correlation OPTIONAL (RECOMMENDED)
    - Network-accessible HTTPS callbackUrl ............ OPTIONAL (RECOMMENDED)
  SIDE_EFFECTS:
    - Creates a transaction in the Vitu system ........ MUTATING
    - Initiates asynchronous DMV filing / processing
    - May trigger later callback POST(s) to callbackUrl
  SUCCESS_SIGNAL:
    - Synchronous: request accepted for async processing (do NOT treat as DMV completion)
    - Authoritative: result callback received; success variant carries transactionId + status
  AGENT_NOTE: The accepted response is receipt-only. Await callback for true outcome.

OPERATION: UpdateTransaction
  AUTH: keycloak / oneapi:access ......................... REQUIRED
  PRECONDITIONS:
    - Valid access token .............................. REQUIRED
    - Path identifier (refNumber OR transactionId) .... REQUIRED
    - Prior CreateTransaction for that identifier ..... REQUIRED
    - MNEVRTransactionDTO body ........................ REQUIRED
  SIDE_EFFECTS:
    - Modifies an existing transaction ................ MUTATING
    - Re-initiates asynchronous processing
    - May trigger later callback POST(s)
  SUCCESS_SIGNAL:
    - Synchronous: accepted for async processing
    - Authoritative: subsequent result callback
  AGENT_NOTE: Replace-vs-merge semantics UNCONFIRMED. Send a COMPLETE body; assume full replacement.

Safety Classification

operation_id	Classification	Notes
`CreateTransaction`	mutating	Creates a resource and initiates a DMV filing. Not idempotent unless deduplicated by caller.
`UpdateTransaction`	mutating	Modifies existing state and re-initiates processing.

No read-only (safe) operation exists in this spec. No explicit delete/void operation exists; void appears only as a status value in callbacks, not as an invokable operation.

Failure-Handling Rules

ON_FAILURE_AUTH (unauthorized):
  MEANING: token missing, expired, or invalid.
  RETRY: yes, once, after acquiring a fresh token.
  BACKOFF: none for the single re-auth attempt.
  STOP: if failure persists after re-auth -> credential/config error; escalate, do not loop.

ON_FAILURE_FORBIDDEN (permission denied):
  MEANING: authenticated but lacks entitlement.
  RETRY: no.
  STOP: immediately; requires entitlement change from Vitu.

ON_FAILURE_VALIDATION (bad request):
  MEANING: payload malformed or invalid; detail in Errors schema.
  RETRY: no (not without changing the payload).
  ACTION: parse Errors messages, correct fields, resubmit.
  STOP: after correction fails repeatedly -> surface for human review.

ON_FAILURE_NOT_FOUND:
  MEANING: referenced transaction (refNumber/transactionId) does not exist.
  RETRY: no.
  ACTION: verify identifier; do not fabricate.
  STOP: immediately.

ON_FAILURE_RATE_LIMIT (too many requests):
  MEANING: throttled.
  RETRY: yes.
  BACKOFF: honor Retry-After; else use RateLimit-Reset; else exponential backoff + jitter.
  STOP: after a bounded attempt cap.

ON_FAILURE_SERVER (server error):
  MEANING: server-side failure.
  RETRY: yes, transient assumption.
  BACKOFF: exponential + jitter.
  STOP: after bounded attempt cap -> escalate.

ON_FAILURE_CALLBACK_DELIVERY:
  MEANING: async result not received within expected window.
  RETRY: N/A from caller side (no poll endpoint exists).
  ACTION: rely on caller-side idempotency + reconciliation by refNumber; escalate to Vitu if unresolved.

Workflow Recipes

RECIPE: Submit and confirm a transaction

1. Acquire token (keycloak client-credentials, scope oneapi:access).
2. Generate refNumber (UUID); persist it.
3. CreateTransaction(body=MNEVRTransactionDTO, callbackUrl=<your endpoint>).
4. On accepted response -> mark PENDING, keyed by refNumber.
5. On inbound callback:
   - - - verify HMAC signature if configured;
   - - - match by refNumber;
   - - - branch on callbackType (SUCCESS -> store transactionId+status;
   - - FAILURE -> capture errors; INVOICED -> capture fees).
6. Deduplicate callbacks (refNumber + callbackType + timestamp).

RECIPE: Correct a rejected transaction

1. Receive FAILURE callback; parse errors.
2. Rebuild a COMPLETE MNEVRTransactionDTO with corrections (assume full replacement).
3. UpdateTransaction(path=refNumber or transactionId, body=<corrected>).
4. Await subsequent result callback; reconcile by refNumber.

RECIPE: Draft then finalize

1. CreateTransaction with saveForLater=true.  [KNOWN_ISSUE: hold-vs-file behavior unconfirmed]
2. Later, UpdateTransaction with completed body and saveForLater=false.
3. Await result callback.