README

A comprehensive PHP wrapper for the JamboJet NSK (New Skies) API - providing complete airline booking and operations functionality.

🚀 Overview

The JamboJet NSK API Wrapper is a production-ready PHP SDK that provides a complete interface to JamboJet's airline systems. Built with enterprise-grade architecture, comprehensive validation, and extensive error handling.

Key Features

✈️ Complete Booking Operations - Search, book, modify, cancel flights
👥 Passenger Management - Full lifecycle passenger operations with SSRs
💳 Payment Processing - Credit cards, fraud prevention, installments, refunds
🎫 Ticketing & Documents - E-tickets, boarding passes, receipts, invoices
💺 Ancillary Services - Seat selection, baggage, meals, special services
🏢 Organization Management - Multi-organization support (v1 & v2)
📋 Manifest Operations - Flight manifests, weight & balance, load sheets
🎟️ Voucher Management - Create, apply, track vouchers
📊 Trip Planning - Multi-city trips, fare rules, availability
⚙️ Configuration - Resources, settings, station management
🔐 Authentication - Token management, user sessions
🛡️ Enterprise Ready - Validation, error handling, logging

📋 Requirements

PHP 8.0 or higher
Composer
cURL extension
JSON extension
OpenSSL extension
Valid JamboJet NSK API credentials

📦 Installation

Install via Composer:

composer require santosdave/jambojet-laravel

⚙️ Configuration

Create a configuration file or set environment variables:

<?php
// config/jambojet.php

return [
    'base_url' => env('JAMBOJET_BASE_URL', 'https://api.jambojet.com/'),
    'subscription_key' => env('JAMBOJET_SUBSCRIPTION_KEY'),
    'timeout' => env('JAMBOJET_TIMEOUT', 30),
    'retry_attempts' => env('JAMBOJET_RETRY_ATTEMPTS', 3),
    'environment' => env('JAMBOJET_ENVIRONMENT', 'test'),

    'logging' => [
        'enabled' => env('JAMBOJET_LOG_ENABLED', true),
        'channel' => env('JAMBOJET_LOG_CHANNEL', 'stack'),
        'level' => env('JAMBOJET_LOG_LEVEL', 'info'),
    ],
];

Environment Variables

JAMBOJET_BASE_URL=https://jmtest.booking.jambojet.com/jm/dotrez/
JAMBOJET_SUBSCRIPTION_KEY=your-subscription-key-here
JAMBOJET_TIMEOUT=30
JAMBOJET_RETRY_ATTEMPTS=3
JAMBOJET_ENVIRONMENT=test

🚀 Quick Start

Initialize the Client

<?php

require 'vendor/autoload.php';

use SantosDave\JamboJet\JamboJetClient;

$client = new JamboJetClient([
    'base_url' => 'https://api.jambojet.com/',
    'subscription_key' => 'your-key-here'
]);

Basic Flight Search & Booking

<?php

// 1. Search for flights
$searchCriteria = [
    'origin' => 'NBO',
    'destination' => 'MBA',
    'departureDate' => '2024-12-15',
    'adult' => 1
];

$availability = $client->booking()->getAvailability($searchCriteria);

// 2. Select flight and get sell key
$sellKey = $availability['data']['trips'][0]['journeysAvailable'][0]['journeys'][0]['sellKey'];

// 3. Create booking
$bookingRequest = [
    'sellKeys' => [$sellKey],
    'passengers' => [
        [
            'name' => [
                'first' => 'John',
                'last' => 'Doe'
            ],
            'passengerTypeCode' => 'ADT',
            'gender' => 'Male'
        ]
    ],
    'contact' => [
        'emails' => ['john.doe@example.com'],
        'phoneNumbers' => ['+254700000000']
    ]
];

$booking = $client->booking()->createBooking($bookingRequest);
$recordLocator = $booking['data']['recordLocator'];

// 4. Process payment
$paymentData = [
    'paymentMethodType' => 'ExternalAccount',
    'paymentMethodCode' => 'MC',
    'accountNumber' => '5123456789012346',
    'expiration' => '2025-12',
    'accountHolderName' => 'John Doe',
    'paymentFields' => [
        ['fieldName' => 'VerificationCode', 'fieldValue' => '123']
    ]
];

$payment = $client->payment()->addPaymentToBooking($recordLocator, $paymentData);

// 5. Retrieve booking confirmation
$confirmation = $client->booking()->getBooking($recordLocator);

echo "Booking successful! PNR: " . $recordLocator;

📚 Documentation

Service Documentation

Comprehensive guides for each service module:

Authentication Service - Token management, user sessions
Booking Service - Flight search, booking creation, modifications
Booking Passengers Service - Passenger operations, SSRs, documents
Payment Service - Payment processing, refunds, installments
User Service - User registration, authentication, profiles
Trip Service - Trip planning, multi-city bookings
Resources Service - Airports, countries, currencies
Organizations Service v1 - Organization management
Organizations Service v2 - Enhanced organization features
Manifest Service - Flight manifests, load sheets
Voucher Service - Voucher creation and management
Settings Service - Configuration and settings
Messages Service - Message queue operations

Complete Workflows

