Technical Integration Guide

Overview

This guide provides the technical specifications for integrating WeatherIt's Quote Landing Page (QLP) into your booking system. Partners can choose from multiple integration methods based on their technical requirements and security needs.

Choosing Your Integration Method

WeatherIt supports three integration patterns. Choose the method that best fits your security requirements and technical capabilities.

Method A: API Retrieval Integration

The API Retrieval method keeps booking data on your servers and provides it to WeatherIt on-demand. This ensures URLs stay clean, data remains current, and you maintain full control over what information is shared.

Architecture Overview

sequenceDiagram
 autonumber
 participant Customer as Customer Browser
 participant QLP as WeatherIt QLP<br/>quote.weatherit.ai
 participant API as WeatherIt Backend<br/>api.weatherit.ai
 participant Partner as Your API Server<br/>api.yourcompany.com

 Customer->>QLP: Clicks link with ?partner=xxx&booking=yyy
 QLP->>API: Request booking details
 API->>Partner: GET /bookings/{booking_id}
 Partner-->>API: Return booking JSON
 API-->>QLP: Booking data + Quote
 QLP-->>Customer: Display coverage options

 Note over Customer,Partner: Customer completes purchase on QLP

How It Works

flowchart LR
 subgraph Step1[Step 1: Customer Action]
 A[Customer clicks<br/>WeatherIt link]
 end

 subgraph Step2[Step 2: Data Retrieval]
 B[QLP extracts<br/>partner & booking IDs]
 C[WeatherIt calls<br/>your API]
 D[Your API returns<br/>booking details]
 end

 subgraph Step3[Step 3: Quote Display]
 E[Quote generated<br/>from booking data]
 F[Customer sees<br/>coverage options]
 end

 A --> B --> C --> D --> E --> F

 style Step1 fill:#e8f4f8
 style Step2 fill:#f0f8e8
 style Step3 fill:#f8f0e8

URL Structure

The customer-facing URL is minimal and clean:

https://quote.weatherit.ai/?partner={partner_id}&booking={booking_id}

Example:

https://quote.weatherit.ai/?partner=a1b2c3d4-e5f6-7890-abcd-ef1234567890&booking=BOOK-3712

Required Parameters

Your API Endpoint Requirements

You must expose an API endpoint that WeatherIt can call to retrieve booking details.

Security Considerations

Method B: Secure Token Integration

Booking data is exchanged server-to-server for a token, ensuring information never appears in URLs or browser history.

Architecture Overview

sequenceDiagram
 autonumber

 participant Platform as Customer Platform
		participant Customer as Customer Browser
 participant YourWeb as Your Website<br/>yourcompany.com
 participant YourServer as Your Backend Server
 participant WTAPI as WeatherIt API<br/>api.weatherit.ai
 participant QLP as WeatherIt QLP<br/>quote.weatherit.ai

 Platform->>YourServer: Request token generation
 YourServer-->>Platform: Redirect URL with token
 YourWeb->>Customer: Redirect to QLP
 Customer->>QLP: Opens ?token=wt_tok_...
 QLP->>WTAPI: Validate token
 WTAPI-->>QLP: Booking data
 QLP-->>Customer: Display coverage options

Token Exchange Flow

flowchart TB
 subgraph CustomerAction[Customer Action]
 A[Customer clicks<br/>'Add Weather Protection']
 end

 subgraph ServerExchange[Server-to-Server Exchange]
 B[Your server sends<br/>booking data to WeatherIt]
 C[WeatherIt validates<br/>and stores data]
 D[Token generated<br/>wt_tok_xxx...]
 end

 subgraph CustomerRedirect[Customer Redirect]
 E[Your server redirects<br/>customer with token]
 F[Customer lands on QLP<br/>?token=wt_tok_xxx]
 end

 subgraph QuoteDisplay[Quote Display]
 G[Token validated<br/>Data retrieved]
 H[Quote displayed<br/>to customer]
 end

 A --> B --> C --> D --> E --> F --> G --> H

 style ServerExchange fill:#e8f8e8
 style CustomerAction fill:#f8f8e8
 style CustomerRedirect fill:#e8e8f8
 style QuoteDisplay fill:#f8e8f8

