Kendez.Niksms.SDK.Delphi 1.0.0

Kendez.NikSms Delphi SDK

این پکیج برای اتصال آسان به وب‌سرویس پیامک Kendez.NikSms (نسخه REST و gRPC) در Delphi طراحی شده است.

This package provides an easy-to-use Delphi SDK for connecting to the Kendez.NikSms SMS web service (REST & gRPC).

نصب / Installation

پیش‌نیازها / Prerequisites

• Delphi 10.3 Rio یا بالاتر / Delphi 10.3 Rio or higher
• Windows 7 یا بالاتر / Windows 7 or higher
• اتصال به اینترنت / Internet connection

نصب / Installation

1. فایل‌های SDK را در پروژه خود کپی کنید / Copy SDK files to your project
2. واحدهای مورد نیاز را به پروژه اضافه کنید / Add required units to your project
3. از مثال‌های موجود استفاده کنید / Use the provided examples

ویژگی‌ها / Features

• اتصال به REST API و gRPC / Connect to REST API and gRPC
• قابل استفاده در پروژه‌های مختلف Delphi / Usable in various Delphi projects
• استفاده از آدرس‌های ثابت و قابل اعتماد / Use of fixed and reliable addresses
• پشتیبانی از تمام متدهای ارسال پیامک (تکی، گروهی، PTP، OTP) / Support for all SMS sending methods (single, group, PTP, OTP)
• دریافت وضعیت پیامک‌ها و اطلاعات پنل / Get SMS status and panel information
• مدیریت خطا و استثناها / Error and exception handling
• پشتیبانی کامل از Unicode / Full Unicode support

استفاده سریع / Quick Usage

REST Example

uses
  src.NiksmsRestClient,
  src.NiksmsTypes;

var
  Client: TNiksmsRestClient;
  Response: TNiksmsResponse;
begin
  Client := TNiksmsRestClient.Create('YOUR_API_KEY');
  try
    // ارسال پیامک تکی / Send single SMS
    Response := Client.SendSingle(
      '50004001',           // شماره فرستنده / Sender number
      '09123456789',        // شماره گیرنده / Recipient number
      'کد تایید شما: 1234'  // متن پیام / Message text
    );
    
    if Response.Success then
      WriteLn('پیام ارسال شد / Message sent')
    else
      WriteLn('خطا: ' + Response.Message);
    
    Response.Free;
    
    // دریافت اعتبار / Get credit
    Response := Client.GetCredit;
    if Response.Success then
      WriteLn('اعتبار دریافت شد / Credit retrieved');
    Response.Free;
  finally
    Client.Free;
  end;
end;

gRPC Example

uses
  src.NiksmsGrpcClient,
  src.NiksmsTypes;

var
  Client: TNiksmsGrpcClient;
  Response: TNiksmsResponse;
begin
  Client := TNiksmsGrpcClient.Create('YOUR_API_KEY');
  try
    // ارسال پیامک تکی / Send single SMS
    Response := Client.SendSingle(
      '50004001',           // شماره فرستنده / Sender number
      '09123456789',        // شماره گیرنده / Recipient number
      'کد تایید شما: 1234', // متن پیام / Message text
      'msg_001',            // شناسه پیام / Message ID
      '',                   // تاریخ ارسال / Send date
      1,                    // نوع ارسال / Send type
      1                     // نوع API / API type
    );
    
    if Response.Success then
      WriteLn('پیام ارسال شد / Message sent')
    else
      WriteLn('خطا: ' + Response.Message);
    
    Response.Free;
  finally
    Client.Free;
  end;
end;

مستندات کامل / Complete Documentation

متدهای ارسال پیامک / SMS Sending Methods

1. ارسال پیامک تکی / Send Single SMS

REST:

Response := Client.SendSingle(
  '50004001',                    // شماره فرستنده / Sender number
  '09123456789',                 // شماره گیرنده / Recipient number
  'سلام! این یک پیام تست است.',   // متن پیام / Message text
  'unique_id_123',               // شناسه یکتا (اختیاری) / Unique ID (optional)
  '2024-01-01T10:30:00',         // تاریخ ارسال (اختیاری) / Send date (optional)
  1                              // نوع ارسال (اختیاری) / Send type (optional)
);

gRPC:

Response := Client.SendSingle(
  '50004001',                    // شماره فرستنده / Sender number
  '09123456789',                 // شماره گیرنده / Recipient number
  'سلام! این یک پیام تست است.',   // متن پیام / Message text
  'unique_id_123',               // شناسه یکتا (اختیاری) / Unique ID (optional)
  '2024-01-01T10:30:00',         // تاریخ ارسال (اختیاری) / Send date (optional)
  1,                             // نوع ارسال (اختیاری) / Send type (optional)
  1                              // نوع API (اختیاری) / API type (optional)
);

2. ارسال پیامک گروهی / Send Group SMS

var
  Recipients: TList<TNiksmsRecipient>;
  I: Integer;
begin
  Recipients := TList<TNiksmsRecipient>.Create;
  try
    Recipients.Add(TNiksmsRecipient.Create('09123456789', '', 'msg_001'));
    Recipients.Add(TNiksmsRecipient.Create('09123456790', '', 'msg_002'));
    Recipients.Add(TNiksmsRecipient.Create('09123456791', '', 'msg_003'));
    
    Response := Client.SendGroup(
      '50004001',                    // شماره فرستنده / Sender number
      'پیام گروهی برای همه کاربران',  // متن پیام / Message text
      Recipients,                    // لیست گیرندگان / Recipients list
      '2024-01-01T10:30:00',         // تاریخ ارسال (اختیاری) / Send date (optional)
      1                              // نوع ارسال (اختیاری) / Send type (optional)
    );
  finally
    for I := 0 to Recipients.Count - 1 do
      Recipients[I].Free;
    Recipients.Free;
  end;
end;

3. ارسال PTP (هر نفر پیام متفاوت) / Send PTP SMS

var
  Recipients: TList<TNiksmsRecipient>;
  I: Integer;
begin
  Recipients := TList<TNiksmsRecipient>.Create;
  try
    Recipients.Add(TNiksmsRecipient.Create('09123456789', 'سلام علی', 'ptp_001'));
    Recipients.Add(TNiksmsRecipient.Create('09123456790', 'سلام رضا', 'ptp_002'));
    Recipients.Add(TNiksmsRecipient.Create('09123456791', 'سلام مریم', 'ptp_003'));
    
    Response := Client.SendPtp(
      '50004001',                    // شماره فرستنده / Sender number
      Recipients,                    // لیست گیرندگان با پیام‌های شخصی / Recipients with personalized messages
      '2024-01-01T10:30:00',         // تاریخ ارسال (اختیاری) / Send date (optional)
      1                              // نوع ارسال (اختیاری) / Send type (optional)
    );
  finally
    for I := 0 to Recipients.Count - 1 do
      Recipients[I].Free;
    Recipients.Free;
  end;
end;

4. ارسال پیامک OTP / Send OTP SMS

Response := Client.SendOtp(
  '50004001',                    // شماره فرستنده / Sender number
  '09123456789',                 // شماره گیرنده / Recipient number
  'کد تایید شما: 1234',          // متن پیام / Message text
  'otp_001',                     // شناسه پیام (اختیاری) / Message ID (optional)
  '2024-01-01T10:30:00',         // تاریخ ارسال (اختیاری) / Send date (optional)
  1                              // نوع ارسال (اختیاری) / Send type (optional)
);

متدهای دریافت اطلاعات / Information Methods

1. دریافت اعتبار / Get Credit

Response := Client.GetCredit;
if Response.Success then
  WriteLn('اعتبار باقی‌مانده: ' + Response.Data.ToString);

2. دریافت تاریخ انقضای پنل / Get Panel Expire Date

Response := Client.GetPanelExpireDate;
if Response.Success then
  WriteLn('تاریخ انقضای پنل: ' + Response.Data.ToString);

3. دریافت وضعیت پیامک‌ها / Get SMS Status

var
  MessageIds: TList<string>;
begin
  MessageIds := TList<string>.Create;
  try
    MessageIds.Add('msg_001');
    MessageIds.Add('msg_002');
    MessageIds.Add('msg_003');
    
    Response := Client.GetSmsStatus(MessageIds);
    if Response.Success then
      WriteLn('وضعیت پیامک‌ها: ' + Response.Data.ToString);
  finally
    MessageIds.Free;
  end;