Step-by-step implementation guides:

Basic Booking Flow - Search → Book → Pay → Ticket
Advanced Booking Flow - With ancillaries, modifications, groups

Additional Resources

Error Handling Guide - Exception handling and troubleshooting
Validation Reference - Input validation rules
Testing Guide - Unit and integration testing
API Reference - Complete endpoint documentation

🎯 Core Services Overview

Booking Operations

// Search flights
$availability = $client->booking()->getAvailability($criteria);

// Create booking
$booking = $client->booking()->createBooking($request);

// Modify booking
$modified = $client->booking()->updateBooking($recordLocator, $changes);

// Cancel booking
$cancelled = $client->booking()->cancelBooking($recordLocator);

// Retrieve booking
$details = $client->booking()->getBooking($recordLocator);

Passenger Management

// Add passenger
$passenger = $client->bookingPassengers()->addPassenger($recordLocator, $passengerData);

// Add SSR (Special Service Request)
$ssr = $client->bookingPassengers()->addSSR($recordLocator, $ssrData);

// Update passenger information
$updated = $client->bookingPassengers()->updatePassenger($recordLocator, $passengerId, $updates);

// Add travel documents
$document = $client->bookingPassengers()->addTravelDocument($recordLocator, $passengerId, $documentData);

Payment Processing

// Add payment
$payment = $client->payment()->addPaymentToBooking($recordLocator, $paymentData);

// Process refund
$refund = $client->payment()->processRefund($recordLocator, $refundData);

// Set up installments
$installment = $client->payment()->createInstallmentPlan($recordLocator, $planData);

// Get payment status
$status = $client->payment()->getPaymentStatus($recordLocator);

Ancillary Services

// Seat selection
$seat = $client->booking()->assignSeat($recordLocator, $seatData);

// Add baggage
$baggage = $client->booking()->addBaggage($recordLocator, $baggageData);

// Add meal
$meal = $client->booking()->addMeal($recordLocator, $mealData);

// Add insurance
$insurance = $client->booking()->addInsurance($recordLocator, $insuranceData);

🛡️ Error Handling

The wrapper provides comprehensive exception handling:

<?php

use SantosDave\JamboJet\Exceptions\JamboJetApiException;
use SantosDave\JamboJet\Exceptions\JamboJetValidationException;
use SantosDave\JamboJet\Exceptions\JamboJetAuthenticationException;

try {
    $booking = $client->booking()->createBooking($request);
} catch (JamboJetValidationException $e) {
    // Handle validation errors (400)
    echo "Validation Error: " . $e->getMessage();
    $errors = $e->getValidationErrors();
} catch (JamboJetAuthenticationException $e) {
    // Handle authentication errors (401)
    echo "Authentication Error: " . $e->getMessage();
} catch (JamboJetApiException $e) {
    // Handle general API errors
    echo "API Error: " . $e->getMessage();
    echo "Status Code: " . $e->getStatusCode();
}

🧪 Testing

Run the test suite:

# Run all tests
composer test

# Run specific test suite
composer test -- --testsuite=Unit

# Run with coverage
composer test -- --coverage-html coverage/

📊 API Coverage

Module	Coverage	Endpoints
Booking	98%	120+
Booking Passengers	95%	80+
Payment	100%	45+
Organizations (v1)	100%	25+
Organizations (v2)	100%	30+
Manifest	100%	35+
Voucher	100%	20+
Trip	100%	15+
Resources	100%	40+
Settings	100%	25+
User	98%	35+
Messages	100%	10+

Overall: 97%+ coverage across all modules

🔒 Security

Reporting Security Issues

If you discover a security vulnerability, please email: security@santosdave.com

Do not create public GitHub issues for security vulnerabilities.

Security Best Practices

Always use HTTPS in production
Store API credentials securely (environment variables, vaults)
Implement rate limiting
Enable request/response logging for audit trails
Regularly update dependencies
Use token refresh mechanisms
Validate all input data
Sanitize sensitive data in logs

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

# Clone repository
git clone https://github.com/santosdave/jambojet-nsk-api.git
cd jambojet-nsk-api

# Install dependencies
composer install

# Copy environment file
cp .env.example .env

# Run tests
composer test

Coding Standards

# Check code style (PSR-12)
composer lint

# Fix code style
composer lint:fix

# Run static analysis
composer analyse

📝 Changelog

See CHANGELOG.md for release notes and version history.

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

👨‍💻 Author

Santos Dave

GitHub: @santosdave
Email: santosdave86@gmail.com

🙏 Acknowledgments

JamboJet Airways for API access and documentation
NSK (New Skies) Platform by Navitaire
PHP Community for excellent tooling

📞 Support

📧 Email: support@santosdave.com
🐛 Issues: GitHub Issues
📖 Documentation: Full Documentation
💬 Discussions: GitHub Discussions

🗺️ Roadmap

GraphQL API support
WebSocket real-time updates
CLI tool for testing
Postman collection
Docker development environment
Multi-language support
Advanced caching strategies
Webhook event handling

Made with ❤️ by Santos Dave

⭐ Star this repo if you find it useful!

santosdave / jambojet-laravel

Maintainers

Details