API: کیف پول

خواندن موجودی و تاریخچه و شروع شارژ.

موجودی‌ها به ریال برگردانده می‌شوند. شارژ نشانی صفحهٔ بانک را برمی‌گرداند که یک انسان باید برای پرداخت در مرورگر باز کند.

دریافت قیمت خدمات جانبی

GET /service-prices

قیمت خدمات جانبی پولی را برمی‌گرداند: IP شناور برای هر مورد، دیسک داده و اسنپ‌شات برای هر گیگابایت، هر کدام برای یک دورهٔ ۳۰ روزه، به معادل دلار و به ریال با نرخ امروز.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق

نمونه

curl -X GET https://veneshcloud.ir/api/service-prices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

موجودی کیف پول

GET /wallet

موجودی شما را به ریال برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند WalletBalance.

نمونه

curl -X GET https://veneshcloud.ir/api/wallet \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

تاریخچهٔ تراکنش‌ها

GET /wallet/ledger

تراکنش‌های کیف پول را از جدید به قدیم و صفحه‌بندی‌شده برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای query

فیلد	نوع	مقادیر
`per_page`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از WalletLedgerEntry).

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/ledger \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

دریافت فاکتور به‌صورت PDF

GET /invoices/{id}/pdf

یکی از فاکتورهای شما را به‌صورت فایل PDF و به زبان درخواست برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`id`	integer

پارامترهای query

فیلد	نوع	مقادیر
`locale`	string	`fa`, `en`

پاسخ‌ها

200 موفق
404 پیدا نشد

نمونه

curl -X GET https://veneshcloud.ir/api/invoices/KEY_ID/pdf \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

فاکتورها و رسیدها

GET /wallet/invoices

همین رکوردها را با قالب فاکتور و مبالغ ریالی برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای query

فیلد	نوع	مقادیر
`per_page`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از Invoice).

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

در دسترس بودن شارژ با تتر

GET /wallet/crypto/options

نشان می‌دهد شارژ با تتر در دسترس است یا نه، کدام شبکه‌ها باز هستند (ترون TRC20، اتریوم ERC20 و پس از فعال‌سازی بایننس اسمارت چین BEP20) و حداقل مبلغ چقدر است.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: enabled (boolean), card_enabled (boolean), network (string), network_label (string), currency (string), networks (فهرستی از CryptoNetwork), default_network (string), min_usdt (string), expiry_minutes (integer).

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/crypto/options \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

فهرست شبکه‌های تتر

GET /wallet/crypto/networks

شبکه‌های باز را همراه با تخمین کارمزد شبکه (آنچه فرستنده به شبکه می‌پردازد، به TRX، ETH یا BNB؛ هرگز به مبلغ تتر اضافه نمی‌شود) و تخمین زمان برمی‌گرداند. کارمزد فقط تخمین است و ممکن است موجود نباشد: کارمزد نهایی را کیف پول شما تعیین می‌کند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از CryptoNetwork).

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/crypto/networks \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

قیمت شارژ با تتر

GET /wallet/crypto/quote

مبلغ ریالی (amount_rial) یا تتری (amount_usdt) را با نرخ فعلی به مبلغ پایهٔ تتر تبدیل می‌کند. با network (tron، ethereum یا bsc) کارمزد خدمات آن شبکه هم لحاظ می‌شود. اگر شارژ با تتر خاموش باشد 404 برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای query

فیلد	نوع	مقادیر
`amount_rial`	integer
`amount_usdt`	string
`network`	string	`tron`, `ethereum`, `bsc`

پاسخ‌ها

200 موفق. برمی‌گرداند: network (string), base_usdt (string), service_fee (string), amount_before_suffix (string), usd_equivalent (string), rial_amount (integer), effective_rate (string), fx_rate_id (integer), min_usdt (string), below_minimum (boolean).
404 پیدا نشد
503 موقتاً در دسترس نیست

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/crypto/quote \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

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

GET /wallet/crypto/invoices

آخرین فاکتورهای شارژ با تتر شما را برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پاسخ‌ها

200 موفق. برمی‌گرداند: data (فهرستی از CryptoInvoice).

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/crypto/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

ساخت فاکتور شارژ با تتر

POST /wallet/crypto/invoices

فاکتوری برای network انتخابی (tron، ethereum یا bsc) می‌سازد با مبلغ دقیق قابل ارسال (مبلغ شارژ به‌علاوهٔ کارمزد خدمات ما در صورت وجود و چند رقم شناسایی)، آدرس دریافت، تخمین کارمزد و زمان شبکه و زمان انقضا. دقیقاً همان مبلغ را روی همان شبکه بفرستید؛ پس از رسیدن انتقال به تأییدهای کافی، کیف پول خودکار شارژ می‌شود. آدرس، قرارداد توکن و زنجیره همیشه از سمت سرور تعیین می‌شوند و شناسهٔ تراکنش هرگز از سمت کلاینت پذیرفته نمی‌شود.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`amount_rial`	integer	خیر
`amount_usdt`	string	خیر
`network`	string	خیر	`tron`, `ethereum`, `bsc`

پاسخ‌ها

201 ایجاد شد. برمی‌گرداند: data (CryptoInvoice).
404 پیدا نشد
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
429 درخواست‌های بیش از حد
503 موقتاً در دسترس نیست

