این مقاله یک راهنمای جامع و عملی برای تشخیص دقیق این است که آیا API یک شرکت از سرور یا شبکه شما قابل دسترسی است یا نه ارائه می‌دهد. برخلاف رویکردهای سطحی که فقط «پینگ» یا «curl» را پیشنهاد می‌کنند، در اینجا یک متدولوژی لایه‌به‌لایه معرفی می‌شود که با آن می‌توانید دقیقاً مشخص کنید مشکل در کدام مرحله رخ داده است. تمام روش‌ها با دستورات عملی برای ویندوز (PowerShell) و لینوکس ارائه شده‌اند تا بتوانید مستقیماً روی سرور تولیدی خود اجرا کنید. هدف نهایی این است که وقتی با تیم فنی شرکت یا تیم شبکه سازمان خود صحبت می‌کنید، به‌جای جمله مبهم «API کار نمی‌کند»، شواهد فنی دقیق و قابل استناد ارائه دهید.

بخش اول: مدل ذهنی — درخواست API از چه لایه‌هایی عبور می‌کند؟

قبل از اجرای هر دستوری، باید بدانید که هر ابزار تشخیصی کدام لایه را تست می‌کند. جدول زیر این نگاشت را نشان می‌دهد:

| نام‌گذاری | DNS | `Resolve-DnsName`, `nslookup`, `dig` | آیا دامنه به IP تبدیل می‌شود؟ |
| شبکه | IP / ICMP | `ping`, `tracert`/`traceroute`, `mtr` | آیا مسیر IP تا مقصد وجود دارد؟ |
| انتقال | TCP (پورت) | `Test-NetConnection`, `nc`, `telnet` | آیا پورت ۴۴۳ باز است؟ |
| نشست | TLS/SSL | `curl -v`, `openssl s_client` | آیا دست‌دادن امن انجام می‌شود؟ |
| کاربرد | HTTP | `curl`, `Invoke-WebRequest` | سرور چه کد وضعیت و بدنه‌ای برمی‌گرداند؟ |
| مسیر خروج | پروکسی / NAT | `netsh winhttp`, `$env:HTTPS_PROXY` | آیا درخواست از IP دیگری خارج می‌شود؟ |
| مجوز | IP Allowlist | `api.ipify.org` + پنل شرکت | آیا IP خروجی شما مجاز است؟ |

روش درست این است که از پایین به بالا تست کنید. اگر DNS شکست بخورد، تست TCP بی‌معنی است. اگر TCP برقرار نشود، تست TLS و HTTP بی‌فایده است. این رویکرد «تقسیم و غلبه» باعث می‌شود در چند دقیقه به علت اصلی برسید، نه اینکه ساعت‌ها بین حدس‌وگمان گیر کنید.

بخش دوم: لایه DNS — آیا اصلاً می‌دانید به کجا وصل می‌شوید؟

اولین قدم همیشه resolving نام دامنه به آدرس IP است. اگر DNS شکست بخورد، هیچ تست شبکه‌ای معنی ندارد.

در ویندوز (PowerShell)

Resolve-DnsName api.example.com

خروجی باید حداقل یک رکورد `A` (IPv4) یا `AAAA` (IPv6) برگرداند. اگر خطای `DNS name does not exist` گرفتید، یعنی یا دامنه اشتباه است، یا DNS سرور شما (مثلاً DNS داخلی سازمان) نمی‌تواند آن را resolve کند.

در لینوکس

dig +short api.example.com
nslookup api.example.com
host api.example.com

تفسیر و نکات مهم

• چند IP برگشتی: بسیاری از APIها پشت CDN یا Load Balancer هستند و چند IP برمی‌گردانند. این طبیعی است.
• تفاوت DNS داخلی و عمومی: اگر سرور شما از DNS داخلی سازمان (مثلاً `172.16.15.2`) استفاده می‌کند، ممکن است دامنه را به IP متفاوتی resolve کند یا اصلاً resolve نکند. برای مقایسه، از یک DNS عمومی مانند `8.8.8.8` نیز تست کنید: `Resolve-DnsName api.example.com -Server 8.8.8.8`.
• DNS کند: اگر resolve شدن بیش از حد طول بکشد (مثلاً بیش از ۵۰۰ میلی‌ثانیه)، ممکن است مشکل از resolver باشد و باعث timeout در کلاینت شما شود.

اگر DNS درست بود، وارد لایه بعدی می‌شویم.

بخش سوم: لایه TCP — آیا پورت مقصد از شبکه شما باز است؟

