راهنمای کامل ارسال پیامک در زبان دلفی

زبان برنامه‌نویسی دلفی (Delphi) یکی از زبان‌های قدرتمند، شی‌ءگرا و ساختاریافته است که برای توسعه نرم‌افزارهای کاربردی دسکتاپ، موبایل و وب استفاده می‌شود. این زبان بر پایه زبان «پاسکال» بنا شده است و شرکت امبارکادرو (Embarcadero) در حال حاضر مسئولیت توسعه آن را بر عهده دارد.

ارسال پیامک (SMS) در زبان برنامه‌نویسی دلفی کاربردهای بسیار گسترده‌ای در دنیای نرم‌افزارهای تجاری و سازمانی دارد. از آنجا که دلفی در ایران به شدت برای نوشتن نرم‌افزارهای حسابداری، مدیریتی و سازمانی محبوب است، اتصال این نرم‌افزارها به سیستم پیامکی یک نیاز رایج است. از جمله این کاربرد ها می توان به موارد زیر اشاره کرد:

• احراز هویت کاربران
• اطلاع رسانی و اعلانات
• بازاریابی و تبلیغات
• سیستم های هوشمند و مانیتورینگ

پیاده‌سازی ارسال پیامک در دلفی:

در این راهنما توابع معادل برای ارسال OTP (پترن)، ارسال پیام به چند شماره (GET و POST)، دریافت وضعیت پیام‌ها و مشاهده اعتبار حساب با استفاده از وب‌سرویس REST ارائه شده است.

پیش‌نیازها

Delphi XE7 یا جدیدتر (برای استفاده از THTTPClient)؛ در نسخه‌های قدیمی‌تر می‌توان از Indy (TIdHTTP) استفاده کرد.

واحدهای مورد نیاز: System.Net.HttpClient, System.Net.URLClient, System.NetEncoding, System.JSON, System.SysUtils, System.Classes.

تنظیمات پایه

ابتدا مقادیر ApiKey، Sender و BaseUrl را در یک واحد مرکزی تعریف کنید (به‌عنوان ثابت یا متغیر سراسری)

unit SmsConfig;

interface

const
ApiKey  = 'YOUR_API_KEY';
Sender  = 'YOUR_SMS_SENDER';
BaseUrl = 'http://api.sms-webservice.com/api/V3/';

implementation

end;

توضیح: در تمام درخواست‌ها به “ApiKey” نیاز دارید، بنابراین آن را یک‌بار تعریف کنید. جهت دریافت این کلید API بصورت اختصاصی برای نرم افزار خود، باید ابتدا در سامانه پیام رسان ثبت نام کنید و طبق مراحل تصویری زیر، مقدار لازم را دریافت نمایید.

۲) ارسال پیامک کد تایید (پترن OTP) — معادل “SendTokenSingle”

این متد در سرویس پیام‌رسان به‌صورت GET پیاده‌سازی شده است و پارامترهایی مانند “TemplateKey” و پارامترهای p1، p2، p3 را می‌گیرد.

uses
  System.SysUtils, System.Net.HttpClient, System.NetEncoding;

function SendTokenSingle(const TemplateKey, Destination, P1, P2, P3: string): string;
var
  Client: THTTPClient;
  Url, Params: string;
begin
  Client := THTTPClient.Create;
  try
    Params := Format('ApiKey=%s&TemplateKey=%s&Destination=%s&p1=%s&p2=%s&p3=%s',
      [TNetEncoding.URL.Encode(ApiKey), TNetEncoding.URL.Encode(TemplateKey),
       TNetEncoding.URL.Encode(Destination), TNetEncoding.URL.Encode(P1),
       TNetEncoding.URL.Encode(P2), TNetEncoding.URL.Encode(P3)]);

    Url := BaseUrl + 'SendTokenSingle?' + Params;
    Result := Client.Get(Url).ContentAsString(TEncoding.UTF8);
  finally
    Client.Free;
  end;
end;

مثال استفاده:

var
  resp: string;
