NMVTIS Notifications — AI Agent Reference | Vitu Production Developer Portal

AI Agent Reference

Compact reasoning layer. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec; the following supplies only what the spec cannot express.

Operation intent

operation_id	Goal
`SetCallbackSecurity`	Configure how Vitu authenticates/secures delivery to the caller's callback endpoint.
`Subscribe`	Register a callback URL to receive NMVTIS notifications.
`GetSubscription`	Retrieve the currently registered callback URL.
`Unsubscribe`	Remove the subscription and stop deliveries.

Prerequisite / dependency tree

Valid OAuth token (oneVituOauth / oneapi:access)
- SetCallbackSecurity   (recommended before Subscribe)
- Subscribe             (requires resolvable HTTPS callback URL)
  - GetSubscription  (meaningful only after a Subscribe)
  - Unsubscribe      (meaningful only after a Subscribe)

Per-operation reasoning contracts

OPERATION: SetCallbackSecurity
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — valid token. OPTIONAL — none.
  SIDE_EFFECTS:   REQUIRED — replaces callback security configuration for delivery.
  SUCCESS_SIGNAL: REQUIRED — success response returned; config now governs deliveries.
  AGENT_NOTE:     Run before Subscribe so deliveries are never sent to an unsecured endpoint.
  KNOWN_ISSUE:    Replace-vs-merge semantics for security settings are not stated in the spec.

OPERATION: Subscribe
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — resolvable HTTPS callback URL (spec enforces https:// and length).
                  OPTIONAL — callback security configured first (recommended).
  SIDE_EFFECTS:   REQUIRED — registers subscription; enables push delivery to callback URL.
  SUCCESS_SIGNAL: REQUIRED — creation success; GetSubscription then reflects the callback URL.

OPERATION: GetSubscription
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  OPTIONAL — a prior Subscribe (otherwise result may be empty).
  SIDE_EFFECTS:   NONE (read-only).
  SUCCESS_SIGNAL: REQUIRED — response body carries the registered callbackUrl.
  AGENT_NOTE:     Supports limit/offset params per spec; treat as paginated read.

OPERATION: Unsubscribe
  AUTH:           REQUIRED — oneVituOauth, scope oneapi:access
  PRECONDITIONS:  REQUIRED — an existing subscription to remove.
  SIDE_EFFECTS:   REQUIRED — removes subscription; halts future deliveries.
  SUCCESS_SIGNAL: REQUIRED — success response; GetSubscription no longer returns the URL.

Safety classification

operation_id	Classification
`GetSubscription`	safe (read-only)
`SetCallbackSecurity`	mutating
`Subscribe`	mutating
`Unsubscribe`	mutating (reversible via Subscribe)

No operation in this spec is strictly irreversible; however, Unsubscribe interrupts delivery and may cause missed notifications during the gap.

Failure-handling rules

ON_FAILURE_AUTH:        (spec 401)
  MEANING:   Missing/expired/invalid token.
  RETRY:     Yes, once, after acquiring a fresh token.
  STRATEGY:  Re-fetch token from oneVituOauth token endpoint, retry once.
  STOP:      If still failing, treat credentials as invalid; halt.

ON_FAILURE_VALIDATION:  (spec 400 / BadRequest, Errors schema)
  MEANING:   Malformed request (e.g., non-HTTPS or over-length callback URL).
  RETRY:     No.
  STRATEGY:  Correct request against spec constraints; resubmit.
  STOP:      Immediately; do not loop.

ON_FAILURE_NOT_FOUND:
  MEANING:   No dedicated not-found response is defined in this spec.
  RETRY:     N/A.
  STRATEGY:  Treat absent subscription via empty GetSubscription result, not an error code.
  STOP:      N/A.

ON_FAILURE_RATE_LIMIT:  (spec 429 / TooManyRequests, Errors schema)
  MEANING:   Rate limit exceeded.
  RETRY:     Yes.
  STRATEGY:  Back off and retry after window resets; read any rate-limit headers at runtime.
  STOP:      After bounded attempts.

ON_FAILURE_SERVER:      (spec 500 / ServerError, Errors schema)
  MEANING:   Transient server-side error.
  RETRY:     Yes.
  STRATEGY:  Exponential backoff with jitter.
  STOP:      After bounded attempts; escalate to [email protected].

Workflow recipes

RECIPE: First-time notification setup

1. Acquire token (oneVituOauth / oneapi:access)
2. SetCallbackSecurity        # secure the endpoint first
3. Subscribe                  # register HTTPS callback URL
4. GetSubscription            # verify registration

RECIPE: Rotate callback secret

1. Receiver accepts old + new secret
2. SetCallbackSecurity (new)
3. Confirm deliveries succeed, then retire old secret

RECIPE: Change destination endpoint

1. SetCallbackSecurity (for new endpoint)
2. Subscribe (new callback URL)
3. GetSubscription            # confirm replace vs. add (multiplicity unconfirmed)

RECIPE: Teardown

1. Unsubscribe