حتی اگر DNS درست باشد، ممکن است فایروال سازمان، ISP یا خود شرکت، ترافیک خروجی به پورت مقصد (معمولاً ۴۴۳) را مسدود کرده باشد.

روش اصلی در ویندوز: `Test-NetConnection`

Test-NetConnection api.example.com -Port 443

خروجی کلیدی خط `TcpTestSucceeded` است:

• `True`: اتصال TCP برقرار شد. یعنی مسیر شبکه و پورت باز است. به مرحله TLS بروید.
• `False`: اتصال برقرار نشد. یعنی فایروال، فیلتر یا مسیر شبکه مانع است.

برای اطلاعات بیشتر، از `-InformationLevel Detailed` استفاده کنید تا latency و مسیر نیز نشان داده شود.

 روش جایگزین در لینوکس: `nc` یا `telnet`

nc -vz api.example.com 443
telnet api.example.com 443

اگر `succeeded` یا `open` دیدید، TCP برقرار است. اگر timeout دیدید، مسیر بسته است. اگر `Connection refused` دیدید، به سرور رسیدید ولی سرویس روی آن پورت گوش نمی‌دهد.

نکته مهم درباره `telnet` در ویندوز
همان‌طور که در تجربه قبلی دیدید، خطای `'telnet' is not recognized` به این معناست که کلاینت telnet نصب نیست، نه اینکه شبکه مشکل دارد. ویندوز سرور به‌صورت پیش‌فرض telnet ندارد. بنابراین همیشه از `Test-NetConnection` استفاده کنید که در همه نسخه‌های PowerShell موجود است.

اگر TCP برقرار نشد، چه کنید؟

• `Test-NetConnection` را از یک شبکه دیگر (مثلاً لپ‌تاپ شخصی با اینترنت خانگی) اجرا کنید. اگر آنجا `True` بود ولی روی سرور `False` بود، مشکل از فایروال سازمان یا مسیر خروجی سرور است، نه شرکت.
• `tracert` (ویندوز) یا `traceroute`/`mtr` (لینوکس) بزنید تا ببینید مسیر در کدام هاپ قطع می‌شود.
• با تیم شبکه سازمان چک کنید که ترافیک خروجی به محدوده IP مقصد روی پورت ۴۴۳ مجاز باشد.

اگر TCP برقرار شد، به لایه TLS می‌رویم.

بخش چهارم: لایه TLS — آیا دست‌دادن امن (Handshake) انجام می‌شود؟

حتی وقتی TCP وصل می‌شود، ممکن است TLS به دلایل مختلف شکست بخورد: گواهی منقضی، نام میزبان ناهماهنگ، الگوریتم‌های رمزنگاری ناسازگار، یا مداخله یک پروکسی واسط (SSL Inspection).

روش اول: `curl -v` (ساده‌ترین و سریع‌ترین)

curl.exe -v --max-time 15 https://api.example.com/

در خروجی به دنبال خطوطی بگردید که با `*` شروع می‌شوند و مربوط به TLS هستند:

