توسعه‌دهندگان

مرجع API

همه اندپوینت‌های REST در SMetaGateway، تولیدشده از قرارداد OpenAPI 3.1. از سرور خود با کلید API نوع Bearer استفاده کنید؛ مبالغ رشته‌های اعشاری هستند.

آدرس پایه: https://smg.sabco24.com/api/v1
نسخه: 0.2.0 · OpenAPI 3.1

باز کردن Swagger UI OpenAPI JSON

اندپوینت‌ها

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

متد	مسیر	توضیح	احراز هویت
سیستم
GET	`/health`	بررسی سلامت سرویس و حالت درگاه.	عمومی
GET	`/config`	خواندن پیکربندی عمومی کلاینت، از جمله کلید سایت کپچا.	عمومی
احراز هویت
POST	`/auth/register`	ثبت‌نام فروشنده و شروع نشست مالک.	عمومی
POST	`/auth/login`	ورود و شروع نشست مالک.	عمومی
POST	`/auth/verify-email`	تأیید نشانی ایمیل با پیوند ارسال‌شده و شروع نشست مالک.	عمومی
POST	`/auth/password/forgot`	ارسال پیوند بازنشانی گذرواژه به ایمیل.	عمومی
POST	`/auth/password/reset`	تعیین گذرواژه جدید با پیوند بازنشانی و ورود.	عمومی
POST	`/auth/google`	ورود یا ثبت‌نام با گوگل و شروع نشست مالک.	عمومی
GET	`/auth/session`	بررسی اینکه آیا این مرورگر وارد شده است.	عمومی
POST	`/auth/logout`	پایان نشست فعلی مالک.	عمومی
حساب
GET	`/me`	دریافت حساب فروشنده، کیف پول‌ها، فاکتورها، کلیدها، وب‌هوک‌ها و آمار.	نشست مالک
PATCH	`/me`	به‌روزرسانی نام نمایشی فروشنده.	نشست مالک
کیف پول‌ها
GET	`/wallets`	فهرست آدرس‌های دریافت ثبت‌شده.	کلید API یا نشست
POST	`/wallets`	ثبت آدرس دریافت ترون با چک‌سام معتبر (مالکیت تأیید نشده است).	نشست مالک
فاکتورها
GET	`/invoices`	فهرست ۵۰۰ فاکتور اخیر.	کلید API یا نشست
POST	`/invoices`	ساخت فاکتور و رزرو یک مبلغ دقیق و یکتا به مدت ۹۰ روز.	کلید API یا نشست
GET	`/invoices/{id}`	دریافت یک فاکتور متعلق به این فروشنده.	کلید API یا نشست
صفحه پرداخت
GET	`/checkout/{token}`	خواندن جزئیات ایمن پرداخت با توکن صفحه پرداخت.	عمومی
کلیدهای API
POST	`/api-keys`	ساخت کلید API با انقضای اختیاری؛ رمز فقط یک بار نمایش داده می‌شود.	نشست مالک
POST	`/api-keys/{id}/roll`	جایگزینی کلید API با رمز جدید با همان نام و مدت اعتبار.	نشست مالک
DELETE	`/api-keys/{id}`	لغو فوری کلید API.	نشست مالک
دفتر
GET	`/ledger.csv`	خروجی کامل دفتر عملیاتی به‌صورت CSV.	کلید API یا نشست
وب‌هوک‌ها
POST	`/webhooks`	ثبت اندپوینت وب‌هوک عمومی HTTPS؛ رمز امضا فقط یک بار نمایش داده می‌شود.	نشست مالک
DELETE	`/webhooks/{id}`	غیرفعال‌سازی اندپوینت و لغو ارسال‌های در انتظار.	نشست مالک
POST	`/webhooks/{id}/test`	ارسال رویداد امضاشده webhook.test.	نشست مالک
POST	`/webhooks/deliveries/{id}/retry`	تلاش مجدد برای ارسال وب‌هوک ناموفق یا در انتظار.	نشست مالک
پشتیبانی
POST	`/support/chat`	شروع گفت‌وگوی وب‌سایت با نام، ایمیل و اولین پیام؛ یک توکن خصوصی گفت‌وگو برمی‌گرداند.	عمومی
GET	`/support/chat`	خواندن گفت‌وگوی وب‌سایت با توکن آن.	عمومی
POST	`/support/chat/messages`	ارسال پیام بعدی در گفت‌وگوی وب‌سایت؛ گفت‌وگوی بسته دوباره باز می‌شود.	عمومی
POST	`/support/contact`	ارسال پیام به پشتیبانی بدون حساب کاربری.	عمومی
GET	`/support/tickets`	فهرست تیکت‌های پشتیبانی شما.	نشست مالک
POST	`/support/tickets`	باز کردن تیکت پشتیبانی.	نشست مالک
GET	`/support/tickets/{id}`	خواندن یکی از تیکت‌ها همراه با پیام‌هایش.	نشست مالک
POST	`/support/tickets/{id}/messages`	پاسخ به تیکت؛ تیکت بسته دوباره باز می‌شود.	نشست مالک
POST	`/support/tickets/{id}/close`	بستن تیکت.	نشست مالک
GET	`/support/inbox`	تیم پشتیبانی: فهرست همه تیکت‌ها، ابتدا تیکت‌های باز.	نشست مالک
GET	`/support/inbox/{id}`	تیم پشتیبانی: خواندن تیکت همراه با اطلاعات تماس.	نشست مالک
POST	`/support/inbox/{id}/messages`	تیم پشتیبانی: پاسخ به تیکت فروشنده.	نشست مالک
POST	`/support/inbox/{id}/status`	تیم پشتیبانی: تغییر وضعیت تیکت.	نشست مالک

سیستم

GET`/api/v1/health`

عمومی

بررسی سلامت سرویس و حالت درگاه.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`status`	`"ok"`	خیر
`mode`	`"live"`	خیر	Invoices are confirmed from verified TRON mainnet transfers.
`live_payments_enabled`	`true`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/health"

GET`/api/v1/config`

عمومی

خواندن پیکربندی عمومی کلاینت، از جمله کلید سایت کپچا.

captcha is null when Cloudflare Turnstile is not configured; otherwise send captcha_token with sign-in, registration, contact and chat requests. google is null when Google sign-in is not configured.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`captcha`	`object`	بله
`google`	`object`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/config"

احراز هویت

POST`/api/v1/auth/register`

عمومی

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

No session is started. The account can sign in after the emailed link (valid 24 hours, single use) is confirmed with POST /auth/verify-email. Answers 503 email_unavailable when the server cannot send email.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`email`	`string (email)`	بله
`password`	`string (password)`	بله	length 12–128
`captcha_token`	`string`	خیر	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`name`	`string`	خیر	length 0–100
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	خیر	Language of the email. — default "en"

خروجی: 201 application/json

فیلد	نوع	الزامی	توضیح
`verification_required`	`true`	بله
`email`	`string (email)`	بله
`email_sent`	`boolean`	بله	False when the SMTP server rejected the message; signing in later sends a new link.

پاسخ‌ها

201Account created; confirmation email sent
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Email delivery is not configured (email_unavailable) or captcha verification is unavailable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Store","email":"merchant@example.com","password":"a-long-unique-passphrase","locale":"en"}'

POST`/api/v1/auth/login`

عمومی

ورود و شروع نشست مالک.

An account whose email is not yet confirmed answers 403 email_not_verified after a correct password, and a new confirmation link is emailed at most every 5 minutes.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`email`	`string (email)`	بله
`password`	`string (password)`	بله	length 10–128
`captcha_token`	`string`	خیر	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	خیر	Language of the email. — default "en"

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`merchant`	`Merchant`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","password":"a-long-unique-passphrase"}'

POST`/api/v1/auth/verify-email`

عمومی

تأیید نشانی ایمیل با پیوند ارسال‌شده و شروع نشست مالک.

token comes from the #verify= fragment of the emailed link. Tokens are single use; a newer email replaces older links.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`token`	`string`	بله	Single-use token from the emailed link. — pattern ^[A-Za-z0-9_-]{43}$

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`merchant`	`Merchant`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAILED_LINK"}'

POST`/api/v1/auth/password/forgot`

عمومی

ارسال پیوند بازنشانی گذرواژه به ایمیل.

Always answers 202 whether or not an account exists. The link is valid for 1 hour and single use.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`email`	`string (email)`	بله
`captcha_token`	`string`	خیر	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048
`locale`	`"en" \| "fa" \| "ar" \| "zh" \| "es" \| "fr" \| "ru"`	خیر	Language of the email. — default "en"

خروجی: 202 application/json

فیلد	نوع	الزامی	توضیح
`success`	`true`	بله

پاسخ‌ها

202Accepted
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Email delivery is not configured (email_unavailable) or captcha verification is unavailable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","locale":"en"}'

POST`/api/v1/auth/password/reset`

عمومی

تعیین گذرواژه جدید با پیوند بازنشانی و ورود.

token comes from the #reset= fragment of the emailed link. Every existing session of the account is revoked, and the email counts as confirmed.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`token`	`string`	بله	Single-use token from the emailed link. — pattern ^[A-Za-z0-9_-]{43}$
`password`	`string (password)`	بله	length 12–128

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`merchant`	`Merchant`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_FROM_THE_EMAILED_LINK","password":"a-new-long-unique-passphrase"}'

POST`/api/v1/auth/google`

عمومی

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

Send the credential returned by Google Identity Services. The server verifies the RS256 signature against Google keys, the issuer, audience (GOOGLE_CLIENT_ID), expiry and email_verified. A new email creates an account (201). An existing confirmed account with the same email is linked to the Google account on first use; an unconfirmed one is claimed by the Google owner and its password stops working.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`credential`	`string`	بله	Google ID token (JWT). — length 20–4096

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`merchant`	`Merchant`	خیر

پاسخ‌ها

200Signed in
201Account created
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Google keys are temporarily unreachable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/google" \
  -H "Content-Type: application/json" \
  -d '{"credential":"GOOGLE_ID_TOKEN_FROM_GOOGLE_IDENTITY_SERVICES"}'

GET`/api/v1/auth/session`

عمومی

بررسی اینکه آیا این مرورگر وارد شده است.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`signed_in`	`boolean`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/auth/session"

POST`/api/v1/auth/logout`

عمومی

پایان نشست فعلی مالک.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`success`	`true`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/auth/logout" \
  -H "Content-Type: application/json" \
  -d '{}'

حساب

GET`/api/v1/me`

نشست مالک

دریافت حساب فروشنده، کیف پول‌ها، فاکتورها، کلیدها، وب‌هوک‌ها و آمار.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

خروجی: 200 Dashboard

فیلد	نوع	الزامی
`merchant`	`Merchant`	بله
`wallets`	`Wallet[]`	بله
`invoices`	`Invoice[]`	بله
`events`	`Event[]`	بله
`api_keys`	`ApiKey[]`	بله
`webhooks`	`Webhook[]`	بله
`deliveries`	`Delivery[]`	بله
`stats`	`object`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

PATCH`/api/v1/me`

نشست مالک

به‌روزرسانی نام نمایشی فروشنده.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`name`	`string`	بله	length 1–100

خروجی: 200 Dashboard

فیلد	نوع	الزامی
`merchant`	`Merchant`	بله
`wallets`	`Wallet[]`	بله
`invoices`	`Invoice[]`	بله
`events`	`Event[]`	بله
`api_keys`	`ApiKey[]`	بله
`webhooks`	`Webhook[]`	بله
`deliveries`	`Delivery[]`	بله
`stats`	`object`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X PATCH "https://smg.sabco24.com/api/v1/me" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

کیف پول‌ها

GET`/api/v1/wallets`

کلید API یا نشست

فهرست آدرس‌های دریافت ثبت‌شده.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`wallets`	`Wallet[]`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/wallets" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/wallets`

نشست مالک

ثبت آدرس دریافت ترون با چک‌سام معتبر (مالکیت تأیید نشده است).

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`label`	`string`	بله	length 1–80
`address`	`string`	بله	pattern ^T[1-9A-HJ-NP-Za-km-z]{33}$

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`wallet`	`Wallet`	خیر

پاسخ‌ها

200Existing address
201Registered
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/wallets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"label":"Main business wallet","address":"T_YOUR_PUBLIC_TRON_ADDRESS"}'

فاکتورها

GET`/api/v1/invoices`

کلید API یا نشست

فهرست ۵۰۰ فاکتور اخیر.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`invoices`	`Invoice[]`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY"

POST`/api/v1/invoices`

کلید API یا نشست

ساخت فاکتور و رزرو یک مبلغ دقیق و یکتا به مدت ۹۰ روز.

Amount allocation is global for (network, token contract, receiving address, final payable micro-units), including merchants sharing an address. Reservations outlive invoice expiry. Historical amount reuse is assigned review status. The invoice is confirmed only when a verified TRON transfer of exactly payable_amount reaches wallet_address between creation and expiry.

هدرهای الزامی

فیلد	نوع	الزامی	توضیح
`Idempotency-Key`	`string`	بله	کلیدی یکتا برای هر تلاش ساخت فاکتور؛ هنگام تلاش مجدد از همان کلید استفاده کنید.

بدنه درخواست `CreateInvoice`

فیلد	نوع	الزامی	توضیح
`merchant_order_id`	`string`	بله	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	بله	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	بله	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	خیر	length 1–1000
`metadata`	`object`	خیر	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	خیر	range 1–1440 · default 20

خروجی: 200 InvoiceEnvelope

فیلد	نوع	الزامی	توضیح
`invoice`	`Invoice`	بله
`idempotent_replay`	`boolean`	خیر

پاسخ‌ها

200Identical idempotent replay
201Invoice allocated
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/invoices" \
  -H "Authorization: Bearer $SMETA_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"merchant_order_id":"1001","amount":"49.95","wallet_id":"WALLET_ID","description":"Example order","expires_in_minutes":20}'

GET`/api/v1/invoices/{id}`

کلید API یا نشست

دریافت یک فاکتور متعلق به این فروشنده.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Invoice ID

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`invoice`	`Invoice`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/invoices/ID" \
  -H "Authorization: Bearer $SMETA_API_KEY"

صفحه پرداخت

GET`/api/v1/checkout/{token}`

عمومی

خواندن جزئیات ایمن پرداخت با توکن صفحه پرداخت.

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

فیلد	نوع	الزامی	توضیح
`token`	`string`	بله	Checkout capability token from checkout_url

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`invoice`	`CheckoutInvoice`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/checkout/TOKEN"

کلیدهای API

POST`/api/v1/api-keys`

نشست مالک

ساخت کلید API با انقضای اختیاری؛ رمز فقط یک بار نمایش داده می‌شود.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`name`	`string`	بله	length 1–80
`expires_in_days`	`integer \| null`	خیر	Days until the key expires. Omit or send null for a key that never expires. — range 1–3650 · e.g. 90

خروجی: 201 application/json

فیلد	نوع	الزامی
`api_key`	`ApiKey & object`	خیر
`secret`	`string`	خیر
`warning`	`string`	خیر

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/api-keys" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'

POST`/api/v1/api-keys/{id}/roll`

نشست مالک

جایگزینی کلید API با رمز جدید با همان نام و مدت اعتبار.

The old key is revoked in the same transaction. The new secret is shown once.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	API key ID

خروجی: 201 application/json

فیلد	نوع	الزامی
`api_key`	`ApiKey & object`	خیر
`secret`	`string`	خیر
`warning`	`string`	خیر
`replaced_key_id`	`string`	خیر

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/api-keys/ID/roll" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE`/api/v1/api-keys/{id}`

نشست مالک

لغو فوری کلید API.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	API key ID

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`success`	`true`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X DELETE "https://smg.sabco24.com/api/v1/api-keys/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

دفتر

GET`/api/v1/ledger.csv`

کلید API یا نشست

خروجی کامل دفتر عملیاتی به‌صورت CSV.

خروجی: 200 text/csv

پاسخ‌ها

200CSV includes separate base, adjustment and payable columns; not a statutory accounting report.
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/ledger.csv" \
  -H "Authorization: Bearer $SMETA_API_KEY"

وب‌هوک‌ها

POST`/api/v1/webhooks`

نشست مالک

ثبت اندپوینت وب‌هوک عمومی HTTPS؛ رمز امضا فقط یک بار نمایش داده می‌شود.

Port 443 only. Local/private targets, IP literals, credentials, URL fragments and redirects are rejected. DNS is resolved and checked again at delivery time.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`url`	`string (uri)`	بله	length 0–2048

خروجی: 201 application/json

فیلد	نوع	الزامی	توضیح
`webhook`	`Webhook & object`	خیر
`secret`	`string`	خیر

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/webhooks" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://merchant.example.com/hooks/smeta"}'

DELETE`/api/v1/webhooks/{id}`

نشست مالک

غیرفعال‌سازی اندپوینت و لغو ارسال‌های در انتظار.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Webhook ID

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`success`	`true`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X DELETE "https://smg.sabco24.com/api/v1/webhooks/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/webhooks/{id}/test`

نشست مالک

ارسال رویداد امضاشده webhook.test.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Webhook ID

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`event`	`Event`	خیر
`deliveries`	`Delivery[]`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/ID/test" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`/api/v1/webhooks/deliveries/{id}/retry`

نشست مالک

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

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Delivery ID

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`delivery`	`Delivery`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/webhooks/deliveries/ID/retry" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST`https://your-server.example/hooks/smeta`

Receive a signed gateway event at your configured URL

Verify HMAC-SHA256(secret, timestamp + "." + original raw body). The signature header is sha256=<lowercase hex>. Reject timestamps outside your five-minute window and deduplicate event IDs. Each retry is freshly signed. GET the saved invoice with your server key and reconcile it before fulfilling once. invoice.confirmed includes the matched on-chain transaction.

هدرهای الزامی

X-SMeta-Event-IdX-SMeta-TimestampX-SMeta-Signature

پاسخ‌ها

200Persisted successfully or already processed. Any 2xx acknowledges delivery.
400Invalid event
401Invalid or stale signature
503Temporary failure; retry delivery

پشتیبانی

POST`/api/v1/support/chat`

عمومی

شروع گفت‌وگوی وب‌سایت با نام، ایمیل و اولین پیام؛ یک توکن خصوصی گفت‌وگو برمی‌گرداند.

Opens a ticket from the visitor's first message, name and email. The response contains chat_token, shown only here; send it as X-Support-Chat-Token to read replies and continue. Contact details are never echoed back.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`message`	`string`	بله	length 1–5000
`name`	`string`	بله	length 1–100
`email`	`string (email)`	بله	length 0–254
`captcha_token`	`string`	خیر	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

خروجی: 201 application/json

فیلد	نوع	الزامی	توضیح
`chat_token`	`string`	بله	Private bearer token for this conversation.
`ticket`	`object`	بله
`name`	`string`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/chat" \
  -H "Content-Type: application/json" \
  -d '{"message":"Do you support WooCommerce?","name":"Jane Doe","email":"jane@example.com","captcha_token":"TURNSTILE_RESPONSE_TOKEN"}'

GET`/api/v1/support/chat`

عمومی

خواندن گفت‌وگوی وب‌سایت با توکن آن.

هدرهای الزامی

فیلد	نوع	الزامی	توضیح
`X-Support-Chat-Token`	`string`	بله	chat_token returned when the chat was started. Keep it private; it is the only key to this conversation.

خروجی: 200 application/json

فیلد	نوع	الزامی
`ticket`	`object`	بله
`name`	`string`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/support/chat" \
  -H "X-Support-Chat-Token: VALUE"

POST`/api/v1/support/chat/messages`

عمومی

ارسال پیام بعدی در گفت‌وگوی وب‌سایت؛ گفت‌وگوی بسته دوباره باز می‌شود.

هدرهای الزامی

فیلد	نوع	الزامی	توضیح
`X-Support-Chat-Token`	`string`	بله	chat_token returned when the chat was started. Keep it private; it is the only key to this conversation.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`message`	`string`	بله	length 1–5000

خروجی: 201 application/json

فیلد	نوع	الزامی
`ticket`	`object`	بله
`name`	`string`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/chat/messages" \
  -H "X-Support-Chat-Token: VALUE" \
  -H "Content-Type: application/json" \
  -d '{"message":"Thanks, that helps."}'

POST`/api/v1/support/contact`

عمومی

ارسال پیام به پشتیبانی بدون حساب کاربری.

Creates a ticket that the support team answers by email. Only the reference is returned.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`name`	`string`	بله	length 1–100
`email`	`string (email)`	بله	length 0–254
`subject`	`string`	بله	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	خیر	default "general"
`message`	`string`	بله	length 1–5000
`captcha_token`	`string`	خیر	Cloudflare Turnstile response token. Required when GET /config returns a captcha site key; each token is single use. — length 0–2048

خروجی: 201 application/json

فیلد	نوع	الزامی	توضیح
`ticket`	`object`	خیر

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error
503Captcha verification is temporarily unavailable

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/contact" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","subject":"Question about pricing","category":"general","message":"Do you charge per invoice?","captcha_token":"TURNSTILE_RESPONSE_TOKEN"}'

GET`/api/v1/support/tickets`

نشست مالک

فهرست تیکت‌های پشتیبانی شما.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`tickets`	`SupportTicket[]`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets`

نشست مالک

باز کردن تیکت پشتیبانی.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`subject`	`string`	بله	length 1–150
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	خیر	default "general"
`message`	`string`	بله	length 1–5000

خروجی: 201 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Webhook signature fails","category":"technical","message":"Deliveries return 401 since yesterday."}'

GET`/api/v1/support/tickets/{id}`

نشست مالک

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

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

خروجی: 200 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/support/tickets/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/tickets/{id}/messages`

نشست مالک

پاسخ به تیکت؛ تیکت بسته دوباره باز می‌شود.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`message`	`string`	بله	length 1–5000

خروجی: 201 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/tickets/{id}/close`

نشست مالک

بستن تیکت.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

خروجی: 200 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/tickets/ID/close" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{}'

GET`/api/v1/support/inbox`

نشست مالک

تیم پشتیبانی: فهرست همه تیکت‌ها، ابتدا تیکت‌های باز.

Requires a session for an account listed in SUPPORT_STAFF_EMAILS.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

خروجی: 200 application/json

فیلد	نوع	الزامی	توضیح
`tickets`	`SupportTicket[]`	خیر

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

GET`/api/v1/support/inbox/{id}`

نشست مالک

تیم پشتیبانی: خواندن تیکت همراه با اطلاعات تماس.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

خروجی: 200 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X GET "https://smg.sabco24.com/api/v1/support/inbox/ID" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com"

POST`/api/v1/support/inbox/{id}/messages`

نشست مالک

تیم پشتیبانی: پاسخ به تیکت فروشنده.

Contact-form tickets return 409 email_reply_required because the visitor has no account.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`message`	`string`	بله	length 1–5000

خروجی: 201 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

201Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/messages" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"message":"string"}'

POST`/api/v1/support/inbox/{id}/status`

نشست مالک

تیم پشتیبانی: تغییر وضعیت تیکت.

به کوکی نشست مالک داشبورد نیاز دارد؛ کلیدهای API برای این عملیات پذیرفته نمی‌شوند.

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

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله	Ticket ID

بدنه درخواست

فیلد	نوع	الزامی	توضیح
`status`	`"open" \| "answered" \| "closed"`	بله

خروجی: 200 SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

پاسخ‌ها

200Success
400Validation error
401Authentication required
403Insufficient scope or invalid origin
404Resource not found
409Conflict, exhausted amount pool or manual review required
429Rate limit exceeded
500Internal server error

نمونه درخواست

curl -X POST "https://smg.sabco24.com/api/v1/support/inbox/ID/status" \
  -H "Cookie: smg_session=$SESSION" \
  -H "Origin: https://smg.sabco24.com" \
  -H "Content-Type: application/json" \
  -d '{"status":"open"}'

اسکیماها

اشیایی که API برمی‌گرداند و می‌پذیرد.

Error

فیلد	نوع	الزامی	توضیح
`error`	`object`	بله
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.

Merchant

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`name`	`string`	بله
`email`	`string (email)`	بله
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`support_staff`	`boolean`	خیر	True when this account is listed in SUPPORT_STAFF_EMAILS and may use the support inbox.

SupportTicket

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`reference`	`string`	بله	Human-friendly reference such as SMG-1A2B3C4D5E.
`subject`	`string`	بله
`category`	`"general" \| "payments" \| "technical" \| "account" \| "other"`	بله	default "general"
`status`	`"open" \| "answered" \| "closed"`	بله	open: waiting for support; answered: support replied; closed: resolved.
`source`	`"dashboard" \| "contact" \| "chat"`	بله	dashboard: merchant ticket; contact: contact form, answered by email; chat: website chat widget, answered in place.
`created_at`	`string (date-time)`	بله
`updated_at`	`string (date-time)`	بله
`name`	`string`	خیر	Support inbox only.
`email`	`string (email)`	خیر	Support inbox only.
`merchant_id`	`string \| null`	خیر	Support inbox only. Null for contact-form and website-chat tickets.
`merchant_name`	`string \| null`	خیر	Support inbox only.

SupportMessage

فیلد	نوع	الزامی
`id`	`string`	بله
`author`	`"customer" \| "staff"`	بله
`body`	`string`	بله
`created_at`	`string (date-time)`	بله

SupportThread

فیلد	نوع	الزامی	توضیح
`ticket`	`SupportTicket`	بله
`messages`	`SupportMessage[]`	بله

Wallet

فیلد	نوع	الزامی
`id`	`string`	بله
`label`	`string`	بله
`address`	`string`	بله
`network`	`"tron-mainnet"`	بله
`verified`	`false`	بله
`verification_status`	`"unverified"`	بله
`created_at`	`string (date-time)`	بله

CheckoutInvoice

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`base_amount`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	بله
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	بله
`created_at`	`string (date-time)`	خیر
`expires_at`	`string (date-time)`	خیر
`reserved_until`	`string (date-time)`	خیر
`description`	`string`	خیر
`tx_hash`	`string \| null`	خیر	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	خیر
`token`	`"USDT"`	خیر
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	خیر
`amount_reuse_review`	`boolean`	خیر
`merchant_name`	`string`	بله	Merchant business display name.

Invoice

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`base_amount`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`adjustment`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`payable_amount`	`string`	بله	Exact USDT decimal string, six fractional digits in responses. Never a floating point number. — pattern ^[0-9]+\.[0-9]{6}$ · e.g. "49.953821"
`wallet_address`	`string`	بله
`status`	`"pending" \| "confirmed" \| "expired" \| "review"`	بله
`created_at`	`string (date-time)`	خیر
`expires_at`	`string (date-time)`	خیر
`reserved_until`	`string (date-time)`	خیر
`description`	`string`	خیر
`tx_hash`	`string \| null`	خیر	TRON transaction hash of the matched USDT transfer (64 hex characters).
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`network`	`"tron-mainnet"`	خیر
`token`	`"USDT"`	خیر
`token_contract`	`"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"`	خیر
`amount_reuse_review`	`boolean`	خیر
`checkout_url`	`string (uri)`	خیر
`checkout_token`	`string`	خیر	Capability token. Treat checkout URLs as confidential invoice links.
`merchant_order_id`	`string`	بله
`wallet_id`	`string`	بله
`metadata`	`object`	بله

CreateInvoice

فیلد	نوع	الزامی	توضیح
`merchant_order_id`	`string`	بله	Unique per merchant. Reuse the original idempotency key for retries. — length 1–120
`amount`	`string`	بله	Base price in USDT; minimum 0.000001, maximum 1000000000. The server adds a disclosed identification adjustment. — pattern ^(0\|[1-9][0-9]{0,9})(\.[0-9]{1,6})?$ · e.g. "49.95"
`wallet_id`	`string`	بله	ID of a wallet registered to this merchant. — length 1–100
`description`	`string`	خیر	length 1–1000
`metadata`	`object`	خیر	JSON object, at most 16 KiB when serialized. Keep customer secrets out of metadata.
`expires_in_minutes`	`integer`	خیر	range 1–1440 · default 20

InvoiceEnvelope

فیلد	نوع	الزامی	توضیح
`invoice`	`Invoice`	بله
`idempotent_replay`	`boolean`	خیر

ApiKey

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`name`	`string`	بله
`prefix`	`string`	بله	First characters of the secret, for identification only.
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`scopes`	`"invoices:read" \| "invoices:write" \| "ledger:read"[]`	بله
`created_at`	`string (date-time)`	خیر
`last_used_at`	`string \| null (date-time)`	خیر
`revoked_at`	`string \| null (date-time)`	خیر
`expires_at`	`string \| null (date-time)`	خیر	Null when the key never expires.
`expired`	`boolean`	خیر

Webhook

فیلد	نوع	الزامی
`id`	`string`	بله
`url`	`string (uri)`	بله
`created_at`	`string (date-time)`	خیر
`active`	`boolean`	بله

Delivery

فیلد	نوع	الزامی
`id`	`string`	بله
`webhook_id`	`string`	بله
`event_id`	`string`	بله
`status`	`"pending" \| "sending" \| "delivered" \| "failed" \| "cancelled"`	بله
`attempts`	`integer`	بله
`next_attempt_at`	`string \| null (date-time)`	خیر
`last_error`	`string \| null`	خیر
`response_status`	`integer \| null`	خیر
`created_at`	`string (date-time)`	خیر
`delivered_at`	`string \| null (date-time)`	خیر

Event

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`type`	`"invoice.created" \| "invoice.confirmed" \| "invoice.expired" \| "invoice.review" \| "webhook.test"`	بله
`created_at`	`string (date-time)`	بله
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	بله

ConfirmedEvent

فیلد	نوع	الزامی	توضیح
`id`	`string`	بله
`type`	`"invoice.confirmed"`	بله
`created_at`	`string (date-time)`	بله
`mode`	`"live"`	بله	Invoices are confirmed from verified TRON mainnet transfers.
`data`	`object`	بله

Dashboard

فیلد	نوع	الزامی
`merchant`	`Merchant`	بله
`wallets`	`Wallet[]`	بله
`invoices`	`Invoice[]`	بله
`events`	`Event[]`	بله
`api_keys`	`ApiKey[]`	بله
`webhooks`	`Webhook[]`	بله
`deliveries`	`Delivery[]`	بله
`stats`	`object`	بله

اندپوینت‌ها

سیستم

پاسخ‌ها

پاسخ‌ها

احراز هویت

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

پاسخ‌ها

پاسخ‌ها

حساب

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

کیف پول‌ها

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

فاکتورها

پاسخ‌ها

هدرهای الزامی

بدنه درخواست CreateInvoice

پاسخ‌ها

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

پاسخ‌ها

صفحه پرداخت

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

پاسخ‌ها

کلیدهای API

بدنه درخواست

پاسخ‌ها

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

پاسخ‌ها

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

پاسخ‌ها

دفتر

پاسخ‌ها

وب‌هوک‌ها

بدنه درخواست

پاسخ‌ها

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

پاسخ‌ها

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

پاسخ‌ها

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

پاسخ‌ها

هدرهای الزامی

پاسخ‌ها

پشتیبانی

بدنه درخواست

پاسخ‌ها

هدرهای الزامی

پاسخ‌ها

هدرهای الزامی

بدنه درخواست

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

پاسخ‌ها

بدنه درخواست

پاسخ‌ها

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

پاسخ‌ها

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

بدنه درخواست

پاسخ‌ها

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

پاسخ‌ها

پاسخ‌ها

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

پاسخ‌ها

بدنه درخواست `CreateInvoice`