سرویس API پیامدهی

نمونه کد SOAP

SOAP — معرفی

وب‌سرویس SOAP از آدرس زیر استفاده می‌کند. احراز هویت: توکن API در UserName؛ PassWord خالی.

آدرس سرویس SOAP

https://dev.homais.com/services/sms/index.asmx

WSDL: https://dev.homais.com/services/sms/index.asmx?wsdl

متدها: getStatus، singleSMS، OTPGenerate، getInbox، getDeliveryStatus

Namespace: Http://services.shahrenovin.com

SOAP — PHP (NuSOAP)

کتابخانهٔ NuSOAP — مناسب PHP قدیمی‌تر.

getStatus — موجودی اعتبار

PHP<?php
require_once 'nusoap.php';
$client = new nusoap_client('https://dev.homais.com/services/sms/index.asmx?wsdl', ['encoding' => 'UTF-8']);
$result = $client->call('getStatus', [
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'returnType' => 1,
]);
echo 'Balance (Rial): ' . $result;

singleSMS — ارسال پیامک تکی

PHP<?php
require_once 'nusoap.php';
$client = new nusoap_client('https://dev.homais.com/services/sms/index.asmx?wsdl', ['encoding' => 'UTF-8']);
$trackingId = $client->call('singleSMS', [
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'Mobile'     => '09121234567',
    'Message'    => 'سلام، پیام تست',
    'ServerType' => 100,
]);
echo ($trackingId > 1000) ? "OK: $trackingId" : "Error: $trackingId";

OTPGenerate — رمز یکبار مصرف

PHP<?php
require_once 'nusoap.php';
$client = new nusoap_client('https://dev.homais.com/services/sms/index.asmx?wsdl', ['encoding' => 'UTF-8']);
$result = $client->call('OTPGenerate', [
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'Mobile'     => '09121234567',
    'Key'        => '',          // خالی = تولید خودکار OTP
    'ServerType' => 100,
]);
echo 'Tracking / OTP result: ' . $result;

getInbox — صندوق دریافت

PHP<?php
require_once 'nusoap.php';
$client = new nusoap_client('https://dev.homais.com/services/sms/index.asmx?wsdl', ['encoding' => 'UTF-8']);
$resultCode = 0;
$rows = $client->call('getInbox', [
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'lastItems'  => 10,
    'indexID'    => -1,          // -1 = پیام‌های خوانده‌نشده
    'resultCode' => &$resultCode,
]);
print_r($rows);
echo 'resultCode: ' . $resultCode;

getDeliveryStatus — وضعیت تحویل

PHP<?php
require_once 'nusoap.php';
$client = new nusoap_client('https://dev.homais.com/services/sms/index.asmx?wsdl', ['encoding' => 'UTF-8']);
$cpId = 12345678;   // خروجی singleSMS
$localId = 100;     // شناسه در باکس تحویل پنل
$status = $client->call('getDeliveryStatus', [
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'localID'    => $localId,
    'cpID'       => $cpId,
]);
echo 'Delivery status code: ' . $status;

SOAP — PHP (SoapClient داخلی)

کلاس SoapClient داخلی PHP — توصیه‌شده برای PHP 7+.

PHP<?php
$client = new SoapClient('https://dev.homais.com/services/sms/index.asmx?wsdl', [
    'encoding' => 'UTF-8',
    'trace'    => true,
    'exceptions' => true,
]);

// --- getStatus ---
$balance = $client->getStatus([
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'returnType' => 1,
]);
echo 'Balance: ' . ($balance->getStatusResult ?? $balance) . PHP_EOL;

// --- singleSMS ---
$sms = $client->singleSMS([
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'Mobile'     => '09121234567',
    'Message'    => 'سلام، پیام تست',
    'ServerType' => 100,
]);
$id = $sms->singleSMSResult ?? $sms;
echo 'Tracking: ' . $id . PHP_EOL;

// --- OTPGenerate ---
$otp = $client->OTPGenerate([
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'Mobile'     => '09121234567',
    'Key'        => '',
    'ServerType' => 100,
]);
echo 'OTP result: ' . ($otp->OTPGenerateResult ?? $otp) . PHP_EOL;

// --- getInbox ---
$inbox = $client->getInbox([
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'lastItems'  => 10,
    'indexID'    => -1,
    'resultCode' => 0,
]);
print_r($inbox);

// --- getDeliveryStatus ---
$delivery = $client->getDeliveryStatus([
    'PortalCode' => 12345,
    'UserName'   => 'YOUR_API_TOKEN',
    'PassWord'   => '',
    'localID'    => 100,
    'cpID'       => 12345678,
]);
echo 'Status: ' . ($delivery->getDeliveryStatusResult ?? $delivery);

SOAP — C# (.NET)

از Visual Studio: Add Service Reference → WSDL: https://dev.homais.com/services/sms/index.asmx?wsdl

