VPack
VPack
VPACK B2B API

API و همکاری در فروش VPack

API عمده برای توسعه‌دهندگان و فروشندگان؛ با قیمت قراردادی، Quote امن، Idempotency و قرارداد OpenAPI کامل.

مشاهده مستنداتOpenAPI 3.1
قیمت عمده اختصاصی
حفاظت Margin
Quote امن ۶۰ ثانیه‌ای
OpenAPI + AI-ready

پنل همکاری شما

شروع در کمتر از یک دقیقه

کلید را فقط در سرور نگه دارید. قیمت را بخوانید، Quote بسازید و همان Quote را با Idempotency-Key خرید کنید.

curl -s "https://v-pack.ir/api/v1/virtual-numbers/prices?service=telegram&country=US" \
  -H "Authorization: Bearer $VPACK_API_KEY"

curl -s -X POST "https://v-pack.ir/api/v1/virtual-numbers/quotes" \
  -H "Authorization: Bearer $VPACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"US","maxPriceUsd":0.50}'
GETTING STARTED

شروع سریع و قرارداد پاسخ

Base URL
https://v-pack.ir/api/v1
احراز هویت
Bearer API key
نسخه API
v1

همه پاسخ‌های موفق در data قرار می‌گیرند و requestId برای ردیابی درخواست برگردانده می‌شود.

{
  "ok": true,
  "requestId": "6ff2d1d8-...",
  "data": { ... }
}
SECURITY

Authentication، Scope و نگهداری کلید

روش پیشنهادی Bearer است. X-API-Key نیز پشتیبانی می‌شود. کلید را هرگز داخل JavaScript مرورگر، اپ موبایل قابل استخراج، Git یا لاگ‌ها قرار ندهید.

Authorization: Bearer vpk_live_xxx

# Alternative
X-API-Key: vpk_live_xxx
virtual_numbers:read

services / countries / prices / activation status

virtual_numbers:buy

create quote / purchase activation

Secret کامل فقط یک‌بار هنگام ساخت کلید نمایش داده می‌شود. در صورت افشا، کلید را Revoke و کلید جدید ایجاد کنید.
PURCHASE LIFECYCLE

فرآیند صحیح خرید شماره مجازی

1. services
2. countries
3. prices
4. quote
5. activation

Price فقط قیمت جاری را نشان می‌دهد و خرید را رزرو نمی‌کند. برای خرید باید Quote بگیرید. Quote حدود ۶۰ ثانیه معتبر است و خرید سرور دوباره قیمت/پروایدر را کنترل می‌کند.

Idempotency-Key

برای POST /activations الزامی، بین ۱۲ تا ۱۲۰ کاراکتر و برای هر خرید منطقی یکتا باشد. اگر همان خرید را Retry می‌کنید همان کلید را دوباره استفاده کنید؛ برای Quote دیگر کلید جدید بسازید.

API REFERENCE

Endpointها با Request و Response واقعی

GET/virtual-numbers/services

Scope: virtual_numbers:read

{
  "ok": true,
  "requestId": "...",
  "data": {
    "services": [
      {"key":"telegram","slug":"telegram","name":{"fa":"تلگرام","en":"Telegram"},"popular":true}
    ]
  }
}
GET/virtual-numbers/countries?service=telegram

Scope: virtual_numbers:read

{
  "ok": true,
  "requestId": "...",
  "data": {
    "service":"telegram",
    "countries":[{"iso2":"US","key":"US","name":{"fa":"آمریکا","en":"United States"},"offers":12}]
  }
}
GET/virtual-numbers/prices?service=telegram&country=US

Scope: virtual_numbers:read

{
  "ok": true,
  "requestId": "...",
  "data": {
    "service":"telegram",
    "country":"US",
    "currency":"USD",
    "price":0.42,
    "available":18,
    "quoteRequired":true
  }
}
POST/virtual-numbers/quotes

Scope: virtual_numbers:buy · HTTP 201

POST https://v-pack.ir/api/v1/virtual-numbers/quotes
Authorization: Bearer $VPACK_API_KEY
Content-Type: application/json

{"service":"telegram","country":"US","maxPriceUsd":0.50}

# 201
{
  "ok":true,
  "requestId":"...",
  "data":{
    "quoteId":"cm...",
    "service":"telegram",
    "country":"US",
    "price":0.42,
    "currency":"USD",
    "available":18,
    "expiresAt":"2026-09-03T08:20:00.000Z"
  }
}
POST/activations

Scope: virtual_numbers:buy · Idempotency-Key required · HTTP 201

POST https://v-pack.ir/api/v1/activations
Authorization: Bearer $VPACK_API_KEY
Idempotency-Key: my-order-20260903-0001
Content-Type: application/json

{"quoteId":"cm..."}

# 201
{
  "ok":true,
  "requestId":"...",
  "data":{
    "quoteId":"cm...",
    "orderId":"cm...",
    "activationId":"cm...",
    "status":"...",
    "charged":{"amount":0.42,"currency":"USD"}
  }
}
GET/activations/{id}

Scope: virtual_numbers:read

{
  "ok":true,
  "requestId":"...",
  "data":{
    "id":"cm...",
    "status":"...",
    "phoneNumber":"+1...",
    "service":"telegram",
    "country":"US",
    "priceToman":12345,
    "createdAt":"...",
    "updatedAt":"...",
    "messages":[{"code":"123456","text":"Your code is 123456","receivedAt":"..."}]
  }
}
OPERATIONS

خطاها، Request ID و Rate Limit

برای خطاها فقط به متن پیام وابسته نشوید؛ HTTP status و error.code را بررسی کنید. requestId را در لاگ خود ذخیره کنید تا پشتیبانی بتواند همان درخواست را پیدا کند.

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Quote expired or not found.",
    "requestId": "..."
  }
}
HTTPTypical codeMeaning
400VALIDATION_ERRORInvalid params/body/idempotency key
401UNAUTHORIZEDMissing / invalid / inactive key
403FORBIDDENMissing scope or unavailable country
404NOT_FOUNDService / country / activation not found
409VALIDATION_ERRORQuote state / idempotency / price conflict
429VALIDATION_ERRORRate limit exceeded
500INTERNAL_ERRORUnexpected server error
X-RateLimit-Limit-MinuteX-RateLimit-Remaining-MinuteX-RateLimit-Limit-DayX-RateLimit-Remaining-Day
AI-READY

مستندات آماده برای ChatGPT، Claude، Gemini و Coding Agentها

برای اتصال توسط AI لازم نیست کل این صفحه را کپی کنید. لینک OpenAPI و llms.txt را به Agent بدهید و Secret را فقط از Environment Variable در اختیار Runtime قرار دهید.

OpenAPI 3.1 JSON
https://v-pack.ir/api/v1/openapi.json
llms.txt
https://v-pack.ir/api/v1/llms.txt
اصل مهم

Provider، Offer ID داخلی، هزینه خام و Margin جزء قرارداد عمومی API نیستند و Agent نباید به آن‌ها وابسته شود.

Rate limit اختصاصی هر Client
خرید Idempotent و قابل Retry
OpenAPI منبع حقیقت
API و همکاری در فروش | VPack | ویپک