مستندات API استعلام بارنامه

راهنمای اتصال سرویس

API استعلام بارنامه با پلاک

آخرین بارنامه قابل دریافت ناوگان در ۱۰ روز گذشته بر اساس اجزای پلاک ایرانی؛ طبق مستند V03 راهداری.

POST/api/v1/waybills/by-plate

X-API-Keyدسترسی مورد نیاز: waybills:readبدنه JSONمصرف سهمیه طبق شرایط اشتراک

ورودی‌های درخواست

فیلدهای زیر را در بدنه JSON با Content-Type: application/json ارسال کنید. نوع داده و الزامی بودن هر فیلد را پیش از ارسال بررسی کنید.

plateLeftstringالزامی

دو رقم سمت چپ

نمونه: 82

plateLetterstringالزامی

حرف پلاک

نمونه: ع

plateRightstringالزامی

سه رقم سمت راست

نمونه: 117

plateCitystringالزامی

کد دو رقمی ایران

نمونه: 11

این مسیر پلاک تجاری با حرف «ع» را می‌پذیرد: plateLeft دو رقم، plateRight سه رقم و plateCity دو رقم هستند. اجزای پلاک را رشته بفرستید تا صفر ابتدای آن‌ها حفظ شود.
بدنه JSON است؛ خروجی مربوط به آخرین بارنامه قابل دریافت برای همین پلاک است، نه فهرست کامل سوابق ناوگان.

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

# Use your test key. Example inputs are synthetic; no automatic retry.
# Set BARBAN_API_KEY privately before running this example.
curl --request POST 'https://api.bar-ban.ir/api/v1/waybills/by-plate' \
  --header "X-API-Key: $BARBAN_API_KEY" \
  --header "Idempotency-Key: example-waybill-plate-001" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
  "plateLeft": "82",
  "plateLetter": "ع",
  "plateRight": "117",
  "plateCity": "11"
}'

مقادیر نمونه‌اند. کپی کد هیچ درخواستی ارسال نمی‌کند.

کلید آزمایشی بدون فراخوانی راهداری پاسخ می‌دهد؛ کسر سهمیه به تنظیمات خریداری‌شده پلن بستگی دارد.

بدنه درخواست JSON است. هدر Idempotency-Key برای تلاش مجدد یک درخواست استفاده شود.

ساختار پاسخ

JSON

ابتدا وضعیت HTTP و پوش پاسخ را بررسی کنید. مقادیر این مثال آموزشی‌اند؛ وجود قرارداد، سلامت لحظه‌ای سرویس بالادستی را تضمین نمی‌کند.

نمونه آموزشی پاسخ

{
  "requestId": "example-waybill-plate-001",
  "sandbox": true,
  "found": true,
  "data": {
    "sandbox": true,
    "service": "waybill-plate",
    "message": "احراز هویت و ساختار درخواست معتبر است؛ راهداری فراخوانی نشد."
  }
}

فیلدهای داده پاسخ ۱۴۱ فیلد

