Read Rail instruction as of a watermark

GET

/v1/object-types/hospitality.rail_instruction/objects/{id}/as-of

const url = 'https://api.aerandil.com/v1/object-types/hospitality.rail_instruction/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/as-of?at=example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.aerandil.com/v1/object-types/hospitality.rail_instruction/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/as-of?at=example' \
  --header 'Authorization: Bearer <token>'

Time-travel read: the instance as it stood at the at watermark, reconstructed by folding its structural events. Property values that were marking-redacted or truncated in the event log surface as sentinel objects, not values.

One thing the card rail is to do at the processor once it can be reached again — OPERA’s offline settlement queue. Written by the rail (queue_rail_instruction) when the processor was unreachable (a transport failure, a 5xx, a 429) during a deferrable verb: a hold captured at check-out (capture), a hold released (void), a refund (refund), a departed stay’s late charges (charge_off_session), the desk’s Top up now for an in-house stay (top_up, continuing the stay’s open top-up attempt). Never a check-in’s authorisation — that hold is placed because the desk needs the answer now. attempt_id is written before the processor is asked again and every processor idempotency key for the instruction derives from it, so a retry is the same request and a capture that reached the processor once is never taken twice. The rail’s drain claims it (sending), asks the processor, and records the outcome through the same ledger verbs the online path uses: done; refused with the processor’s words, never retried; or queued again with an exponential backoff (not_before) until the cap or the key’s window, then abandoned for the GM. A processor that replayed a saved failure under the key has spent that attempt: what it did is read back, and when nothing moved the instruction is queued again under a new attempt_id. The desk may take a queued one back (cancel_rail_instruction → cancelled), never one the drain is sending. The night audit drains whatever is queued, and its close lists what is still open.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.rail_instruction:read

Parameters

Path Parameters

required

string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

required

string

The watermark: an event seq (integer, canonical — the /v1/events cursor namespace) or an RFC3339 timestamp (resolved to the latest seq at or before it in the tenant’s stream).

Responses

200

The reconstructed as-of state.

application/json

object

required

string

events_applied

required

integer

required

string format: uuid

last_event_seq

required

integer

last_event_ts

required

string format: date-time

object_type

required

Allowed value: hospitality.rail_instruction

properties

required

Log-shaped folded bag: each entry is a typed {kind, value} object, a {redacted: [markings]} sentinel, or a {truncated_bytes: n} sentinel.

object

key

additional properties

any

Example

{
  "object_type": "hospitality.rail_instruction"
}

404

Object did not exist at the watermark (not yet created, or already deleted).

422

Malformed at, or the object’s history predates structural event images and cannot back a faithful reconstruction.