نمونه

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

دریافت یک فاکتور تتر

GET /wallet/crypto/invoices/{id}

یکی از فاکتورهای شما و وضعیت آن را برمی‌گرداند (pending، detected، confirming، paid، expired، manual_review، cancelled)، همراه با تأییدهای تاکنون (timing)، تخمین کارمزد شبکه و نرخ تبدیلی که با آن ساخته شده است (effective_rate، ریال به‌ازای هر دلار). هر ۵ تا ۱۰ ثانیه می‌توان آن را پرس‌وجو کرد.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`id`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (CryptoInvoice).
404 پیدا نشد

نمونه

curl -X GET https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

به‌روزرسانی تخمین کارمزد شبکه

POST /wallet/crypto/invoices/{id}/refresh-fee

فقط تخمین کارمزد و زمان شبکهٔ یکی از فاکتورهای باز شما را دوباره محاسبه می‌کند. مبلغ قابل ارسال هرگز تغییر نمی‌کند. حداکثر ۱۲ بار در دقیقه.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`id`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (CryptoInvoice).
404 پیدا نشد

نمونه

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID/refresh-fee \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

لغو یک فاکتور تتر

POST /wallet/crypto/invoices/{id}/cancel

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

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

پارامترهای مسیر

فیلد	نوع
`id`	integer

پاسخ‌ها

200 موفق. برمی‌گرداند: data (CryptoInvoice).
404 پیدا نشد
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی

نمونه

curl -X POST https://veneshcloud.ir/api/wallet/crypto/invoices/KEY_ID/cancel \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json"

شروع شارژ

POST /wallet/topup

یک شارژ می‌سازد و redirect_url یعنی صفحهٔ پرداخت بانک را برمی‌گرداند. برای پرداخت آن را در مرورگر باز کنید؛ بانک سپس کاربر را به سایت برمی‌گرداند.

احراز هویت: کلید API یا توکن خود را به‌صورت Bearer بفرستید.

بدنهٔ درخواست (application/json)

فیلد	نوع	الزامی	مقادیر
`amount_rial`	integer	بله

پاسخ‌ها

200 موفق. برمی‌گرداند: topup_id (integer), redirect_url (string).
422 خطای اعتبارسنجی یا مجاز نبودن در وضعیت فعلی
502 خطای ارائه‌دهنده
503 موقتاً در دسترس نیست

نمونه

curl -X POST https://veneshcloud.ir/api/wallet/topup \
  -H "Authorization: Bearer $VENESH_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount_rial":<AMOUNT_IN_RIAL>}'

اشیاء

فهرست فیلدهای اشیایی که در بالا برگردانده می‌شوند.

CryptoInvoice

فیلد	نوع	مقادیر
`id`	integer
`status`	string	`pending`, `detected`, `confirming`, `paid`, `expired`, `manual_review`, `cancelled`
`currency`	string
`network`	object
`network_label`	string
`token`	object
`token_contract`	string
`address`	string
`amount`	string
`base_amount`	string
`pricing`	object
`received_amount`	string
`usd_equivalent`	string
`rial_amount`	integer
`network_fee`	`CryptoNetworkFee`
`timing`	object
`expires_at`	string
`detected_at`	string
`confirmed_at`	string
`paid_at`	string
`created_at`	string
`tx_hash`	string
`explorer_tx_url`	string
`fx_rate_id`	integer
`effective_rate`	string
`cancelled_at`	string
`paid_after_cancel`	boolean
`cancellable`	boolean

CryptoNetwork

فیلد	نوع	مقادیر
`key`	string	`tron`, `ethereum`, `bsc`
`name`	string
`token`	string
`token_note`	string
`chain_id`	integer
`fee_currency`	string	`TRX`, `ETH`, `BNB`
`service_fee`	string
`required_confirmations`	integer
`estimated_time_min_seconds`	integer
`estimated_time_max_seconds`	integer
`network_fee`	`CryptoNetworkFee`

CryptoNetworkFee

فیلد	نوع	مقادیر
`currency`	string
`estimated_native_amount`	string
`estimated_usd_amount`	string
`is_estimate`	boolean
`available`	boolean
`determined_by_wallet`	boolean
`quoted_at`	string
`expires_at`	string

Invoice

فیلد	نوع	مقادیر
`id`	integer
`invoice_number`	string
`type`	string	`topup`, `order_charge`, `renewal_charge`, `refund`, `admin_adjustment`
`direction`	string	`credit`, `debit`
`date`	string
`description`	string
`amount_usd`	string
`rial_amount`	integer
`type_label`	string
`status`	string	`paid`
`status_label`	string
`reference_type`	string
`reference_id`	integer

WalletBalance

فیلد	نوع	مقادیر
`balance_usd`	string
`balance_rial`	integer
`vm_policy`	object
`fx`	object

WalletLedgerEntry

فیلد	نوع	مقادیر
`id`	integer
`type`	string	`topup`, `order_charge`, `renewal_charge`, `refund`, `admin_adjustment`
`amount_usd`	string
`balance_after_usd`	string
`balance_after_rial`	integer
`rial_amount`	integer
`amount_rial`	integer
`type_label`	string
`fx_rate_id`	integer
`reference_type`	string
`reference_id`	integer
`description`	string
`created_at`	string