CreateTransaction
- requires: valid token (oneapi:access), state-appropriate body
- enables:
  - GetTransactionIdByRefNumber   (needs refNumber from create)
  - UpdateTransaction             (needs existing transaction, not finalized)
  - CancelTransaction             (needs existing transaction, cancellable state)
  - GetTransactionFees            (fees produced by processing)
  - GetTransactionForms           (forms produced by processing)
    │   └── DownloadTransactionForms / DownloadTransactionDocument
  - InitiateSign                  (needs existing transaction; sign-eligible)
    │   ├── GetSignLink               (needs initiated sign flow + signerNumber)
    │   ├── ResendSignInvitation      (needs initiated sign flow + signerNumber)
    │   └── CancelSign                (needs initiated sign flow)
  - CommitTransaction             (needs existing transaction in committable state)

OPERATION: CreateTransaction
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: valid state-specific body; state discriminator set [REQUIRED]
  SIDE_EFFECTS: creates a new transaction; begins async processing; may trigger callbacks [REQUIRED]
  SUCCESS_SIGNAL: request accepted for processing + a returned reference/id;
                  final success confirmed via callback status field (not the acceptance response)
  AGENT_NOTE: persist returned refNumber/id for correlation before doing anything else.

OPERATION: UpdateTransaction
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists; not finalized [REQUIRED]
  SIDE_EFFECTS: mutates transaction state; may trigger callbacks [REQUIRED]
  SUCCESS_SIGNAL: accepted-for-processing; confirm via subsequent status/callback

OPERATION: CancelTransaction
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists; in a cancellable state [REQUIRED]
  SIDE_EFFECTS: cancels transaction; may trigger callbacks [REQUIRED]
  SUCCESS_SIGNAL: accepted; transaction status reflects cancellation via status field/callback

OPERATION: CommitTransaction
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists; committable state; shipping info present [REQUIRED]
                 plate-destination / signer info [OPTIONAL, state/flow-dependent]
  SIDE_EFFECTS: finalizes/submits transaction downstream; may trigger callbacks [REQUIRED]
  SUCCESS_SIGNAL: accepted; final state reflected via status/universalStatus in callback
  AGENT_NOTE: treat as the point of no easy return; verify fees/forms first.

OPERATION: GetTransactionForms
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists                [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: array returned; EMPTY array means "not yet generated", not error.

OPERATION: GetTransactionFees
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists                [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: array returned; may be empty until processing produces fees.

OPERATION: DownloadTransactionForms / DownloadTransactionDocument
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists; document(s) generated (unless blank=true) [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: PDF binary returned.

OPERATION: GetTransactionIdByRefNumber
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: valid UUID refNumber              [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: integer id returned.

OPERATION: InitiateSign
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: transaction exists; sign-eligible; sender/signer details [REQUIRED]
  SIDE_EFFECTS: starts e-sign flow; sends invitation(s) to signers [REQUIRED]
  SUCCESS_SIGNAL: accepted; sign flow active (signer links become retrievable)

OPERATION: GetSignLink
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: sign flow initiated; valid signerNumber (1=owner,2=co-owner) [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: signing URL returned.

OPERATION: ResendSignInvitation
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: sign flow initiated; valid signerNumber [REQUIRED]
  SIDE_EFFECTS: sends another invitation email to the signer [REQUIRED]
  SUCCESS_SIGNAL: accepted.

OPERATION: CancelSign
  AUTH: oneapi:access                              [REQUIRED]
  PRECONDITIONS: sign flow initiated; reason provided [REQUIRED]
                 deleteSignedDocuments flag         [OPTIONAL]
  SIDE_EFFECTS: cancels sign request; may delete signed documents if requested [REQUIRED]
  SUCCESS_SIGNAL: accepted.

ON_FAILURE_AUTH_UNAUTHENTICATED:
  MEANS: token missing/expired/invalid.
  RETRY: yes, once, after acquiring a fresh token.
  STOP_CONDITION: second consecutive failure → treat as credential/config error; halt.

ON_FAILURE_AUTH_FORBIDDEN:
  MEANS: authenticated client lacks permission for this API/resource.
  RETRY: no.
  STOP_CONDITION: immediate; escalate to human / VITU support.

ON_FAILURE_VALIDATION:
  MEANS: request shape invalid for the target state / missing required fields.
  RETRY: no (not without changing the payload).
  STOP_CONDITION: immediate; inspect Errors messages; correct against correct state variant.

ON_FAILURE_NOT_FOUND:
  MEANS: referenced transaction/resource absent or not yet available.
  RETRY: conditional — if resource is expected-eventual (just created/processing), backoff+retry;
         else treat as terminal.
  STOP_CONDITION: bounded retries exhausted → halt.

ON_FAILURE_RATE_LIMIT:
  MEANS: request rate exceeded the window.
  RETRY: yes, after window reset.
  BACKOFF: wait for reset, then exponential backoff with jitter.
  STOP_CONDITION: bounded attempts exhausted → halt and escalate.

ON_FAILURE_SERVER:
  MEANS: transient server-side error.
  RETRY: yes.
  BACKOFF: exponential with jitter.
  STOP_CONDITION: small bounded attempt count → halt.

RECIPE: Submit and finalize a transaction

1. CreateTransaction            -> persist refNumber/id
2. (if only refNumber known) GetTransactionIdByRefNumber
3. WAIT for processing (prefer callback; else poll)
4. GetTransactionFees           -> verify fees produced (empty => not ready, backoff)
5. GetTransactionForms          -> verify forms produced (empty => not ready, backoff)
6. DownloadTransactionForms / DownloadTransactionDocument (optional)
7. CommitTransaction            -> finalize with shipping (+ plate/signer as required)
8. CONFIRM final state via callback status/universalStatus

RECIPE: Transaction requiring e-signature

1. CreateTransaction            -> persist id
2. InitiateSign                 -> provide sender + owner/coOwner participants
3. GetSignLink (signerNumber=1) [and =2 if co-owner]  -> distribute links
4. ResendSignInvitation         -> only if a signer did not receive/act
5. WAIT for signing completion (callback signerStatus/signRequestStatus)
6. CommitTransaction            -> finalize
  ALT: CancelSign (reason required) to abort signing; set deleteSignedDocuments only if intended.

RECIPE: Amend before finalizing

1. UpdateTransaction (COMPLETE state-specific body)  -> replace-semantics assumed
2. Re-fetch GetTransactionFees / GetTransactionForms to confirm regenerated outputs
3. Proceed to CommitTransaction