شروع کار با Tipax API

Authentication – دریافت Access Token

برای استفاده از تمامی Endpoint های API ابتدا باید Access Token دریافت کنید.

POST /api/OM/v3/Account/token

Request Body:

 {
  "username": "string",
  "password": "string",
  "apiKey": "string"
}

پس از دریافت توکن، مقدار accessToken را در Header تمام درخواست‌ها ارسال کنید:

{
  "accessToken": "string",
  "refreshToken": "string"
}

Refresh Token

در صورت منقضی شدن Access Token، می‌توانید بدون ورود مجدد، توکن جدید دریافت کنید.

POST /api/OM/v3/Account/RefreshToken

{
  "refreshToken": "REFRESH_TOKEN"
}

Cities

دریافت لیست شهرها.

GET /api/OM/v3/Cities

200 Response body

[
  {
    "title": "RW city",
    "abbreviation": null,
    "stateId": null,
    "jetId": "3F42A230-101F-4780-A8E3-8FABD642B1E5",
    "latitude": null,
    "longitude": null,
    "id": 3040
  },
  {
    "title": "گلوگاه",
    "abbreviation": null,
    "stateId": 1026,
    "jetId": "69583842-EE68-4088-86CD-2F308EEFBAD4",
    "latitude": 36.72951983,
    "longitude": 53.8108839,
    "id": 1899
  },
.....

CityId خروجی در ثبت آدرس و ثبت سفارش استفاده می‌شود.

Packaging

لیست انواع بسته‌بندی‌های مجاز تیپاکس.

مقادیر معتبر:

    10 → پاکت
    20 → بسته
    50 → مینی‌پک
    60 → بسته حجیم و سنگین

PackagingId برای محاسبه هزینه و ثبت سفارش کاربرد دارد.

Errors & Fixes

خطای 422 Unprocessable Entity در API تیپاکس به این معناست که ساختار JSON معتبر است اما قوانین بیزینسی (Business Rules) رعایت نشده‌اند. این خطا برخلاف 400، معمولاً با اصلاح داده قابل حل است.

Rule #1 — PackType نقطه شروع تمام Validation هاست

Symptom:

422 Validation Error
Invalid PackType

Root Cause:

• ارسال packType هاردکد شده
• استفاده از مقادیر قدیمی یا تستی

Correct Flow:

GET /api/OM/v4/PackingType/GetPackTypes

Developer Note:

• packType یک enum آزاد نیست
• هر Release ممکن است تغییر کند

Rule #2 — packingId به packType وابسته است (Foreign Key Logic)

Symptom:

422 Validation Error
PackingType mismatch

Root Cause:

• packingId متعلق به packType دیگری است

Correct Flow:

GET /api/OM/v4/PackingType/GetPackingTypes

Validation Rule:

packingId.packType === selected packType

Developer Tip:

• packingType را client-side فیلتر کنید
• Backend هرگونه mismatch را Reject می‌کند

Rule #3 — packageContentId یک Enum ساده نیست

Symptom:

422 Validation Error
Invalid package content for PackType

Root Cause:

• packageContentId با packType ناسازگار است

Correct Flow:

GET /api/OM/v4/PackingType/GetPackagingContents

Validation Rule:

packageContentId.packType === packType

Real World Example:

• پاکت (10) × موبایل ❌
• بسته (20) × پوشاک ✅

Rule #4 — Weight & Dimensions = Hard Validation

Symptom:

422 Validation Error
Package dimensions or weight is out of allowed range

Root Cause:

• ابعاد یا وزن خارج از محدودیت packingType

Developer Note:

• این validation POST-request است
• Swagger محدودیت‌ها را کامل نشان نمی‌دهد

Best Practice:

• Validate وزن و ابعاد در Client
• Fallback validation در Backend

Rule #5 — Order of Operations مهم است

Symptom:

422 Validation Error
Invalid order request

Root Cause:

• پرش از PackType
• Hardcode کردن IDها
• عدم Sync بین APIها

Correct Flow:

PackTypes → PackingTypes → PackageContents → Price → Order

✅ Minimal Valid Example

{
  "packType": 20,
  "packingId": 49,
  "packageContentId": 9,
  "weight": 2500,
  "length": 35,
  "width": 25,
  "height": 10
}

✅ این Request تمام Validation Ruleها را پاس می‌کند.

✅ Debug Checklist (Developer Ready)

• ✅ packType از API گرفته شده؟
• ✅ packingId متعلق به همان packType است؟
• ✅ packageContentId با packType match است؟
• ✅ وزن و ابعاد داخل range هستند؟
• ✅ ترتیب فراخوانی API رعایت شده؟

اگر هنوز 422 دارید، به Validation Flow Diagram رجوع کنید.

Address Book

مدیریت و ثبت آدرس فرستنده و گیرنده.

POST /api/OM/v3/Addresses/Book

{
  "cityId": 101,
  "address": "Tehran, Valiasr St",
  "postalCode": "1234567890"
}

در پاسخ، addressId دریافت می‌شود.

Pricing

استعلام هزینه ارسال قبل از ثبت سفارش.

POST /api/OM/v3/Pricing

{
  "packageInputs": [
    {
      "origin": {
        "cityId": 0
      },
      "destination": {
        "cityId": 0
      },
      "weight": 0,
      "packageValue": 0,
      "length": 0,
      "width": 0,
      "height": 0,
      "packingId": 0,
      "packageContentId": 0,
      "packType": 0,
      "paymentType": 0,
      "pickupType": 0,
      "distributionType": 0,
      "serviceId": 0,
      "parcelBookId": 0
    }
  ],
  "discountCode": "string"
}

دریافت لیست سرویس های بین دو شهر

POST /api/OM/v3/Pricing/GetServicesBetweenCities

SourceCityId: آیدی شهر مبدا

DestinationCityId: آیدی شهر مقصد

{
  "sourceCityId": 0,
  "destinationCityId": 0
}

Order

ثبت نهایی سفارش ارسال مرسوله.

PackType: نوع بسته بندی- 10:پاکت - 20:بسته

PaymentType: نوع پرداخت- 10:سمت فرستنده-اعتباری - 20:سمت گیرنده-پسکرایه - 30:سمت گیرنده-پرداخت در محل- 40:سمت فرستنده-پرداخت در محل- 50:سمت فرستنده-پرداخت از کیف پول 80-سمت فرستنده-نقدی

PickupType: نوع جمع آوری- 10:جمع آوری در محل مشتری - 20:جمع آوری در نمایندگی

DistributionType: نوع تحویل- 10:تحویل در محل مشتری - 20:تحویل در نمایندگی

ServiceId: نوع سرویس- 1:ارسال زمینی یک روزه-اکسپرس عادی - 2:ارسال یک روزه- 3:ارسال دو روزه- 6:"بین الملل- 7:اکسپرس درون شهری- 13: اکسپرس پلاس 12: سرویس همان روز

ReceiverKioskId : آیدی کیوسک جهت استفاده از سرویس لاکر پر شود (برای اطلاعات بیشتر از سرویس لاکر بخش Locker را مطالعه نمایید)

POST /api/OM/v3/Order

 {
  "packages": [
    {
      "origin": {
        "cityId": 0,
        "fullAddress": "string",
        "floor": "string",
        "unit": "string",
        "postalCode": "string",
        "latitude": "string",
        "longitude": "string",
        "no": "string",
        "description": "string",
        "beneficiary": {
          "phone": "string",
          "fullName": "string",
          "mobile": "string"
        }
      },
      "destination": {
        "cityId": 0,
        "fullAddress": "string",
        "floor": "string",
        "unit": "string",
        "postalCode": "string",
        "latitude": "string",
        "longitude": "string",
        "no": "string",
        "description": "string",
        "beneficiary": {
          "phone": "string",
          "fullName": "string",
          "mobile": "string"
        }
      },
      "senderAddressAndClient": {
        "addressId": 0,
        "addressTitle": "string",
        "clientTitle": "string",
        "clientId": 0,
        "cityId": 0
      },
      "receiverAddressAndClient": {
        "addressId": 0,
        "addressTitle": "string",
        "clientTitle": "string",
        "clientId": 0,
        "cityId": 0
      },
      "weight": 0,
      "packageValue": 0,
      "length": 0,
      "width": 0,
      "height": 0,
      "packingId": 0,
      "packageContentId": 0,
      "packType": 0,
      "parcelBookId": 0,
      "description": "string",
      "serviceId": 0,
      "enableLabelPrivacy": true,
      "paymentType": 0,
      "pickupType": 0,
      "distributionType": 0,
      "cod": 0,
      "cashAmount": 0,
      "barcode": "string",
      "barcodeDetail": {
        "preFix": "string",
        "infix": "string",
        "postFix": "string"
      },
      "customParcelTitle": "string"
    }
  ],
  "receiverKioskId": 0,
  "receiverBunchId": 0,
  "traceCode": "string",
  "secondaryTraceCode": "string",
  "customerSubstationCode": "string",
  "discountCode": "string"
}

در پاسخ، orderId و traceCode دریافت می‌کنید.

Cancel Order

لغو سفارش ثبت‌شده (در صورت شروع نشدن پردازش).

POST /api/OM/v3/Orders/CancelOrder/{orderId}

Tracking

رهگیری وضعیت مرسوله از طریق روش‌های مختلف.

پیگیری مرسوله

GET /api/OM/v3/Tracking/BriefTracking/{trackingInput}

پیگیری مرسوله با کد قرار جت

GET /api/OM/v3/Tracking/ByContractCode/{contractCode}

پیگیری با کد سفارش

GET /api/OM/v3/Tracking/{orderId}

وضعیت‌ها شامل ثبت سفارش، جمع‌آوری، ارسال و تحویل می‌باشد.

Errors & Status Codes

در صورت بروز خطا، API کد وضعیت HTTP مناسب بازمی‌گرداند.

• 401 – احراز هویت ناموفق
• 403 – دسترسی غیرمجاز
• 422 – خطای اعتبارسنجی داده‌ها
• 500 – خطای داخلی سرور