فیلد	نوع و مقدار تهی	توضیح
`ChangeStatusDate`	`object`می‌تواند null باشد	تاریخ تغییر وضعیت
`ChangeStatusDate.Day`	`integer (int32)`غیرتهی	روز
`ChangeStatusDate.Month`	`integer (1–12)`می‌تواند null باشد	ماه
`ChangeStatusDate.Year`	`integer (int32)`غیرتهی	سال
`Company`	`object`می‌تواند null باشد	شرکت حمل
`Company.Branch`	`object`می‌تواند null باشد	شعبه
`Company.Branch.ID`	`integer (int64)`غیرتهی	شناسه
`Company.Branch.Name`	`string`می‌تواند null باشد	نام
`Company.Code`	`integer (int32)`غیرتهی	کد
`Company.LOCATION`	`integer (int32)`غیرتهی	کد موقعیت
`Company.Name`	`string`می‌تواند null باشد	نام
`Company.NationalCode`	`integer (int64)`غیرتهی	شناسه ملی
`Company.SARASARY`	`integer (int32)`غیرتهی	محدوده فعالیت
`CompanyCommission`	`number`غیرتهی	کمیسیون شرکت
`CompanyCommissionPercent`	`number`غیرتهی	درصد کمیسیون شرکت
`Cost`	`integer (int64)`غیرتهی	کرایه حمل
`CustomInfo`	`object`می‌تواند null باشد	اطلاعات گمرکی
`CustomInfo.Code`	`string`می‌تواند null باشد	کد
`CustomInfo.KootajDate`	`datetime`غیرتهی	تاریخ کوتاژ
`CustomInfo.KootajNo`	`string`می‌تواند null باشد	شماره کوتاژ
`Description`	`string`می‌تواند null باشد	توضیحات
`DestinationCityCode`	`integer (int32)`غیرتهی	کد مقصد
`DestinationCityName`	`string`می‌تواند null باشد	شهر مقصد
`DischargeCost`	`integer (int32)`غیرتهی	هزینه تخلیه
`DriverCommission`	`integer (int32)`غیرتهی	دریافتی راننده
`FirstDriver`	`object`می‌تواند null باشد	راننده اول
`FirstDriver.BirthCityCode`	`integer (int32)`غیرتهی	کد شهر تولد
`FirstDriver.BirthCityName`	`string`می‌تواند null باشد	شهر تولد
`FirstDriver.CardNumber`	`string`می‌تواند null باشد	شماره کارت هوشمند
`FirstDriver.CardValidationDate`	`object`می‌تواند null باشد	اعتبار کارت هوشمند
`FirstDriver.CardValidationDate.Day`	`integer (int32)`غیرتهی	روز
`FirstDriver.CardValidationDate.Month`	`integer (1–12)`می‌تواند null باشد	ماه
`FirstDriver.CardValidationDate.Year`	`integer (int32)`غیرتهی	سال
`FirstDriver.CertifcateIssueCityCode`	`integer (int32)`غیرتهی	کد محل صدور گواهینامه
`FirstDriver.CertifcateIssueCityName`	`string`می‌تواند null باشد	محل صدور گواهینامه
`FirstDriver.CertifcateNumber`	`string`می‌تواند null باشد	شماره گواهینامه
`FirstDriver.Driver_Type`	`string`می‌تواند null باشد	نوع راننده
`FirstDriver.Family`	`string`می‌تواند null باشد	نام خانوادگی
`FirstDriver.FatherName`	`string`می‌تواند null باشد	نام پدر
`FirstDriver.IdentifierNumber`	`string`می‌تواند null باشد	شماره شناسایی
`FirstDriver.InsuranceBranch`	`string`می‌تواند null باشد	شعبه بیمه
`FirstDriver.InsuranceId`	`string`می‌تواند null باشد	شناسه بیمه
`FirstDriver.IsActive`	`boolean`غیرتهی	وضعیت فعال
`FirstDriver.Mobile`	`string`می‌تواند null باشد	شماره همراه
`FirstDriver.NOVE_GAVAHINAMEH`	`string`می‌تواند null باشد	نوع گواهینامه
`FirstDriver.Name`	`string`می‌تواند null باشد	نام
`FirstDriver.NationalId`	`string`می‌تواند null باشد	کد ملی
`FirstDriver.TARIKH_ETEBAR_KART_SALAMAT`	`string`می‌تواند null باشد	اعتبار کارت سلامت
`FreighterFullInfo`	`object`می‌تواند null باشد	اطلاعات کامل ناوگان
`FreighterFullInfo.BARGIR_ID`	`integer (int64)`غیرتهی	شناسه بارگیر
`FreighterFullInfo.CardNumber`	`string`می‌تواند null باشد	شماره کارت هوشمند
`FreighterFullInfo.IsActive`	`boolean`غیرتهی	وضعیت فعال
`FreighterFullInfo.LOADER_LINK_TYPE`	`string`می‌تواند null باشد	نوع اتصال بارگیر
`FreighterFullInfo.LoadingTypeCode`	`integer (int32)`غیرتهی	کد نوع ناوگان
`FreighterFullInfo.LoadingTypeTitle`	`string`می‌تواند null باشد	نوع ناوگان
`FreighterFullInfo.MadeYear`	`integer (int32)`غیرتهی	سال ساخت
`FreighterFullInfo.Mobile`	`string`می‌تواند null باشد	شماره همراه
`FreighterFullInfo.NOVE_GAVAHINAMEH`	`string`می‌تواند null باشد	نوع گواهینامه
`FreighterFullInfo.NOVE_NAVGAN_BARI`	`integer (int32)`غیرتهی	نوع ناوگان باری
`FreighterFullInfo.PlaqueCityCode`	`integer (int32)`غیرتهی	کد شهر پلاک
`FreighterFullInfo.PlaqueCityName`	`string`می‌تواند null باشد	شهر پلاک
`FreighterFullInfo.PlaqueNumber`	`string`می‌تواند null باشد	شماره پلاک
`FreighterFullInfo.PlaqueSerialNumber`	`string`می‌تواند null باشد	سریال پلاک
`FreighterFullInfo.PlaqueType`	`string`می‌تواند null باشد	نوع پلاک
`FreighterFullInfo.TARIKH_ETEBAR_MOAYENE_FANI`	`string`می‌تواند null باشد	اعتبار معاینه فنی
`FreighterFullInfo.VINCode`	`string`می‌تواند null باشد	شماره شاسی (VIN)
`FreighterFullInfo.YearType`	`string`می‌تواند null باشد	نوع سال
`GoodInfoList`	`array`می‌تواند null باشد	کالاها
`GoodInfoList[].GoodTitle`	`string`می‌تواند null باشد	عنوان کالا
`GoodInfoList[].GoodTypeCode`	`integer (int32)`غیرتهی	کد کالا
`GoodInfoList[].HSCode`	`integer (int32)`غیرتهی	کد تعرفه کالا
`GoodInfoList[].HSTarrifTitle`	`string`می‌تواند null باشد	عنوان تعرفه
`GoodInfoList[].IranCode`	`string`می‌تواند null باشد	ایران‌کد
`GoodInfoList[].MeghdareTabieiLitr`	`integer (int32)`غیرتهی	مقدار به لیتر
`GoodInfoList[].PackingTitle`	`string`می‌تواند null باشد	نوع بسته‌بندی
`GoodInfoList[].PackingTypeCode`	`integer (int32)`غیرتهی	کد بسته‌بندی
`GoodInfoList[].Value`	`number`غیرتهی	ارزش کالا
`GoodInfoList[].VazneMakhsoos`	`number`غیرتهی	وزن مخصوص
`GoodInfoList[].Weight`	`integer (int32)`غیرتهی	وزن
`InsuranceCompany`	`string`می‌تواند null باشد	شرکت بیمه
`InsuranceCost`	`integer (int64)`غیرتهی	هزینه بیمه
`InsuranceNumber`	`string`می‌تواند null باشد	شماره بیمه
`IssuDate`	`object`می‌تواند null باشد	تاریخ صدور
`IssuDate.Day`	`integer (int32)`غیرتهی	روز
`IssuDate.Month`	`integer (1–12)`می‌تواند null باشد	ماه
`IssuDate.Year`	`integer (int32)`غیرتهی	سال
`IssueTime`	`string`می‌تواند null باشد	ساعت صدور
`KalaDesc`	`string`می‌تواند null باشد	شرح کالا
`LanderTitle`	`string`می‌تواند null باشد	نوع بارگیر
`LanderTypeCode`	`integer (int32)`غیرتهی	کد بارگیر
`LoadingCost`	`integer (int32)`غیرتهی	هزینه بارگیری
`MasterBillofLadingTraceCode`	`string`می‌تواند null باشد	رهگیری بارنامه اصلی
`Number`	`integer (int64)`غیرتهی	شماره بارنامه
`OriginCityCode`	`integer (int32)`غیرتهی	کد مبدأ
`OriginCityName`	`string`می‌تواند null باشد	شهر مبدأ
`PayanehCost`	`integer (int32)`غیرتهی	هزینه پایانه
`Serial`	`string`می‌تواند null باشد	سریال
`Status`	`string`می‌تواند null باشد	وضعیت اعلام‌شده
`Tax`	`integer (int32)`غیرتهی	مالیات
`TotalCost`	`number`غیرتهی	مجموع هزینه
`TransitTypeTitle`	`string`می‌تواند null باشد	نوع حمل
`Receiver`	`object`می‌تواند null باشد	گیرنده
`Receiver.Name`	`string`می‌تواند null باشد	نام
`Receiver.NationalCode`	`string`می‌تواند null باشد	شناسه ملی
`Receiver.PostalCode`	`string`می‌تواند null باشد	کدپستی
`Receiver.LastName`	`string`می‌تواند null باشد	نام خانوادگی
`ReceiverAddress`	`string`می‌تواند null باشد	نشانی گیرنده
`Robari`	`boolean`غیرتهی	روبار
`Sender`	`object`می‌تواند null باشد	فرستنده
`Sender.Name`	`string`می‌تواند null باشد	نام
`Sender.NationalCode`	`string`می‌تواند null باشد	شناسه ملی
`Sender.PostalCode`	`string`می‌تواند null باشد	کدپستی
`Sender.LastName`	`string`می‌تواند null باشد	نام خانوادگی
`SenderAddress`	`string`می‌تواند null باشد	نشانی فرستنده
`ShomarehHavalehAnbarNaft`	`integer (int64)`غیرتهی	شماره حواله انبار نفت
`TraceCode`	`string`می‌تواند null باشد	کد رهگیری
`TransitTypecode`	`integer (int32)`غیرتهی	کد نوع حمل
`WeighbridgeCost`	`integer (int32)`غیرتهی	هزینه باسکول
`secondDriver`	`object`می‌تواند null باشد	راننده دوم
`secondDriver.BirthCityCode`	`integer (int32)`غیرتهی	کد شهر تولد
`secondDriver.BirthCityName`	`string`می‌تواند null باشد	شهر تولد
`secondDriver.CardNumber`	`string`می‌تواند null باشد	شماره کارت هوشمند
`secondDriver.CardValidationDate`	`object`می‌تواند null باشد	اعتبار کارت هوشمند
`secondDriver.CardValidationDate.Day`	`integer (int32)`غیرتهی	روز
`secondDriver.CardValidationDate.Month`	`integer (1–12)`می‌تواند null باشد	ماه
`secondDriver.CardValidationDate.Year`	`integer (int32)`غیرتهی	سال
`secondDriver.CertifcateIssueCityCode`	`integer (int32)`غیرتهی	کد محل صدور گواهینامه
`secondDriver.CertifcateIssueCityName`	`string`می‌تواند null باشد	محل صدور گواهینامه
`secondDriver.CertifcateNumber`	`string`می‌تواند null باشد	شماره گواهینامه
`secondDriver.Driver_Type`	`string`می‌تواند null باشد	نوع راننده
`secondDriver.Family`	`string`می‌تواند null باشد	نام خانوادگی
`secondDriver.FatherName`	`string`می‌تواند null باشد	نام پدر
`secondDriver.IdentifierNumber`	`string`می‌تواند null باشد	شماره شناسایی
`secondDriver.InsuranceBranch`	`string`می‌تواند null باشد	شعبه بیمه
`secondDriver.InsuranceId`	`string`می‌تواند null باشد	شناسه بیمه
`secondDriver.IsActive`	`boolean`غیرتهی	وضعیت فعال
`secondDriver.Mobile`	`string`می‌تواند null باشد	شماره همراه
`secondDriver.NOVE_GAVAHINAMEH`	`string`می‌تواند null باشد	نوع گواهینامه
`secondDriver.Name`	`string`می‌تواند null باشد	نام
`secondDriver.NationalId`	`string`می‌تواند null باشد	کد ملی
`secondDriver.TARIKH_ETEBAR_KART_SALAMAT`	`string`می‌تواند null باشد	اعتبار کارت سلامت

پاسخ نامنتظره گرفتید؟راهنمای پاسخ‌ها و خطاها آماده اتصال هستید؟مرور نکات محیط عملیاتی