begin
  resp := SendTokenSingle('MY_TEMPLATE_KEY', '09121234567', '1234', '', '');
  // resp حاوی پاسخ سرویس (معمولا JSON یا متن) است
end;

نکته: در سمت کلاینت، پس از دریافت پاسخ باید مقدار ارسال‌شده در قالب OTP را با مقدار ورودی کاربر اعتبارسنجی کنید.

۳) ارسال یک متن به چند شماره (GET) — معادل “Send”

نسخهٔ GET این متد می‌تواند تا 99 گیرنده را در یک فراخوانی پشتیبانی کند . در اینجا نمونه پیاده‌سازی با پارامتر “Recipients” به‌صورت رشته (مثلا جداشده با ویرگول) آورده شده است:

function Send_Get(const RecipientsCSV, TextMessage: string): string;
var
  Client: THTTPClient;
  Url, Params: string;
begin
  Client := THTTPClient.Create;
  try
    Params := Format('ApiKey=%s&Text=%s&Sender=%s&Recipients=%s',
      [TNetEncoding.URL.Encode(ApiKey),
       TNetEncoding.URL.Encode(TextMessage),
       TNetEncoding.URL.Encode(Sender),
       TNetEncoding.URL.Encode(RecipientsCSV)]);

    Url := BaseUrl + 'Send?' + Params;
    Result := Client.Get(Url).ContentAsString(TEncoding.UTF8);
  finally
    Client.Free;
  end;
end;

مثال استفاده:

var
  response: string;
begin
  response := Send_Get('09121234567,09129876543', 'سلام! این یک پیام تست است.');
end;

نکته: اگر تعداد گیرندگان بیش از 99 است، باید چندین درخواست ارسال کنید یا از متد “SendBulk” (POST JSON) استفاده کنید.

۴) ارسال گروهی با POST JSON — معادل “SendBulk”

نسخهٔ POST برای ارسال لیست گیرندگان با مشخصات هر گیرنده (مانند “UserTraceId”) استفاده می‌شود. خروجی JSON و ورودی JSON باید مشابه نمونهٔ PHP باشد.

uses
  System.JSON, System.Classes, System.Net.HttpClient, System.SysUtils;

function SendBulk(const DestinationArr, UserTraceIdArr: TArray; const TextMessage: string): string;
var
  Client: THTTPClient;
  JSONObj, RecipientObj: TJSONObject;
  RecipientsArr: TJSONArray;
  I: Integer;
  RequestBody: TStringStream;
begin
  Client := THTTPClient.Create;
  try
    JSONObj := TJSONObject.Create;
    RecipientsArr := TJSONArray.Create;
    try
      for I := 0 to Length(DestinationArr)-1 do
      begin
        RecipientObj := TJSONObject.Create;
        RecipientObj.AddPair('Destination', TJSONString.Create(DestinationArr[I]));
        if I <= High(UserTraceIdArr) then
          RecipientObj.AddPair('UserTraceId', TJSONString.Create(UserTraceIdArr[I]))
        else
          RecipientObj.AddPair('UserTraceId', TJSONString.Create(''));
        RecipientsArr.AddElement(RecipientObj);
      end;

      JSONObj.AddPair('ApiKey', TJSONString.Create(ApiKey));
      JSONObj.AddPair('Text', TJSONString.Create(TextMessage));
      JSONObj.AddPair('Sender', TJSONString.Create(Sender));
      JSONObj.AddPair('Recipients', RecipientsArr);

      RequestBody := TStringStream.Create(JSONObj.ToString, TEncoding.UTF8);
      try
        Result := Client.Post(BaseUrl + 'SendBulk', RequestBody, nil, [TNetHeader.Create('Content-Type', 'application/json')]).ContentAsString(TEncoding.UTF8);
      finally
        RequestBody.Free;
      end;
    except
      JSONObj.Free; // در صورت بروز خطا
      raise;
    end;
  finally
    Client.Free;
  end;
end;

مثالٔ ساخت آرایه‌ها و فراخوانی:

var
  dests, traces: TArray;
  resp: string;