C#using System;
using System.ServiceModel;

// پس از Add Service Reference نام کلاس ممکن است SmsServiceSoapClient باشد
var client = new SmsServiceSoapClient();

// getStatus
var balance = await client.getStatusAsync(12345, "YOUR_API_TOKEN", "", 1);
Console.WriteLine($"Balance: {balance.Body.getStatusResult}");

// singleSMS
var sms = await client.singleSMSAsync(
    12345, "YOUR_API_TOKEN", "",
    "09121234567", "سلام، پیام تست", 100);
long trackingId = sms.Body.singleSMSResult;
Console.WriteLine(trackingId > 1000 ? $"OK: {trackingId}" : $"Error: {trackingId}");

// OTPGenerate
var otp = await client.OTPGenerateAsync(
    12345, "YOUR_API_TOKEN", "",
    "09121234567", "", 100);
Console.WriteLine($"OTP result: {otp.Body.OTPGenerateResult}");

// getInbox
var inbox = await client.getInboxAsync(
    12345, "YOUR_API_TOKEN", "", 10, -1, ref resultCode);
// resultCode به‌صورت out/ref بسته به proxy

// getDeliveryStatus
var status = await client.getDeliveryStatusAsync(
    12345, "YOUR_API_TOKEN", "", 100, 12345678);
Console.WriteLine($"Delivery: {status.Body.getDeliveryStatusResult}");

HttpClient — XML دستی (بدون Service Reference)

C# — HttpClientvar endpoint = "https://dev.homais.com/services/sms/index.asmx";
var envelope = $@"<?xml version=""1.0"" encoding=""utf-8""?>
<soap:Envelope xmlns:soap=""http://schemas.xmlsoap.org/soap/envelope/"">
  <soap:Body>
    <singleSMS xmlns=""Http://services.shahrenovin.com"">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <Mobile>09121234567</Mobile>
      <Message>سلام</Message>
      <ServerType>100</ServerType>
    </singleSMS>
  </soap:Body>
</soap:Envelope>";

using var http = new HttpClient();
var req = new HttpRequestMessage(HttpMethod.Post, endpoint);
req.Content = new StringContent(envelope, Encoding.UTF8, "text/xml");
req.Headers.Add("SOAPAction", "Http://services.shahrenovin.com/singleSMS");
var res = await http.SendAsync(req);
Console.WriteLine(await res.Content.ReadAsStringAsync());

SOAP — Java

Java — javax.xml.soapimport javax.xml.soap.*;
import java.net.URL;

public class HomaSmsSoap {
    static final String ENDPOINT = "https://dev.homais.com/services/sms/index.asmx";
    static final String NS = "Http://services.shahrenovin.com";

    static SOAPMessage call(String method, String innerXml) throws Exception {
        MessageFactory mf = MessageFactory.newInstance();
        SOAPMessage msg = mf.createMessage();
        SOAPEnvelope env = msg.getSOAPPart().getEnvelope();
        SOAPBody body = env.getBody();
        body.addChildElement(env.createName(method, "", NS))
            .addTextNode(""); // inner params via DOM — یا از JAX-WS stub

        SOAPConnection conn = SOAPConnectionFactory.newInstance().createConnection();
        SOAPMessage res = conn.call(msg, new URL(ENDPOINT));
        conn.close();
        return res;
    }

    // توصیه: wsimport -keep https://dev.homais.com/services/sms/index.asmx?wsdl
    // سپس:
    // SmsService service = new SmsService();
    // SmsServiceSoap port = service.getSmsServiceSoap();
    // long id = port.singleSMS(12345, "YOUR_API_TOKEN", "", "0912...", "msg", 100);
}

JAX-WS (wsimport) — همه متدها

Java — JAX-WS// wsimport -keep -p com.homa.sms https://dev.homais.com/services/sms/index.asmx?wsdl

SmsService service = new SmsService();
SmsServiceSoap port = service.getSmsServiceSoap();

// getStatus
long balance = port.getStatus(12345, "YOUR_API_TOKEN", "", 1);

// singleSMS
long trackingId = port.singleSMS(
    12345, "YOUR_API_TOKEN", "",
    "09121234567", "سلام", 100);

// OTPGenerate
long otpResult = port.otpGenerate(
    12345, "YOUR_API_TOKEN", "",
    "09121234567", "", 100);

// getInbox
Holder<Integer> resultCode = new Holder<>(0);
GetInboxResponse inbox = port.getInbox(
    12345, "YOUR_API_TOKEN", "", 10, -1, resultCode);

// getDeliveryStatus
int delivery = port.getDeliveryStatus(
    12345, "YOUR_API_TOKEN", "", 100, (int) trackingId);

SOAP — Python

zeep (توصیه‌شده)

Python — zeep# pip install zeep
from zeep import Client

client = Client('https://dev.homais.com/services/sms/index.asmx?wsdl')

