🔑 Identity verification (Authentication)

The portal uses a system HTTP Basic Auth With support for two levels of authentication:

📌 Level 1: API authentication (for external systems)

  • Required data: Username:Password:AppId (three parts separated by colons)
  • Encoding: Converting text to Base64
  • Header: Authorization: Basic [Token]
  • Also supports: X-Authorization: Basic [Token] (For environments that rewrite the Authorization header)

📌 Second level: Control Panel authentication (UI Admin)

  • Required data: Username:Password (two parts only)
  • Verification is done against credentials stored in appsettings.json
  • Grants valid complete Admin privileges

💻 Example of encryption

# تشفير البيانات بصيغة Base64
TOKEN=$(echo -n "myuser:mypass:1" | base64)
# النتيجة: bXl1c2VyOm15cGFzczox

# استخدام التوكن في الطلب
curl -H "Authorization: Basic $TOKEN" https://api.wss.sa/api/v1/...
// تشفير البيانات بصيغة Base64
const credentials = "myuser:mypass:1";
const token = btoa(credentials);
// النتيجة: "bXl1c2VyOm15cGFzczox"

// استخدام التوكن
fetch(url, {
  headers: { "Authorization": `Basic ${token}` }
});
// تشفير البيانات بصيغة Base64
var credentials = "myuser:mypass:1";
var token = Convert.ToBase64String(Encoding.UTF8.GetBytes(credentials));
// النتيجة: "bXl1c2VyOm15cGFzczox"

client.DefaultRequestHeaders.Add("Authorization", $"Basic {token}");

📱 1. Sending mobile messages (SMS)

POST /api/v1/Notification/SMS

📋 Parameters

fieldTypeDescription
appId *IntUnique application code
message *ObjectMessage object
receiver *StringFuture number (9665xxxxxxxx)
message *StringText message content

💻 Code samples

curl -X POST "https://api.wss.sa/api/v1/Notification/SMS" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "appId": 1,
  "message": {
    "receiver": "9665xxxxxxxx",
    "message": "محتوى الرسالة النصية"
  }
}'
using System.Net.Http.Json;

var client = new HttpClient();
client.BaseAddress = new Uri("https://api.wss.sa/");
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");

var payload = new {
    appId = 1,
    message = new {
        receiver = "9665xxxxxxxx",
        message = "محتوى الرسالة النصية"
    }
};

var response = await client.PostAsJsonAsync("api/v1/Notification/SMS", payload);
if (response.IsSuccessStatusCode) {
    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}
