API Documentation

Introduction

Welcome to the Trekka API documentation. The Trekka API enables seamless integration of intercity transport booking and management features into your application.

This documentation provides details on authentication, endpoints, data structures, and implementation best practices to help you build efficiently on the Trekka platform.

API Base URL

Production:

Development:

Authentication

Trekka API uses JWT (JSON Web Tokens) for authentication. Include your token in the Authorization header of all requests.

Get Token

First, register or login to receive a JWT token:

POST /api/auth/login
                                Content-Type: application/json

                                {
                                "email": "user@example.com",
                                "password": "your_password"
                                }

                                Response:
                                {
                                "success": true,
                                "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                                "user": { ... }
                                }
                            

Using the Token

Include the token in the Authorization header:

GET /api/bookings
                                Authorization: Bearer YOUR_JWT_TOKEN

API ENDPOINTS

Request Body:
                                        {
                                        "firstName": "John",
                                        "lastName": "Doe",
                                        "email": "john@example.com",
                                        "phone": "+2348012345678",
                                        "password": "securePassword123"
                                        }
                                

BOOKINGS ENDPOINTS

                                    
                                        Request Body:
                                    {
                                    "pickupLocation": {
                                        "address": "123 Main St, Lagos"
                                    },
                                    "dropoffLocation": {
                                        "address": "456 Park Ave, Abuja"
                                    },
                                    "pickupDateTime": "2024-12-25T10:00:00Z",
                                    "numberOfPassengers": 2,
                                    "companyId": "company_id_here"
                                    }
                                    
                                

PAYMENTS ENDPOINTS

Request Body:
                                    {
                                    "bookingId": "booking_id_here",
                                    "paymentMethod": "card"
                                    }

                                    Response:
                                    {
                                    "success": true,
                                    "paymentUrl": "https://checkout.paystack.com/...",
                                    "reference": "PAY-20241225-123456"
                                    }
                                

COMPANIES ENDPOINTS

BACKEND DATA FLOWS & LOGIC

This section explains how the Trekka back-end powers the above API endpoints.

BOOKING LIFECYCLE

• Search: User selects pickup and drop-off points.
• Match: Backend queries available companies/vehicle.
• Booking Creation: API saves booking with pending status.
• Payment: User initializes and completes payment.
• Confirmation: Partner or system confirms booking.
• Completion: Trip marked completed and rating recorded.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

{
                                "success": false,
                                "message": "Error description",
                                "errors": {
                                    "field": "Specific error details"
                                }
                                }
                            

Common Status Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required or failed
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

RATE LIMITS

To ensure fair usage, the API has the following rate limits:

• 100 requests per 15 minutes per IP address
• 1000 requests per day per authenticated user

Rate limit headers are included in all responses:

                                
                                    X-RateLimit-Limit: 100
                                    X-RateLimit-Remaining: 95
                                    X-RateLimit-Reset: 1640000000
                                
                            

WEBHOOKS

Web-hooks events notify your of updates in real-time.

Setting Up Webhooks

Contact our support team to configure webhook endpoints for your account.

Webhook Events

• booking.created
• booking.confirmed
• booking.completed
• payment.success
• payment.failed

1. HTTPS enforced for all API calls.
2. JWT tokens verified on each request.
3. Partner companies undergo KYC validation before activation.
4. Driver licenses and vehicle documents are verified via admin dashboard.
5. Payment data handled securely via Paystack or Flutterwave (no card data stored).
6. Compliant wwith NDPR (Nigeria Data Protection Regulations).

1. Current API version: v1.0
2. All future versions will follow semantic versioning (v1.1,v2).
3. Deprecations and breaking changes are announced (2) weeks before rollout.
4. Partners receive release notes via email or dashboard notifications.

1. "100% Verified Drivers" → backed by the driver verification system.
2. "Transparent Pricing" → pricing breakdown reflected in back-end data models.
3. Front-end field names (e.g,)

                               pickupLocation, pickupLocation
                             

   directly mirror back-end models to ensure consistency.

Need Help?

If you have questions or need assistance with the API:

• Email: developers@trekkatravels.com
• Visit our Contact Page
• Check our FAQ