---
title: شروع سریع: اولین درخواست به Stard API
url: https://stard-market.ir/docs/getting-started
markdown: https://stard-market.ir/docs/getting-started.md
language: fa
updated: 2026-11-18
description: در پنج قدم: ورود، ساخت کلید test، اولین درخواست، اولین سفارش آزمایشی و رفتن به live.
---

# شروع سریع: اولین درخواست به Stard API

> در پنج قدم: ورود، ساخت کلید test، اولین درخواست، اولین سفارش آزمایشی و رفتن به live.

## ۱. ورود به داشبورد

به [داشبورد توسعه‌دهندگان](https://stard-market.ir/developers/login) برو و با تلگرام (کد ربات @Stard_marketbot) یا گوگل وارد شو. یک پروژه‌ی پیش‌فرض و ۱۰۰ میلیون تومان موجودی آزمایشی برایت ساخته می‌شود.

## ۲. ساخت کلید test

در بخش «کلیدهای API» یک کلید با محیط **test** بساز. کلید فقط **همان یک بار** نمایش داده می‌شود؛ آن را در متغیر محیطی نگه دار، نه در کد:

**ترمینال**

```bash
export STARD_API_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## ۳. اولین درخواست

قیمت ۵۰۰ استارز را بگیر:

```bash
curl "https://stard-market.ir/api/v1/stars/price?quantity=500" \
  -H "Authorization: Bearer $STARD_API_KEY"
```

```javascript
const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

```typescript
type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } };

const res = await fetch("https://stard-market.ir/api/v1/stars/price?quantity=500", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
  },
});
if (!res.ok) {
  const { error } = (await res.json()) as StardError;
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const data: Record<string, unknown> = await res.json();
```

```python
import os
import requests

r = requests.get(
    "https://stard-market.ir/api/v1/stars/price?quantity=500",
    headers={
    "Authorization": f"Bearer {os.environ['STARD_API_KEY']}",
    },
    timeout=20,
)
data = r.json()
if r.status_code >= 400:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

```php
<?php
$ch = curl_init("https://stard-market.ir/api/v1/stars/price?quantity=500");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("STARD_API_KEY"),
  ],
  CURLOPT_TIMEOUT => 20,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
  throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
}
print_r($data);
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://stard-market.ir/api/v1/stars/price?quantity=500", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(b))
}
```

**پاسخ — 200**

```json
{
  "object": "stars_price",
  "quantity": 500,
  "unit_price": 4382,
  "amount": 2191000,
  "currency": "IRT",
  "updated_at": "2026-10-01T10:31:49Z"
}
```

## ۴. اولین سفارش آزمایشی

با کلید test سفارش در sandbox ثبت می‌شود؛ همه‌ی اعتبارسنجی‌ها و قیمت‌ها واقعی‌اند ولی پولی جابه‌جا نمی‌شود:

```bash
curl -X POST "https://stard-market.ir/api/v1/orders" \
  -H "Authorization: Bearer $STARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-order-1" \
  -d '{"type": "stars", "quantity": 500, "recipient": "@durov"}'
```

```javascript
const res = await fetch("https://stard-market.ir/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "first-order-1",
  },
  body: JSON.stringify({
    "type": "stars",
    "quantity": 500,
    "recipient": "@durov"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

```typescript
type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } };

const res = await fetch("https://stard-market.ir/api/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "first-order-1",
  },
  body: JSON.stringify({
    "type": "stars",
    "quantity": 500,
    "recipient": "@durov"
  }),
});
if (!res.ok) {
  const { error } = (await res.json()) as StardError;
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const data: Record<string, unknown> = await res.json();
```

```python
import os
import requests

r = requests.post(
    "https://stard-market.ir/api/v1/orders",
    headers={
    "Authorization": f"Bearer {os.environ['STARD_API_KEY']}",
    "Idempotency-Key": "first-order-1",
    },
    json={
        "type": "stars",
        "quantity": 500,
        "recipient": "@durov"
    },
    timeout=20,
)
data = r.json()
if r.status_code >= 400:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

```php
<?php
$ch = curl_init("https://stard-market.ir/api/v1/orders");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("STARD_API_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: first-order-1",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "type" => "stars",
    "quantity" => 500,
    "recipient" => "@durov"
  ]),
  CURLOPT_TIMEOUT => 20,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
  throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
}
print_r($data);
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"type": "stars", "quantity": 500, "recipient": "@durov"}`)
	req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/orders", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "first-order-1")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(b))
}
```

**پاسخ — 201**

```json
{
  "object": "order",
  "id": "ord_test_TyrINakBwx0N66kV",
  "order_id": null,
  "environment": "test",
  "status": "pending",
  "raw_status": "pending",
  "title": "⭐ 500 استارز برای @durov (test)",
  "product_id": null,
  "product_tag": null,
  "type": "stars",
  "quantity": 500,
  "recipient": "@durov",
  "amount": {
    "amount": 2191000,
    "currency": "IRT"
  },
  "paid": {
    "amount": 2191000,
    "currency": "IRT"
  },
  "failure_reason": null,
  "metadata": {},
  "created_at": "2026-10-01T10:31:49Z",
  "updated_at": "2026-10-01T10:31:49Z"
}
```

## ۵. رفتن به live

وقتی یکپارچه‌سازی کامل شد، حساب تلگرام Stard را در داشبورد وصل کن (اگر با گوگل وارد شده‌ای)، از بخش «کیف پول API» داشبورد با یک کلیک از ولت TON خودت (Tonkeeper یا هر ولت) شارژ کن و یک کلید **live** بساز. کد تو تغییری نمی‌کند؛ فقط کلید عوض می‌شود. [تفاوت test و live](https://stard-market.ir/docs/sandbox)