begin
  dests := TArray.Create('09121234567','09129876543');
  traces := TArray.Create('order-123','order-124');
  resp := SendBulk(dests, traces, 'پیام گروهی تست');
end;

۵) دریافت وضعیت پیام‌ها — معادل “StatusById”

برای استعلام وضعیت یک یا چند پیام، سرویس یک متد POST JSON با پارامتر “Ids” ارائه می‌دهد.

function StatusById(const Ids: TArray): string;
var
  Client: THTTPClient;
  JSONObj: TJSONObject;
  IdsArr: TJSONArray;
  I: Integer;
  RequestBody: TStringStream;
begin
  Client := THTTPClient.Create;
  try
    JSONObj := TJSONObject.Create;
    IdsArr := TJSONArray.Create;
    try
      for I := 0 to High(Ids) do
        IdsArr.Add(Ids[I]);

      JSONObj.AddPair('ApiKey', TJSONString.Create(ApiKey));
      JSONObj.AddPair('Ids', IdsArr);

      RequestBody := TStringStream.Create(JSONObj.ToString, TEncoding.UTF8);
      try
        Result := Client.Post(BaseUrl + 'StatusById', RequestBody, nil, [TNetHeader.Create('Content-Type', 'application/json')]).ContentAsString(TEncoding.UTF8);
      finally
        RequestBody.Free;
      end;
    except
      JSONObj.Free;
      raise;
    end;
  finally
    Client.Free;
  end;
end;

نمونه فراخوانی:

var
  statusResp: string;
begin
  statusResp := StatusById(TArray.Create('12345','12346'));
end;

۶) دریافت اعتبار پنل — معادل “AccountInfo”

برای نمایش اعتبار پنل در اپلیکیشن می‌توان از متد “AccountInfo” استفاده کرد.

function AccountInfo: string;
var
  Client: THTTPClient;
  JSONObj: TJSONObject;
  RequestBody: TStringStream;
begin
  Client := THTTPClient.Create;
  try
    JSONObj := TJSONObject.Create;
    try
      JSONObj.AddPair('ApiKey', TJSONString.Create(ApiKey));

      RequestBody := TStringStream.Create(JSONObj.ToString, TEncoding.UTF8);
      try
        Result := Client.Post(BaseUrl + 'AccountInfo', RequestBody, nil, [TNetHeader.Create('Content-Type', 'application/json')]).ContentAsString(TEncoding.UTF8);
      finally
        RequestBody.Free;
      end;
    finally
      JSONObj.Free;
    end;
  finally
    Client.Free;
  end;
end;

نکات کاربردی و خطاگیری

همیشه پاسخ سرویس را (که معمولاً به‌صورت JSON است) پارس کنید (“TJSONObject.ParseJSONValue”) و خطاهای شبکه را مدیریت کنید.
برای امنیت، ApiKey را در متن کد قرار ندهید؛ بهتر است آن را در فایل تنظیمات رمزنگاری‌شده یا محیط اجرا نگهداری کنید.
در درخواست‌های GET طول URL ممکن است محدودیت داشته باشد؛ برای لیست طولانی گیرندگان از “SendBulk” (POST) استفاده کنید.
بررسی وضعیت HTTP و محتوای پاسخ (کد وضعیت، پیام خطا) کمک بزرگی در دیباگ می‌کند.

جایگزین: استفاده از Indy (TIdHTTP)

اگر از نسخه‌ای از Delphi استفاده می‌کنید که THTTPClient ندارد، می‌توانید از TIdHTTP استفاده کنید؛ ولی در نمونه بالا از THTTPClient استفاده شده که API ساده و مدرن‌تری دارد.

نمونهٔ کامل: ارسال OTP و بررسی پاسخ

یک نمونهٔ ساده که OTP را ارسال و خروجی را چاپ می‌کند:

procedure TestOTP;
var
  resp: string;
begin
  resp := SendTokenSingle('VERIFY_TEMPLATE', '09121234567', '5678', '', '');
  Writeln('Response: ' + resp);
end;