end;

مدیریت خطا / Error Handling

uses
  src.NiksmsTypes;

try
  Response := Client.SendSingle(
    '50004001',
    '09123456789',
    'پیام تست'
  );
  
  if Response.Success then
    WriteLn('موفقیت: ' + Response.Data.ToString)
  else
    WriteLn('خطا: ' + Response.Message);
    
except
  on E: ENiksmsHttpException do
    WriteLn('خطای HTTP: ' + E.Message);
  on E: ENiksmsGrpcException do
    WriteLn('خطای gRPC: ' + E.Message);
  on E: ENiksmsValidationException do
    WriteLn('خطای اعتبارسنجی: ' + E.Message);
  on E: Exception do
    WriteLn('خطای عمومی: ' + E.Message);
end;

انواع خطا / Exception Types

• ENiksmsException: خطای پایه / Base exception
• ENiksmsHttpException: خطای HTTP / HTTP error
• ENiksmsGrpcException: خطای gRPC / gRPC error
• ENiksmsValidationException: خطای اعتبارسنجی / Validation error

انواع ارسال / Send Types

• 1: عادی / Normal
• 2: فلش / Flash
• 3: یونیکد / Unicode

انواع API / API Types

• 1: استاندارد / Standard
• 2: پریمیوم / Premium

نکات مهم / Important Notes

1. API Key: کلید API خود را از پنل کاربری دریافت کنید / Get your API key from user panel
2. شماره فرستنده: شماره فرستنده باید از شماره‌های مجاز پنل شما باشد / Sender number must be from your panel's authorized numbers
3. نوع ارسال: مقادیر مختلف SendType برای انواع مختلف پیامک / Different SendType values for different SMS types
4. تاریخ ارسال: فرمت تاریخ باید YYYY-MM-DDTHH:MM:SS باشد / Date format should be YYYY-MM-DDTHH:MM:SS
5. شناسه پیام: برای پیگیری وضعیت پیامک‌ها، شناسه یکتا تعیین کنید / Set unique ID to track SMS status
6. مدیریت حافظه: همیشه اشیاء Response را آزاد کنید / Always free Response objects
7. Unicode: SDK از Unicode کامل پشتیبانی می‌کند / SDK supports full Unicode

مثال‌های موجود / Available Examples

• examples/RestExample.pas: مثال کامل REST API / Complete REST API example
• examples/GrpcExample.pas: مثال کامل gRPC API / Complete gRPC API example
• examples/CompleteExample.pas: مثال ترکیبی REST و gRPC / Combined REST and gRPC example

ساختار پروژه / Project Structure

Kendez.Niksms.SDK.Delphi/
├── src/                          # کد منبع / Source code
│   ├── NiksmsTypes.pas          # انواع و کلاس‌های پایه / Base types and classes
│   ├── NiksmsModels.pas         # مدل‌های درخواست / Request models
│   ├── NiksmsRestClient.pas     # کلاینت REST / REST client
│   └── NiksmsGrpcClient.pas     # کلاینت gRPC / gRPC client
├── examples/                     # مثال‌ها / Examples
│   ├── RestExample.pas          # مثال REST / REST example
│   ├── GrpcExample.pas          # مثال gRPC / gRPC example
│   └── CompleteExample.pas      # مثال کامل / Complete example
├── proto/                        # فایل‌های Protocol Buffers / Protocol Buffers files
│   └── Service.proto            # تعریف سرویس gRPC / gRPC service definition
├── Kendez.Niksms.SDK.Delphi.dpr # فایل اصلی پروژه / Main project file
├── Kendez.Niksms.SDK.Delphi.dproj # فایل پروژه / Project file
└── README.md                    # مستندات / Documentation

پشتیبانی / Support

برای پشتیبانی و راهنمایی بیشتر با تیم فنی تماس بگیرید / For support and guidance, contact the technical team.

تلفن / Phone: 021-74552000
وب‌سایت / Website: https://webservice.niksms.com

نسخه / Version: 1.0.0
آخرین به‌روزرسانی / Last Update: 2024
مجوز / License: MIT