Skip to main content

Integration patterns

How an integration layer (for example MuleSoft in front of Salesforce Service Cloud, Experience Cloud and Agentforce) works with the order engine.

Import the contract​

Import the OpenAPI 3.0 document into Anypoint Exchange or your API catalogue. It contains every operation, request schema, error code and the captured examples on this site, and states the service commit it was generated from.

Calling the API​

ConcernPattern
AuthenticationHold the tenant token in the integration layer's secure properties; send it as Authorization: Bearer. One token per environment. See Authentication.
CorrelationSend X-Request-Id (or X-Correlation-Id) on every call with the integration layer's correlation id, and log the X-Request-Id the response returns. See Errors.
RetriesSend Idempotency-Key on every write, generated once per business action and reused on every retry. Retry on timeouts, 500 and 503 with exponential backoff; do not retry 4xx except 409 idempotency_in_progress. See Idempotency.
Conflicting editsRead the version, send If-Match on purchase order writes and expectedVersion elsewhere; on 412 or 409, read again and re-apply. See Concurrency.
ErrorsMap on code, not on message. Treat unknown codes by HTTP status.

Receiving changes​

Run a scheduled flow that polls the outbox:

  1. Read the last processed seq for the tenant from the integration layer's object store.
  2. GET /oms-ops/events?afterSeq=<seq>&limit=200.
  3. For each event, in order: deliver it (for example as a Salesforce platform event, or an update to a Service Cloud record), deduplicating on eventId.
  4. Store the last seq. If the page was full, poll again at once.

See Events overview.

Sending status events from specialist systems​

Specialist systems that the integration layer fronts (reservation, onboard, excursions, finance) report outcomes through POST /order-orchestration/events:

  • Use a stable messageId per event (the source system's event id) so redelivery is harmless.
  • Pass the correlationId of the outbound request being answered, or refs (tripId, poId, lineIds, externalRef).
  • Map the source system's status to a catalogue type (or send nativeStatus in data where the catalogue maps native statuses).
  • A 202 with outcome unmatched or rejected is logged for operations to reconcile or replay; it is not an error to retry.

Care and service views​

For a Service Cloud component, read GET /order-orchestration/trips/{tripId}/view (orders, lines, statuses, pending feedback, timeline) and GET /oms-ops/care/trips/{tripId} or GET /oms-ops/care/customers/{customerRef} (balance, payments, marks, service-recovery cases). Both are read models designed for one call per screen.

Advisor and agency channels​

Call with the channel's unscoped tenant token and record the agency on each record (createdBy.kind: agency, agencyRef). The Experience Cloud portal shows the advisor and agency from createdBy and attribution. Agency-partitioned tokens are not available; see Availability.