Skip to main content

FuzeMetrix IBA Integration - Private

 

Overview​

The IBA validates members when they check in at wind tunnels using the FuzeMetrix (FM) booking system.

The integration performs the following 4 tasks:

  1. Member Validation: Exposes an endpoint where FM can validate an IBA member using a member's member_id and PIN code.
  2. Member Data: Exposes an endpoint where FM can retrieve member data for an individual member
  3. Tunnel Booking Data: Exposes an endpoint where FM can send the flight booking data for storage in the IBA system
  4. Logbook Management: Based on the status of the member the system will create a logbook entry for the member. It also allows members to easily update the flight time associated with a booking via an email link and web form
 

Business Logic​

Business logic is mostly handled on the FM side apart from logbook entries associated with the booking.

Creating a Logbook Entry

Logbook entries are only created for members that have an active flyer_currency.

Email Triggers

When a booking is created through the FuzeMetrix integration, the system sends different emails based on the member's currency status:

  1. Active Currency Status:

    • Creates a logbook entry for the flight time
    • Sends an "active" email template (logbook/external-time-entry-active)
    • Email includes a link for the member to update their flight time
    • The link contains a unique token that allows one-time access to modify the booking

  2. Inactive Currency Status (Not current):

    • Does NOT create a logbook entry (to prevent automatic recurrency)
    • Sends an "inactive" email template (logbook/external-time-entry-inactive)
    • Notifies the member that they need to complete recurrency before their time can be logged
 

Important Notes on Data Types​

  1. Date Format: All dates must be Unix timestamps in seconds (not milliseconds)
  2. Header Names:
    • Use client-id for POST endpoints
  3. Token Generation: Must use HMAC SHA-256 with the exact JSON structure of the request body
  4. Optional Fields: registration_id can be omitted or set to 0
 

Error Handling​

HTTP Status Codes​

  • 200: Success - Request processed successfully
  • 400: Bad Request - Missing client ID or token headers
  • 403: Forbidden - Invalid HMAC token/unauthorized access
  • 404: Not Found - Invalid client ID/client not found
  • 422: Unprocessable Entity - Validation failed/missing required fields
  • 500: Internal Server Error - Server-side error occurred

Error Response Format​

{
  "valid": false,
  "message": "Error description"
}

Common Error Messages​

  • "Please provide client id for access the data"
  • "Please provide token to access the resource"
  • "Client id does not match with data"
  • "Your token does not match"
  • "Missing required fields: [field_list]"
  • "Member not found"
  • "Invalid PIN"
  • "Invalid member ID"
  • "Tunnel not found"
  • "Booking already exits"
  • "Entry already exists"
  • "Email is required"
  • "Email already exists"
  • "Booking not found"

Success Messages​

  • "Member validated successfully"
  • "User created successfully"
  • "User edited successfully"
  • "User deleted successfully"
  • "Token generated successfully"
  • "Booking created successfully"
  • "Booking updated successfully"
 

Authentication​

HMAC SHA-256 Token Authentication​

All API requests require HMAC authentication using SHA-256.

Required Headers:

  • client-id: Unique identifier for the FuzeMetrix client
  • token: HMAC SHA-256 hash of the request body using the client's secret key

Token Generation:

crypto.createHmac('SHA256', clientSecret).update(JSON.stringify(requestBody)).digest('hex')
 

API Endpoints (External-Facing)​

Base URL https://api.tunnelflight.com/api/external/fuse-metrix

1. PIN Validation​

Validates member using their member_id and pin. Use this to check PIN before proceeding with booking creation.

Endpoint: POST /api/external/fuse-metrix/validate-pin (validation only)

Headers:

client-id: your-client-id
Authorization: generated-hmac-token
Content-Type: application/json

Request Body:

{
  "member_id": 60649,
  "member_pin": "67510"
}

Response (Success - 200):

{
  "valid": true,
  "message": "Member validated successfully"
}

Response (Error - 422):

{
  "valid": false,
  "message": "Invalid PIN" // or "Member not found"
}

Flow Diagram​

View Flow Diagram
 

2. Member Data Endpoint​

Retrieves member information for display or verification purposes.

Endpoint: POST /api/external/fuse-metrix/get-member

Request Body:

{
  "member_id": 60649
}

Headers:

client-id: your-client-id
Authorization: any-valid-token

Note: client-id is lowercase with no hyphen for this legacy endpoint

Request Body: None (GET request)

Response (Success - 200):

{
  "valid": true,
  "member_id": 40,
  "date_of_birth": "1979-06-08T15:28:42.000Z",
  "screen_name": "Rusty Lewis",
  "role_name": "Examiner",
  "real_name": "Rusty Lewis",
  "tunnel_name": "Support Center",
  "is_coach": true,
  "paymentStatus": "Not required",
  "total_flight_time": "0:53",
  "last_flight": "2025-04-08T07:40:00.000Z",
  "currency_renewal_date_flyer": "2025-10-05T07:40:00.000Z",
  "flyerLevels": {
      "level1": "Yes",
      "static": "Pro",
      "dynamic": "Pro",
      "formation": "Level 4"
  },
  "flyer_currency_status": "Active"
}