• `SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384` → handshake موفق.
• `Server certificate: subject: CN=api.example.com` → گواهی معتبر و برای همان دامنه.
• SSL certificate verify ok` → زنجیره گواهی تأیید شد.

اگر خطایی مانند `SSL certificate problem: unable to get local issuer certificate` یا `certificate has expired` دیدید، مشکل TLS دارید.

روش دوم: `openssl s_client` (تحلیل عمیق)
 

echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -subject -issuer -dates

این دستور جزئیات گواهی (موضوع، صادرکننده، تاریخ انقضا) را نشان می‌دهد. اگر handshake شکست بخورد، `openssl` خطای دقیق‌تری مانند `handshake failure` یا `tlsv1 alert protocol version` می‌دهد.

تفسیر خطاهای رایج TLS

• `certificate verify failed`: گواهی سرور توسط کلاینت معتبر شناخته نشد (ممکن است CA ناشناخته باشد یا گواهی منقضی شده باشد).
• `hostname mismatch`: گواهی برای دامنه دیگری صادر شده است (مثلاً `*.example.com` برای `api.example.com` معتبر است، اما برای `api.example.net` نه).
• `unsupported protocol`: سرور فقط TLS 1.2+ را می‌پذیرد ولی کلاینت شما TLS 1.0/1.1 پیشنهاد می‌دهد (در ویندوزهای قدیمی رایج است).

اگر TLS موفق بود، به لایه HTTP می‌رویم.

بخش پنجم: لایه HTTP — سرور در پاسخ به درخواست شما چه می‌گوید؟

این مرحله مهم‌ترین بخش است، زیرا مشخص می‌کند که آیا درخواست شما از نظر شبکه‌ای به API رسیده و سرور از نظر منطقی چه پاسخی داده است.

روش اصلی: `curl` با نمایش کد وضعیت و زمان‌بندی
 

curl.exe -sS -o NUL -w "HTTP:%{http_code} DNS:%{time_namelookup} CONNECT:%{time_connect} TLS:%{time_appconnect} TTFB:%{time_starttransfer} TOTAL:%{time_total}\n" --max-time 15 https://api.example.com/

(در لینوکس به‌جای `NUL` از `/dev/null` استفاده کنید.)

این خروجی یک تجزیه زمانی کامل می‌دهد: چه مدت DNS طول کشید، چه مدت TCP، چه مدت TLS، و چه مدت تا اولین بایت پاسخ (TTFB). اگر TTFB بسیار بالا باشد (مثلاً چند ثانیه)، ممکن است مشکل از سمت سرور شرکت باشد، نه شبکه شما.

روش جایگزین در PowerShell (وقتی `curl.exe` نصب نیست)
 

try {
    $r = Invoke-WebRequest -Uri "https://api.example.com/" -TimeoutSec 15 -UseBasicParsing
    "HTTP: $($r.StatusCode)"
    $r.Content.Substring(0, [Math]::Min(300, $r.Content.Length))
} catch {
    if ($_.Exception.Response) {
        "HTTP: $([int]$_.Exception.Response.StatusCode)"
        "Body: $((New-Object System.IO.StreamReader($_.Exception.Response.GetResponseStream())).ReadToEnd().Substring(0,300))"
    } else {
        "ERROR: $($_.Exception.Message)"
    }
}

این نسخه حتی برای پاسخ‌های `4xx/5xx` هم کد وضعیت و بدنه را نشان می‌دهد، چون `Invoke-WebRequest` در این حالت‌ها استثنا پرتاب می‌کند.

جدول تفسیر کدهای وضعیت HTTP

| 200 | API کاملاً در دسترس و پاسخ‌ده است. | مشکل جای دیگری است (احراز هویت، بدنه درخواست و…). |
| 401 / 403 | از نظر شبکه در دسترس است، اما احراز هویت یا مجوز IP مشکل دارد. | کلید API، توکن یا IP Allowlist را بررسی کنید. |
| 404 | به سرور رسیدید، اما مسیر (endpoint) وجود ندارد. | URL را بررسی کنید (این خطا معمولاً ربطی به دسترسی ندارد). |
| 429 | در دسترس است، اما Rate Limit فعال شده. | تعداد درخواست‌ها را کاهش دهید یا با شرکت هماهنگ کنید. |
| 500 | در دسترس است، اما خطای داخلی سرور شرکت. | مشکل سمت شرکت است؛ لاگ‌ها را برایشان بفرستید. |
| 502 / 504 | به Gateway رسیدید، اما سرویس upstream شرکت مشکل دارد. | شبکه شما سالم است؛ مشکل سمت شرکت است. |
| 000 + timeout | اصلاً به سرور نرسیدید. | فایروال، فیلتر، یا مسیر شبکه را بررسی کنید. |
| `Connection refused` | به سرور رسیدید، اما پورت/سرویس بسته است. | endpoint یا پورت را بررسی کنید. |

نکته کلیدی: دریافت کد `502` یا `504` دقیقاً به معنای آن است که شبکه شما تا Gateway شرکت باز است و مشکل از سرویس داخلی شرکت است. این تمایز حیاتی است و باید در مکاتبه با شرکت برجسته شود.

بخش ششم: پروکسی و NAT — آیا درخواست شما واقعاً از IP خودتان خارج می‌شود؟

در بسیاری از سازمان‌ها، ترافیک خروجی از طریق یک پروکسی یا NAT عبور می‌کند. در این حالت، IP عمومی که سرور مقصد می‌بیند، IP سرور شما نیست، بلکه IP پروکسی است. اگر شرکت API از IP Allowlist استفاده کند، باید IP پروکسی در لیست مجاز باشد، نه IP سرور.# بررسی تنظیمات پروکسی در ویندوز

# پروکسی WinHTTP
netsh winhttp show proxy

# پروکسی پیش‌فرض .NET
[System.Net.WebRequest]::DefaultWebProxy

# متغیرهای محیطی پروکسی
echo $env:HTTP_PROXY
echo $env:HTTPS_PROXY
echo $env:NO_PROXY

اگر پروکسی تنظیم شده باشد، `curl` و `Invoke-WebRequest` به‌طور خودکار از آن استفاده می‌کنند (مگر اینکه با `--noproxy` یا `-Proxy` خلاف آن را مشخص کنید).

تست با پروکسی مشخص
 

Invoke-WebRequest -Uri "https://api.example.com/" -Proxy "http://proxy.corp:8080" -TimeoutSec 15

یا با `curl`:

curl.exe -v --proxy http://proxy.corp:8080 https://api.example.com/

اگر بدون پروکسی timeout می‌گیرید ولی با پروکسی پاسخ می‌گیرید، یعنی شبکه شما فقط از طریق پروکسی به اینترنت دسترسی دارد و باید IP پروکسی را به شرکت اعلام کنید.

بررسی IP خروجی واقعی
مهم‌ترین دستور برای مکاتبه با شرکت:

Invoke-RestMethod -Uri "https://api.ipify.org?format=json" -TimeoutSec 10

یا در لینوکس:

curl -s https://api.ipify.org

این IP همان چیزی است که شرکت در سمت خود می‌بیند. اگر با IP سرور شما (`89.32.250.206` در مثال قبلی) متفاوت است، حتماً باید IP جدید را به شرکت اعلام کنید.

بخش هفتم: IP Allowlist — وقتی شبکه باز است اما مجوز IP ندارید

بسیاری از APIهای تجاری (مانند درگاه‌های پرداخت، سرویس‌های پیامک، و پلتفرم‌های ابری) از IP Allowlist استفاده می‌کنند: فقط درخواست‌هایی پذیرفته می‌شوند که از IPهای از پیش تأییدشده ارسال شوند. در این حالت، تست‌های TCP/TLS/HTTP ممکن است موفق باشند (چون اتصال برقرار می‌شود)، اما API پاسخ `401` یا `403` می‌دهد.

نشانه‌های مشکل Allowlist

• `Test-NetConnection` → `True`
• `curl -v` → handshake موفق
• اما پاسخ HTTP: `401 Unauthorized` یا `403 Forbidden` با پیامی شبیه «IP not allowed» یا «source IP not permitted».

اقدامات

• 1. IP خروجی واقعی را مشخص کنید (بخش ششم).
• 2. IP را به شرکت اعلام کنید و بخواهید در Allowlist ثبت شود.
• 3. در صورت استفاده از پروکسی، IP پروکسی را اعلام کنید، نه IP سرور.
• 4. پس از تأیید شرکت، دوباره تست کنید و مطمئن شوید پاسخ `200` یا `401` (به‌جای `403`) می‌گیرید.

نکته مهم: حتی اگر Allowlist درست باشد، ممکن است احراز هویت (کلید API، OAuth) هم لازم باشد. Allowlist جایگزین احراز هویت نیست، بلکه یک لایه اضافی است. بنابراین اگر `403` گرفتید، ابتدا Allowlist را بررسی کنید؛ اگر `401` گرفتید، کلید API را بررسی کنید.

بخش هشتم: اتوماسیون و مانیتورینگ — از تست دستی به پایش مستمر

تست دستی برای عیب‌یابی خوب است، اما برای اطمینان پایدار از دسترسی API، باید این بررسی‌ها را خودکار کنید.

جمع‌بندی: دسترسی به API یک مسئله «همه یا هیچ» نیست

«API قطع است» تقریباً همیشه یک تشخیص ناقص است. همان‌طور که دیدیم، یک درخواست API از چندین لایه عبور می‌کند و شکست در هر لایه علت و راه‌حل متفاوتی دارد. با رویکرد لایه‌به‌لایه‌ای که در این مقاله توضیح داده شد—شروع از DNS، سپس TCP، سپس TLS، و در نهایت HTTP—می‌توانید در چند دقیقه مشخص کنید که مشکل از شبکه خودتان، پروکسی/فایروال سازمان، IP Allowlist، یا سرویس شرکت است.

مهم‌ترین درس عملی این است: هرگز به «قطع بودن API» بسنده نکنید. با `Test-NetConnection` ثابت کنید که TCP باز است، با `curl -v` ثابت کنید که TLS و HTTP کار می‌کنند، و با `api.ipify.org` ثابت کنید که IP خروجی شما همان چیزی است که فکر می‌کنید. این شواهد سه‌گانه، هم برای عیب‌یابی خودتان و هم برای مکاتبه با شرکت، قدرتمندترین ابزاری است که می‌توانید داشته باشید. در نهایت، با خودکارسازی این بررسی‌ها و مانیتورینگ مستمر، می‌توانید قبل از اینکه کاربران یا سیستم‌هایتان از خطا مطلع شوند، از بروز مشکل آگاه شوید و آن را برطرف کنید.