<?php
$url = "https://api.wss.sa/api/v1/Notification/SMS";
$data = [
    "appId" => 1,
    "message" => [
        "receiver" => "9665xxxxxxxx",
        "message" => "محتوى الرسالة"
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Basic [TOKEN]",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
import requests

url = "https://api.wss.sa/api/v1/Notification/SMS"
headers = {
    "Authorization": "Basic [TOKEN]",
    "Content-Type": "application/json"
}
payload = {
    "appId": 1,
    "message": {
        "receiver": "9665xxxxxxxx",
        "message": "رسالة تجريبية"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
import okhttp3.*;

OkHttpClient client = new OkHttpClient();
MediaType JSON = MediaType.parse("application/json; charset=utf-8");
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"9665xxxx\", \"message\": \"Test\"}}";

RequestBody body = RequestBody.create(json, JSON);
Request request = new Request.Builder()
  .url("https://api.wss.sa/api/v1/Notification/SMS")
  .addHeader("Authorization", "Basic [TOKEN]")
  .post(body)
  .build();

try (Response response = client.newCall(request).execute()) {
    System.out.println(response.body().string());
}

💬 2. WhatsApp sending

POST /api/v1/Notification/WhatsApp
fieldDescription
appId *Application code
message.receiver *WhatsApp number in international format
message.templateNameTemplate name (if using templates)
message.bodyParamsTemplate variables are separated by a comma
curl -X POST "https://api.wss.sa/api/v1/Notification/WhatsApp" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "appId": 1,
  "message": {
    "receiver": "9665xxxxxxxx",
    "templateName": "otp_verification",
    "bodyParams": "1234, 5"
  }
}'
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");

var payload = new {
    appId = 1,
    message = new {
        receiver = "9665xxxxxxxx",
        templateName = "otp_verification",
        bodyParams = "1234, 5"
    }
};

await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/WhatsApp", payload);
<?php
$url = "https://api.wss.sa/api/v1/Notification/WhatsApp";
$data = [
    "appId" => 1,
    "message" => [
        "receiver" => "9665xxxxxxxx",
        "templateName" => "otp_verification",
        "bodyParams" => "1234, 5"
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Basic [TOKEN]", "Content-Type: application/json"]);
$response = curl_exec($ch);
?>
import requests

url = "https://api.wss.sa/api/v1/Notification/WhatsApp"
payload = {
    "appId": 1,
    "message": {
        "receiver": "9665xxxxxxxx",
        "templateName": "otp_verification",
        "bodyParams": "1234, 5"
    }
}

requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})
import okhttp3.*;

OkHttpClient client = new OkHttpClient();
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"9665xx\", \"templateName\": \"otp\"}}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

Request request = new Request.Builder()
  .url("https://api.wss.sa/api/v1/Notification/WhatsApp")
  .addHeader("Authorization", "Basic [TOKEN]")
  .post(body)
  .build();

📧 3. Send an email

POST /api/v1/Notification/Email
fieldDescription
appId *Application code
message.receiver *Recipient's email
message.subject *Message title
message.message *Content (HTML supported)
curl -X POST "https://api.wss.sa/api/v1/Notification/Email" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "appId": 1,
  "message": {
    "receiver": "user@domain.com",
    "subject": "تنبيه من النظام",
    "message": "<h1>محتوى HTML</h1>"
  }
}'
using System.Net.Http.Json;

var client = new HttpClient();
var data = new {
    appId = 1,
    message = new {
        receiver = "user@domain.com",
        subject = "Hello",
        message = "<h1>World</h1>"
    }
};

await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/Email", data);
<?php
$url = "https://api.wss.sa/api/v1/Notification/Email";
$data = [
    "appId" => 1,
    "message" => [
        "receiver" => "user@domain.com",
        "subject" => "Subject",
        "message" => "Body"
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Basic [TOKEN]", "Content-Type: application/json"]);
$response = curl_exec($ch);
?>
import requests

url = "https://api.wss.sa/api/v1/Notification/Email"
payload = {
    "appId": 1,
    "message": {
        "receiver": "user@domain.com",
        "subject": "Hello",
        "message": "Content"
    }
}

requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})
import okhttp3.*;

OkHttpClient client = new OkHttpClient();
String json = "{\"appId\": 1, \"message\": {\"receiver\": \"u@d.com\"}}";
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

Request request = new Request.Builder()
  .url("https://api.wss.sa/api/v1/Notification/Email")
  .addHeader("Authorization", "Basic [TOKEN]")
  .post(body)
  .build();

🔔 4. Phone Notifications (FCM Push)

POST /api/v1/Notification/FCM

📋 Parameters

fieldTypeDescription
appId *IntUnique application code
message *ObjectNotification object
receiver *StringFCM Device Token of the target device
message *StringNotice content

💻 Code samples

curl -X POST "https://api.wss.sa/api/v1/Notification/FCM" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '{
  "appId": 1,
  "message": {
    "receiver": "fcm_device_token_here",
    "message": "لديك إشعار جديد"
  }
}'
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");

var payload = new {
    appId = 1,
    message = new {
        receiver = "fcm_device_token_here",
        message = "لديك إشعار جديد"
    }
};

await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/FCM", payload);
import requests

url = "https://api.wss.sa/api/v1/Notification/FCM"
payload = {
    "appId": 1,
    "message": {
        "receiver": "fcm_device_token_here",
        "message": "لديك إشعار جديد"
    }
}

requests.post(url, json=payload, headers={"Authorization": "Basic [TOKEN]"})

📨 5. Send bulk emails

POST /api/v1/Notification/Emails

This Endpoint allows sending a group of emails at once. Each message is processed independently—the failure of one message does not affect the rest.

📋 Parameters

fieldTypeDescription
demandArrayAn array of EmailPublisher objects
appId *IntApplication code
message.receiver *StringRecipient's email
message.subject *StringMessage title
message.message *StringContent (HTML supported)
message.emailCCStringCarbon copy (separated by semicolons)
message.emailBCCStringHidden carbon copy

💻 Code samples

curl -X POST "https://api.wss.sa/api/v1/Notification/Emails" \
-H "Authorization: Basic [TOKEN]" \
-H "Content-Type: application/json" \
-d '[
  {
    "appId": 1,
    "message": {
      "receiver": "user1@domain.com",
      "subject": "تنبيه",
      "message": "<h1>مرحباً</h1>"
    }
  },
  {
    "appId": 1,
    "message": {
      "receiver": "user2@domain.com",
      "subject": "تنبيه",
      "message": "<h1>أهلاً</h1>"
    }
  }
]'
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");

