Sign In Get Started

API Documentation

Build transportation features into your application

Introduction

Welcome to the Trekka API

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.

Test the API

Check if the API is running.

GET /api/ping

API Base URL

Production

https://api.trekkatravels.com/api

Development

http://localhost:5000/api

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

POST /api/auth/register

Register a new account.

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

Login and get a JWT token.

GET /api/auth/me

Retrieve the current user profile (requires authentication).

Bookings Endpoints

POST /api/bookings

Create a new booking.

                                        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"
}
GET /api/bookings

Get all user bookings.

GET /api/bookings/:id

Get booking details.

POST /api/bookings/:id/cancel

Cancel a booking.

Payments Endpoints

POST /api/finance/payments/initialize

Initialize payment.

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

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

Verify payment.

Companies Endpoints

GET /api/companies

Get a list of transport companies.

GET /api/companies/:id

Get details of a specific company.

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 and vehicles.
  • 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:

Headers

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

Webhooks

Webhook events notify you 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

Security & Verification

  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 the admin dashboard.
  5. Payment data is handled securely via Paystack or Flutterwave without storing card data.
  6. Compliant with NDPR (Nigeria Data Protection Regulations).

Versioning & Maintenance

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

User-Facing Alignment

  1. “100% Verified Drivers” is backed by the driver verification system.
  2. “Transparent Pricing” is reflected in the back-end data models.
  3. Front-end field names such as pickupLocation mirror back-end models for consistency.

Need Help?

If you have questions or need assistance with the API: