Operator API Documentation

• Introduction
• Base URL
• Security Headers
• Endpoints
  • 1. Auth API - Get Access Token
  • 2. Deposit Data
  • 3. Validate Phone Number
  • 4. Send SMS (OTP or Notifications)
• Error Codes

Introduction

The operator provides an API for DataMore to:

1. Obtain an access token for authentication.
2. Deposit data into a customer's account.
3. Validate phone numbers for eligibility.
4. Send SMS (e.g., OTPs or notifications) to customers.

For enhanced security, all API requests must include the following additional headers:

• X-Timestamp: A UNIX timestamp of the request.
• X-Signature: A hashed signature generated using a shared secret key.

Base URL

All requests will be sent to:

https://api.operator.com/v1

---

Security Headers

1. X-Timestamp

   • A required UNIX timestamp (seconds since epoch) representing the time of the request.
   • The timestamp ensures requests are valid within a specific time window (e.g., 5 minutes).

2. X-Signature

   • A required HMAC-SHA256 hash of the request payload and X-Timestamp, signed using the shared secret key provided by the operator.

   • The format of the signature generation:

     HMAC-SHA256(secret_key, X-Timestamp + JSON.stringify(request_payload))

   • Example in Node.js:

     const crypto = require("crypto");
     
     const secretKey = "your_shared_secret_key";
     const timestamp = Math.floor(Date.now() / 1000);
     const payload = JSON.stringify({
       phone_number: "1234567890",
       amount_mb: 500,
     });
     
     const signature = crypto
       .createHmac("sha256", secretKey)
       .update(timestamp + payload)
       .digest("hex");
     
     console.log("X-Timestamp:", timestamp);
     console.log("X-Signature:", signature);

---

Endpoints

1. Auth API - Get Access Token

• Description: Generates an access token to authenticate API requests.

• Endpoint: POST /auth/token

• Headers:

  {
    "Content-Type": "application/json",
    "X-Timestamp": "1672531200",
    "X-Signature": "<calculated_signature>"
  }

• Request Body:

  {
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }

• Response:

  • Success: 200 OK

    {
      "status": "success",
      "access_token": "eyJhbGciOiJIUzI1...",
      "expires_in": 3600
    }

  • Error: 401 Unauthorized

    {
      "status": "error",
      "message": "Invalid client credentials."
    }

---

2. Deposit Data

• Endpoint: POST /data/deposit

• Headers:

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer <OPERATOR_ACCESS_TOKEN>",
    "X-Timestamp": "1672531200",
    "X-Signature": "<calculated_signature>"
  }

• Request Body:

  {
    "phone_number": "1234567890",
    "amount_mb": 500,
    "transaction_id": "txn_123456",
    "description": "Reward for watching ads"
  }

• Response:

  • Success: 200 OK

    {
      "status": "success",
      "transaction_id": "txn_123456",
      "phone_number": "1234567890",
      "amount_mb": 500,
      "message": "Data successfully deposited."
    }

  • Error: 400 Bad Request

    {
      "status": "error",
      "message": "Invalid phone number or transaction ID."
    }

---

3. Validate Phone Number

• Endpoint: POST /phone/validate

• Headers:

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer <OPERATOR_ACCESS_TOKEN>",
    "X-Timestamp": "1672531200",
    "X-Signature": "<calculated_signature>"
  }

• Request Body:

  {
    "phone_number": "1234567890"
  }

• Response:

  • Success: 200 OK

    {
      "status": "success",
      "valid": true,
      "message": "Phone number is valid."
    }

  • Error: 400 Bad Request

    {
      "status": "error",
      "message": "Invalid phone number format."
    }

---

4. Send SMS (OTP or Notifications)

• Endpoint: POST /sms/send

• Headers:

  {
    "Content-Type": "application/json",
    "Authorization": "Bearer <OPERATOR_ACCESS_TOKEN>",
    "X-Timestamp": "1672531200",
    "X-Signature": "<calculated_signature>"
  }

• Request Body:

  {
    "phone_number": "1234567890",
    "message": "Your OTP is 123456",
    "sender_id": "DATAMORE"
  }

• Response:

  • Success: 200 OK

    {
      "status": "success",
      "message_id": "msg_78910",
      "phone_number": "1234567890",
      "message": "SMS successfully sent."
    }

  • Error: 400 Bad Request

    {
      "status": "error",
      "message": "Invalid phone number or message format."
    }

---

Error Codes

Code	Message	Description
400	Bad Request	The request is malformed or missing fields.
401	Unauthorized	Invalid or missing authentication token.
403	Forbidden	Invalid X-Signature or request timestamp.
404	Not Found	The requested resource does not exist.
500	Internal Server Error	An unexpected error occurred.