FareHarbor's Advanced Lightframe API can open the booking UI programmatically with FH.open(...).

Important options:

• shortname: required FareHarbor company shortname.
• flow: selects a booking flow. This is better than exposing the entire default company catalog.
• asn: affiliate shortname for affiliate attribution.
• asnRef: affiliate voucher/reference value.
• ref: online booking reference.
• language: booking flow language.
• view: 'items': opens item grid.
• view: 'all-availability': opens all-availability calendar.
• view: { item: 5 }: opens the calendar for a specific FareHarbor item.
• view: { item: 5, availability: 867901 }: opens directly to a specific availability.

Why this matters:

• The app can let users design/select a custom trip first.
• The app can map that choice to a FareHarbor item and, when known, a FareHarbor availability.
• The app can send the user into a FareHarbor-hosted checkout at the most specific supported point.
• ref, asnRef, and possibly affiliate tagging can carry our local trip/order reference into FareHarbor for reconciliation.

Concern enabled:

• This may avoid building payment and checkout ourselves while still making the booking feel driven by the custom app.

Concern not fully solved:

• Lightframe is still a FareHarbor-hosted checkout surface. It does not by itself create a fully invisible API checkout.
• Mobile/touch devices may redirect users to a secure FareHarbor page instead of opening the embedded frame.
• We still need a booking confirmation/reconciliation strategy after the user completes checkout.

The external API documentation index exposes API references for affiliates and software partners, plus booking and item webhooks.

Publicly indexed API examples show:

• availability lookup by company shortname and availability ID;
• headers X-FareHarbor-API-User and X-FareHarbor-API-App;
• booking creation under a selected availability;
• booking payload fields including contact, customers, customer type rates, custom field values, agent, desk, external ID, note, and voucher number.

Booking creation constraints visible in the public API examples:

• The availability must still be open.
• The availability must have enough capacity.
• Customer type rate capacities must support the requested customers.
• Exclusive customer type rates cannot be mixed incorrectly.
• Customer type rates must belong to the selected availability.

Why this matters:

• A real app implementation should select/check a FareHarbor availability immediately before checkout or booking creation.
• Our local app should store FareHarbor company.shortname, item.pk, availability.pk, customer_type_rate.pk, and local external_id.
• external_id, voucher_number, note, and custom field values look like the most important hooks for preserving custom trip context.

Concern enabled:

• If the target account/API permissions allow it, we may be able to create bookings from the app without manually entering them in the Dashboard.

Concern not fully solved:

• The docs we can see do not prove that API booking includes payment collection through FareHarbor for our use case.
• Affiliate API booking appears to expect the affiliate/platform to have its own payment gateway.
• We need actual API credentials and the target account's enabled permissions before assuming end-to-end automated booking.

FareHarbor's affiliate documentation says API bookings are aimed at high-traffic websites, OTAs, and marketplaces that actively promote activities.

Key affiliate API requirements listed by FareHarbor:

• Ability to take bookings with payments using a payment gateway.
• Developer team to build and test the integration.
• $50,000 trailing-12-month transaction value for API integration.
• Connection and annual maintenance fees listed as 1,000 EUR each.
• Signed and approved API/data license agreement.
• FHDN API requirements are higher and require being an existing FareHarbor API partner.

Why this matters:

• If we are building the provider's own custom booking app, the software-partner/direct-provider API path may be more relevant than the affiliate API path.
• If we are building a marketplace or reseller surface, affiliate rules, commission tracking, net payment settlement, and cancellation ownership become core product constraints.

Concern enabled:

• Affiliate references (asn, asnRef, voucher fields, reports) can help track bookings generated from our app.

Concern not fully solved:

• Affiliate API may be overkill or unavailable unless the business meets FareHarbor's commercial requirements.
• It may shift payment responsibility away from FareHarbor and onto our app/platform.

The affiliate Dashboard lets a reseller access live partner availability and manually create bookings, including agent, desk, voucher, guest details, notes, customer counts, required fields, add-ons, and payment-method-specific details.

Why this matters:

• The Dashboard is a good reference for the data model the app must eventually supply.
• It is also a fallback for exceptional cases or manual support.

Concern enabled:

• We can use the Dashboard to inspect how items, availability, custom fields, agents, desks, vouchers, and affiliate tags appear after a booking.

Concern not fully solved:

• Manual Dashboard entry is exactly what we want to avoid for normal custom in-app trip checkout.

FareHarbor's Website Cheatsheet says HTML/CSS/JS sites support Lightframe buttons, embeds, Lightframing embeds, and the FareHarbor stylesheet.

The standard Lightframe script is:

<script src="https://fareharbor.com/embeds/api/v1/?autolightframe=yes"></script>

For custom programmatic behavior, the Advanced Lightframe docs say to load the script without ?autolightframe=yes, then call FH.autoLightframe(...) or FH.open(...).

Why this matters:

• A Next.js/custom app can likely use the programmatic FH.open approach instead of relying only on plain FareHarbor links.
• We should treat Lightframe as a checkout adapter: local app collects trip context, maps it, then invokes FareHarbor with explicit options.

Concern enabled:

• This supports a proof of concept without full API booking access.

Concern not fully solved:

• Checkout completion callbacks/webhooks need to be verified. We should not assume the app will know the final booking status unless FareHarbor provides a webhook, redirect, report, API lookup, or reference-based reconciliation.