Token Request Specification

Endpoint:

POST https://api.weatherit.ai/v1/tokens
Authorization: Bearer {your_api_key}
Content-Type: application/json

Request Body:

{
 "partner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
 "booking_id": "BOOK-3712",
 "experience": {
 "name": "Harbour Bridge Climb",
 "type": "outdoor_activity",
 "location": {
 "latitude": -33.8523,
 "longitude": 151.2108,
 "suburb": "Sydney",
 "state": "NSW",
 "country": "AU"
 }
 },
 "coverage": {
 "start_date": "2025-03-15",
 "end_date": "2025-03-15",
 "amount": 250.00,
 "currency": "AUD"
 },
 "customer": {
 "email": "[email protected]",
 "first_name": "John",
 "last_name": "Smith"
 },
 "metadata": {
 "source": "checkout_page",
 "session_id": "sess_abc123"
 }
}

Success Response (201 Created):

{
 "token": "wt_tok_abc123def456ghi789jkl012mno345pqr678",
 "expires_at": "2025-01-20T12:15:00Z",
 "quote_url": "https://quote.weatherit.ai/?token=wt_tok_abc123def456..."
}

Error Response (400 Bad Request):

{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "Invalid request parameters",
 "details": {
 "coverage.start_date": "Must be a future date"
 }
 }
}

Customer Redirect

After receiving the token, redirect the customer to the quote page:

https://quote.weatherit.ai/?token=wt_tok_abc123def456ghi789jkl012mno345pqr678

Security Features

Method C: Native URL Integration

The Native URL method passes all booking details directly in the URL. This is the simplest integration requiring no backend changes, making it ideal for email campaigns, quick launches, or MVPs.

Architecture Overview

sequenceDiagram
 autonumber
 participant Source as Email / Website / App
 participant Customer as Customer Browser
 participant QLP as WeatherIt QLP<br/>quote.weatherit.ai

 Source->>Customer: Link with all parameters embedded
 Note over Source,Customer: ?partner=xxx&booking=yyy&lat=-33.85<br/>&lon=151.21&start=2025-03-15&amount=250...

 Customer->>QLP: Clicks link
 QLP->>QLP: Extract & validate parameters
 QLP->>QLP: Generate quote from URL data
 QLP-->>Customer: Display coverage options

 Note over Customer,QLP: Customer completes purchase

How It Works

flowchart LR
 subgraph Source[Link Source]
 A[Email Campaign]
 B[Booking Confirmation]
 C[Partner Website]
 end

 subgraph URL[URL Contains Everything]
 D[partner & booking IDs]
 E[Location coordinates]
 F[Dates & amount]
 G[Experience details]
 end

 subgraph QLP[WeatherIt QLP]
 H[Parse URL params]
 I[Validate data]
 J[Generate quote]
 K[Display options]
 end

 A --> D
 B --> D
 C --> D
 D --> E --> F --> G --> H --> I --> J --> K

 style Source fill:#f8e8f8
 style URL fill:#e8f8e8
 style QLP fill:#e8e8f8

URL Structure

https://quote.weatherit.ai/?partner={partner_id}
 &booking={booking_id}
 &lat={latitude}
 &lon={longitude}
 &start={start_date}
 &end={end_date}
 &amount={amount}
 &type={event_type}
 &experience={experience_name}

Parameter Reference

Required Parameters

Location Parameters

You must provide one of the following location options:

flowchart TD
 A[Location Required] --> B{Which format?}
 B -->|Recommended| C[Coordinates]
 B -->|Alternative| D[Address-Based]

 C --> E["lat=-33.8523<br/>lon=151.2108"]
 D --> F["suburb=Sydney<br/>state=NSW"]

 E --> G[Direct lookup<br/>Most accurate]
 F --> H[Geocoded by WeatherIt<br/>Good accuracy]

 style C fill:#d4edda
 style E fill:#d4edda

