مستندات اتصال عامل‌های فروش

curl -X POST https://api.example-coop.ir/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "agent_key": "AGT-724-XXXX",
    "agent_secret": "your-secret-key"
  }'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

curl "https://api.example-coop.ir/v1/cities?search=تهران" \
  -H "Authorization: Bearer {access_token}"

{
  "success": true,
  "data": [
    {
      "city_id": 101,
      "name": "تهران",
      "province": "تهران",
      "terminals": [
        { "terminal_id": 5, "name": "پایانه بیهقی" },
        { "terminal_id": 8, "name": "پایانه جنوب" }
      ]
    }
  ]
}

curl "https://api.example-coop.ir/v1/services?origin_city_id=101&destination_city_id=205&date=2026-07-20" \
  -H "Authorization: Bearer {access_token}"

{
  "success": true,
  "data": {
    "services": [
      {
        "service_id": "SRV-84213",
        "origin": { "city_id": 101, "name": "تهران", "terminal": "پایانه بیهقی" },
        "destination": { "city_id": 205, "name": "اصفهان", "terminal": "پایانه کاوه" },
        "departure_at": "2026-07-20T08:30:00+03:30",
        "vehicle": { "type": "sedan", "model": "پژو پارس", "plate": "۱۲ب۳۴۵-۱۰" },
        "price": 2500000,
        "currency": "IRR",
        "capacity": { "total": 4, "available": 3 },
        "cooperative": { "id": 12, "name": "تعاونی شماره ۴" },
        "status": "open"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 8 }
  }
}

curl "https://api.example-coop.ir/v1/services/SRV-84213" \
  -H "Authorization: Bearer {access_token}"

{
  "success": true,
  "data": {
    "service_id": "SRV-84213",
    "departure_at": "2026-07-20T08:30:00+03:30",
    "driver": { "name": "ع. محمدی", "rating": 4.8 },
    "vehicle": { "type": "sedan", "model": "پژو پارس", "year": 1402 },
    "price": 2500000,
    "refund_policy": {
      "before_24h_percent": 90,
      "before_2h_percent": 50,
      "after_2h_percent": 0
    },
    "seats": [
      { "seat_number": 1, "status": "sold" },
      { "seat_number": 2, "status": "available" },
      { "seat_number": 3, "status": "available" },
      { "seat_number": 4, "status": "locked" }
    ]
  }
}

curl -X POST https://api.example-coop.ir/v1/reservations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "SRV-84213",
    "seat_numbers": [2, 3],
    "passengers": [
      { "full_name": "علی رضایی", "national_id": "0012345678", "phone": "09121234567" },
      { "full_name": "مریم رضایی", "national_id": "0087654321", "phone": "09121234567" }
    ]
  }'

{
  "success": true,
  "data": {
    "reservation_id": "RSV-55102",
    "status": "pending",
    "expires_at": "2026-07-15T10:42:00+03:30",
    "total_amount": 5000000,
    "currency": "IRR"
  }
}

curl -X POST https://api.example-coop.ir/v1/reservations/RSV-55102/confirm \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "payment_reference": "PAY-998877" }'

{
  "success": true,
  "data": {
    "tickets": [
      {
        "ticket_number": "TKT-2026-771001",
        "passenger": "علی رضایی",
        "seat_number": 2,
        "qr_code_url": "https://api.example-coop.ir/v1/tickets/TKT-2026-771001/qr"
      },
      {
        "ticket_number": "TKT-2026-771002",
        "passenger": "مریم رضایی",
        "seat_number": 3,
        "qr_code_url": "https://api.example-coop.ir/v1/tickets/TKT-2026-771002/qr"
      }
    ],
    "issued_at": "2026-07-15T10:38:12+03:30"
  }
}

curl "https://api.example-coop.ir/v1/tickets/TKT-2026-771001" \
  -H "Authorization: Bearer {access_token}"

{
  "success": true,
  "data": {
    "ticket_number": "TKT-2026-771001",
    "status": "issued",
    "service_id": "SRV-84213",
    "passenger": { "full_name": "علی رضایی", "national_id": "001*****78" },
    "seat_number": 2,
    "price": 2500000,
    "departure_at": "2026-07-20T08:30:00+03:30"
  }
}

curl -X POST https://api.example-coop.ir/v1/tickets/TKT-2026-771001/refund \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "انصراف مسافر" }'

{
  "success": true,
  "data": {
    "ticket_number": "TKT-2026-771001",
    "status": "refunded",
    "refund_amount": 2250000,
    "refund_percent": 90,
    "refunded_at": "2026-07-15T11:02:45+03:30"
  }
}