# getStatus
balance = client.service.getStatus(
    PortalCode=12345, UserName='YOUR_API_TOKEN',
    PassWord='', returnType=1)
print('Balance:', balance)

# singleSMS
tracking = client.service.singleSMS(
    PortalCode=12345, UserName='YOUR_API_TOKEN', PassWord='',
    Mobile='09121234567', Message='سلام', ServerType=100)
print('Tracking:', tracking)

# OTPGenerate
otp = client.service.OTPGenerate(
    PortalCode=12345, UserName='YOUR_API_TOKEN', PassWord='',
    Mobile='09121234567', Key='', ServerType=100)
print('OTP:', otp)

# getInbox
inbox = client.service.getInbox(
    PortalCode=12345, UserName='YOUR_API_TOKEN', PassWord='',
    lastItems=10, indexID=-1, resultCode=0)
print('Inbox:', inbox)

# getDeliveryStatus
status = client.service.getDeliveryStatus(
    PortalCode=12345, UserName='YOUR_API_TOKEN', PassWord='',
    localID=100, cpID=12345678)
print('Delivery:', status)

requests — XML دستی

Python — requestsimport requests

def soap_call(envelope, soap_action):
    r = requests.post(
        'https://dev.homais.com/services/sms/index.asmx',
        data=envelope.encode('utf-8'),
        headers={
            'Content-Type': 'text/xml; charset=utf-8',
            'SOAPAction': soap_action,
        },
        timeout=30,
    )
    return r.text

env = f"""<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <singleSMS xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <Mobile>09121234567</Mobile>
      <Message>سلام</Message>
      <ServerType>100</ServerType>
    </singleSMS>
  </soap:Body>
</soap:Envelope>"""

print(soap_call(env, 'Http://services.shahrenovin.com/singleSMS'))

SOAP — cURL (XML خام)

فراخوانی مستقیم بدون کتابخانه — مناسب تست و shell script.

getStatus

cURLcurl -X POST 'https://dev.homais.com/services/sms/index.asmx' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: Http://services.shahrenovin.com/getStatus' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getStatus xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <returnType>1</returnType>
    </getStatus>
  </soap:Body>
</soap:Envelope>'

singleSMS

cURLcurl -X POST 'https://dev.homais.com/services/sms/index.asmx' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: Http://services.shahrenovin.com/singleSMS' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <singleSMS xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <Mobile>09121234567</Mobile>
      <Message>سلام</Message>
      <ServerType>100</ServerType>
    </singleSMS>
  </soap:Body>
</soap:Envelope>'

OTPGenerate

cURLcurl -X POST 'https://dev.homais.com/services/sms/index.asmx' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: Http://services.shahrenovin.com/OTPGenerate' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <OTPGenerate xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <Mobile>09121234567</Mobile>
      <Key></Key>
      <ServerType>100</ServerType>
    </OTPGenerate>
  </soap:Body>
</soap:Envelope>'

getInbox

cURLcurl -X POST 'https://dev.homais.com/services/sms/index.asmx' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: Http://services.shahrenovin.com/getInbox' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getInbox xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <lastItems>10</lastItems>
      <indexID>-1</indexID>
      <resultCode>0</resultCode>
    </getInbox>
  </soap:Body>
</soap:Envelope>'

getDeliveryStatus

cURLcurl -X POST 'https://dev.homais.com/services/sms/index.asmx' \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: Http://services.shahrenovin.com/getDeliveryStatus' \
  -d '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getDeliveryStatus xmlns="Http://services.shahrenovin.com">
      <PortalCode>12345</PortalCode>
      <UserName>YOUR_API_TOKEN</UserName>
      <PassWord></PassWord>
      <localID>100</localID>
      <cpID>12345678</cpID>
    </getDeliveryStatus>
  </soap:Body>
</soap:Envelope>'

نکات

برای اتصال نرم‌افزارهای حسابداری از بخش «اتصال سایر نرم‌افزارها» استفاده کنید: نام کاربری = توکن API، کد پرتال = پارامتر PortalCode.
اتصال مستقیم فقط وقتی ممکن است که نرم‌افزار اجازه تعریف URL و پارامترهای دلخواه را بدهد؛ در غیر این صورت افزونه/واسط اختصاصی لازم است.
ServerType=100 برای ارسال عمومی و OTP (لیست سیاه مخابرات) توصیه می‌شود.
پاسخ موفق: عدد بزرگ‌تر از ۱۰۰۰؛ هر عدد دیگر کد خطاست.
برای پیام حاوی لینک یا ارسال از شماره عمومی، پروفایل WhoIS باید تکمیل و تأیید شده باشد.
برای تست سریع REST API، URL را با پارامترها در مرورگر باز کنید.
در صورت خطا، کد بازگشتی و ServerType را در تیکت پشتیبانی ذکر کنید.

مدیریت مشتریان

عملیات مالی