var emails = new[] {
    new {
        appId = 1,
        message = new { receiver = "user1@domain.com", subject = "تنبيه", message = "مرحباً" }
    },
    new {
        appId = 1,
        message = new { receiver = "user2@domain.com", subject = "تنبيه", message = "أهلاً" }
    }
};

await client.PostAsJsonAsync("https://api.wss.sa/api/v1/Notification/Emails", emails);

🔍 6. Inquire about the status of the message

GET /api/v1/Settings/MessageStatus?appId={appId}&msgId={msgId}&messageType={type}

You can query the status of any sent message using the message identifier (MsgId) returned upon sending.

📋 Parameters

fieldTypeDescription
appId *IntApplication code
msgId *GuidMessage ID (returned on sending)
messageType *EnumChannel type: SMS=1, WhatsApp=2, Email=3

💻 Code samples

curl -X GET "https://api.wss.sa/api/v1/Settings/MessageStatus?appId=1&msgId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&messageType=1" \
-H "Authorization: Basic [TOKEN]"
using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Basic [TOKEN]");

var appId = 1;
var msgId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
var messageType = 1; // SMS

var url = $"https://api.wss.sa/api/v1/Settings/MessageStatus?appId={appId}&msgId={msgId}&messageType={messageType}";
var response = await client.GetAsync(url);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

📊 7. Response codes

The system returns a standardized response code ServiceResponse Shows the status of the process. Here are all possible codes:

✅ Success codes

CodeThe constantDescription
100SuccessThe request has been sent successfully and has been placed in the waiting list

⚠️ Verification codes

CodeThe constantDescription
11ExpireQuoataThe quota is insufficient — the application balance has been exhausted
15AppNotActiveThe application is inactive — it has been disabled by the administrator
16SMSSettingNotActiveMobile messaging setting is not functional for this app
17EmailSettingNotActiveEmail setting is not functional for this application
18WhatsAppSettingNotActiveWhatsApp messaging setting is not functional for this app
19PushNotificationSettingNotActiveThe phone notifications setting is not functional for this app

❌ Error codes

CodeThe constantDescription
-1ExceptionInternal system error (database or message server is down)
-2FailDBSavedFailed to save message to database
-3NotFoundThe application (AppId) does not exist in the system
-4FailDBUpdateThe message was sent but the status update in the database failed
-5PushFailFailed to send message to queue (RabbitMQ timeout)
-6ConnectionNotExistsNo connection to message server (RabbitMQ)
-7BadParameterThe order data is incorrect or missing

🏗️ System Architecture

The gateway is based on an architecture Microservices Flexible using RabbitMQ.

Client
API (Publisher)
RabbitMQ


Consumers (Workers)

📄 Technical documents

All official documents of the project - you can view or download any document

📋
SRS

Software Requirements Specification

System Requirements Specification - includes all functional and non-functional requirements for the system

🏗️
HLD

High Level Design

Overall system design - includes the main components, their relationships, and the overall architecture

🔧
LLD

Low Level Design

Detailed design of the system - includes details of the classes, modules, and algorithms used

💻
IMPL

Implementation

Implementation document - details the development environment, technologies used, and the actual implementation mechanism of the system

🔗
API + DB

API Docs + DB Docs

Documentation of programming interfaces and databases - details of endpoints, tables, and relationships

🚀
DEPLOY

Deployment

Deployment and Deployment Document - Steps for deployment to production, test, and infrastructure environments

📊
FLOW

Flow Diagram

Process Flow Diagram - Visually shows the flow of data and processes within the system

🔄
SEQ

Sequence Diagram

Sequence diagram - shows the chronological order of interactions between different components of a system

Document review