Option A: Coordinates (Recommended)

&lat=-33.8523&lon=151.2108

Option B: Address-Based

&suburb=Sydney&state=NSW

URL Construction Examples

Full URL (All Parameters)

https://quote.weatherit.ai/?partner=a1b2c3d4-e5f6-7890-abcd-ef1234567890&booking=BOOK-3712&lat=-33.8523&lon=151.2108&start=2025-03-15&end=2025-03-16&amount=250.00&type=outdoor_activity&experience=Harbour%20Bridge%20Climb&product_name=premium&currency=AUD&lang=en&country=AU

Address-Based URL

https://quote.weatherit.ai/?partner=a1b2c3d4-e5f6-7890-abcd-ef1234567890&booking=BOOK-3712&suburb=Sydney&state=NSW&start=2025-03-15&end=2025-03-15&amount=250.00&type=outdoor_activity&country=AU

URL Encoding Requirements

Event Types Reference

The type parameter specifies the category of experience being protected.

Validation & Error Handling

Parameter Validation Flow

The QLP validates all URL parameters before displaying the quote interface.

flowchart TD
 A[URL Received] --> B[Extract Parameters]
 B --> C{Valid Partner?<br/>3-100 chars}
 C -->|NO| C1[Error: invalid-partner]
 C -->|YES| D{Valid Booking?<br/>non-empty}
 D -->|NO| D1[Error: missing-params]
 D -->|YES| E{Integration Type?}

 E -->|Minimal params| F[API Retrieval Mode]
 F --> F1[Fetch from Partner API]

 E -->|Has lat/start/amount| G{Valid Location?<br/>coords OR suburb}
 G -->|NO| G1[Error: missing-params]
 G -->|YES| H{Valid Dates?<br/>ISO 8601 format}
 H -->|NO| H1[Error: invalid-format]
 H -->|YES| I{Valid Date Range?<br/>start ≤ end}
 I -->|NO| I1[Error: invalid-dates]
 I -->|YES| J{Valid Amount?<br/>positive number}
 J -->|NO| J1[Error: invalid-format]
 J -->|YES| K[Generate Quote]

 K --> L[Display Quote Page]
 F1 --> L

 C1 --> ERR[Error Page]
 D1 --> ERR
 G1 --> ERR
 H1 --> ERR
 I1 --> ERR
 J1 --> ERR

 style L fill:#d4edda
 style ERR fill:#f8d7da

Validation Rules Summary

Error Page Display

When validation fails, customers see a branded error page:

{
 "type": "invalid-dates",
 "title": "Invalid Date Range",
 "message": "The event start date is after the end date.",
 "details": "Please contact your booking provider for a corrected link."
}

API Error Codes

Error Code Categories

flowchart LR
 subgraph Auth[Authentication Errors<br/>401/403]
 A1[MISSING_BEARER_TOKEN]
 A2[INVALID_TOKEN]
 A3[TOKEN_EXPIRED]
 A4[PARTNER_INACTIVE]
 end

 subgraph Val[Validation Errors<br/>400/422]
 B1[LOCATION_ERROR]
 B2[INSUFFICIENT_ADVANCE_NOTICE]
 B3[DURATION_EXCEEDED]
 B4[NO_COVERAGE_AVAILABLE]
 end

 subgraph Biz[Business Logic Errors<br/>422]
 C1[QUOTE_EXPIRED]
 C2[NO_STATIONS_FOUND]
 C3[HIGH_RISK_DETECTED]
 end

 style Auth fill:#f8d7da
 style Val fill:#fff3cd
 style Biz fill:#cce5ff

Authentication Errors (401/403)

Validation Errors (400/422)

Business Logic Errors (422)

Support

For technical support or integration assistance: