فضای کاری TZ

مستندات API

API v1

مستندات TZ Services API

این API برای کلاینت‌های B2B طراحی شده است. base URL نصب شما برابر https://stage.ehsantz.pingbaz.space/api/v1 است. همه پاسخ‌ها JSON و دارای request_id هستند.

در v1 فقط Mock Provider فعال است. نام سرویس‌ها و IDها را همیشه از /services بخوانید.

احراز هویت HMAC

کلید عمومی، timestamp، nonce و signature را در هر درخواست بفرستید. canonical string:

METHOD + "\n" + CANONICAL_TARGET + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(BODY)

امضا: HMAC-SHA256(canonical, secret). timestamp بیشتر از ۵ دقیقه و nonce تکراری رد می‌شود؛ query نرمال/مرتب و query key تکراری رد می‌شود.

سرویس‌ها و موجودی

GET /api/v1/services
GET /api/v1/balance
GET /api/v1/profile

قیمت کلاینت نمایش داده می‌شود؛ هزینه داخلی provider هرگز در پاسخ نیست.

سفارش‌ها

POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: order-unique-001

{"service_id": 1, "quantity": 100}

در وضعیت کمبود موجودی HTTP 422 و در استفاده مجدد از کلید با payload متفاوت HTTP 409 دریافت می‌کنید.

GET /api/v1/orders
GET /api/v1/orders/TZ-20260915-000001
GET /api/v1/transactions

وب‌هوک‌ها

GET  /api/v1/webhook
POST /api/v1/webhook
POST /api/v1/webhook/test

رویدادهای order.created، order.processing، order.completed، order.failed، order.cancelled، order.refunded، order.provider_unknown و wallet.updated پشتیبانی می‌شوند.

خطا، rate limit و request ID

{"success":false,"request_id":"req_...","error":{"code":"...","message":"..."}}

محدودیت پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید است و پاسخ 429 هدر Retry-After منطقی دارد.

مثال‌های اتصال

curl -X GET "https://example.com/api/v1/services" \
  -H "X-TZ-Key: tzk_..." \
  -H "X-TZ-Timestamp: 1730000000" \
  -H "X-TZ-Nonce: 0123456789abcdef" \
  -H "X-TZ-Signature: SIGNATURE"

// PHP: از hash_hmac("sha256", $canonical, $secret) استفاده کنید.
// Python: hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
// JS: در محیط سرور Node با crypto.createHmac("sha256", secret) انجام دهید.