Response (Error - 422):

{
  "valid": false,
  "message": "Member not found"
}

Flow Diagram​

View Flow Diagram
 

3. Create Booking Entry​

Registers a new checkin / booking at the wind tunnel.

Endpoint: POST /api/external/fuse-metrix/create-booking

Path Parameters: None

Headers:

client-id: your-client-id
Authorization: generated-hmac-token
Content-Type: application/json

Request Body:

{
  "member_id": 60649,
  "purchase_id": 215312,
  "purchase_date": 1744131450,
  "flight_date": 1744098000,
  "minutes_booked": 9,
  "product_id": 12893,
  "tunnel_id": 25, // uses FM tunnel ID 
  "checkin_time": 1744098000
}

Note: All dates are Unix timestamps in seconds.

Response (Success - 200):

{
  "valid": true,
  "message": "Booking created successfully"
}

Response (Error - 422):

{
  "valid": false,
  "message": "Member not found"
}

Flow Diagram​

View Flow Diagram
 

API Endpoints (Internal-Facing)​

The following endpoints are for internal IBA use only and are not exposed to FuzeMetrix:

Customer Facing​

  • POST /api/external/fuse-metrix/update-booking - Update a member's logbook entry

Admin Operations​

  • POST /api/external/fuse-metrix/op - Create FuzeMetrix integration user
  • PUT /api/external/fuse-metrix/op - Edit FuzeMetrix user
  • DELETE /api/external/fuse-metrix/op/:fuse_metrix_id - Delete FuzeMetrix user
  • GET /api/external/fuse-metrix/op/ - List all FuzeMetrix users
  • GET /api/external/fuse-metrix/op/:fuse_metrix_id - Get single FuzeMetrix user
  • POST /api/admin/reports/external/fuse-metrix/history - Get FuzeMetrix History List
  • POST /api/admin/reports/external/fuse-metrix/bookings - Get FuseMetrix Booking List

These require IBA admin JWT authentication.

 

Database Tables​

-- Create syntax for TABLE 'fuse_metrix'
CREATE TABLE `fuse_metrix` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `email` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
  `clientId` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL,
  `secret` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL,
  `created_by` int DEFAULT NULL,
  `created_at` int DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=12 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

-- Create syntax for TABLE 'fuse_metrix_booking'
CREATE TABLE `fuse_metrix_booking` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `member_id` int DEFAULT NULL,
  `purchase_id` int DEFAULT NULL,
  `registration_id` int DEFAULT NULL,
  `purchase_date` int DEFAULT NULL,
  `flight_date` int DEFAULT NULL,
  `minutes_booked` int DEFAULT NULL,
  `product_id` int DEFAULT NULL,
  `tunnel_id` int DEFAULT NULL,
  `checkin_time` int DEFAULT NULL,
  `auth_token` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=7 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

-- Create syntax for TABLE 'fuse_metrix_history'
CREATE TABLE `fuse_metrix_history` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `client_id` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
  `body` text CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci,
  `status` varchar(11) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
  `error_msg` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
  `ips` varchar(130) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci DEFAULT NULL,
  `path` varchar(100) COLLATE utf8mb4_general_ci DEFAULT NULL,
  `created_at` int DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=48 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

-- Create syntax for TABLE 'fuse_metrix_tunnel_mapping'
CREATE TABLE `fuse_metrix_tunnel_mapping` (
  `id` int unsigned NOT NULL AUTO_INCREMENT,
  `tunnel_id` int DEFAULT NULL,
  `fuse_metrix_id` int DEFAULT NULL,
  `fuse_metrix_pos_id` int DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=40 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
 

Implementation Details​

Code Structure​

  • Routes: api/src/features/connector/fuse-metrix/routes/index.js
  • Controller: api/src/features/connector/fuse-metrix/controller/controller.js, api/src/features/connector/shared/controller/base.controller.js
  • Service: api/src/features/connector/shared/service/base.service.js, api/src/features/connector/fuse-metrix/service/service.js
  • Repository: api/src/features/connector/shared/repository/index.js
  • Models: api/src/features/connector/shared/model/index.js
  • Middleware: api/src/features/connector/shared/middlewares/req-validate.js
  • Route Mounting: Connector routes mounted at api/src/features/connector in api/src/routes/index.js

Email Notifications​

When a booking is created:

  • Active/N/A Currency Status: Creates logbook entry and sends email with update link
  • Inactive Currency Status: Sends notification email only
  • Email templates: #lang/{lang}/email/logbook/external-time-entry-{active|inactive}
 

Interactive Swagger UI​

External FuzeMetrix API

Interactive documentation for the external FuzeMetrix integration endpoints that partners use:

Interactive Swagger UI - Internal API​

Internal FuzeMetrix Admin API

Interactive documentation for internal admin endpoints used to manage FuzeMetrix integration users: