API OCR میتر آب

API OCR میتر آب. این صفحه HTTP API عمومی ارائه‌شده توسط بخش پشتی وب‌سایت برای یکپارچه‌سازی‌های شخص ثالث را مستند می‌کند.

با یک آپلود واقعی شروع کنید

ابتدا ثبت‌نام کنید، عکس میتر آب خود را در فضای کاری آپلود کنید و پس از آماده‌شدن برای یکپارچه‌سازی، یک کلید API بسازید.

ثبت نام و آپلود عکس یک کلید API ایجاد کنید

جستجو در نقاط پایانی

نمای کلی

برای همه یکپارچه‌سازی‌های خارجی از بخش پشتی وب‌سایت استفاده کنید.
با waterMeterAi مستقیماً از برنامه های شخص ثالث تماس نگیرید.
API باز همان کاربران، سهمیه، حافظه پنهان، وظایف و قوانین حسابرسی را به عنوان پورتال وب به اشتراک می گذارد.
بخش پشتی می‌تواند با پیکربندی استقرار، سرویس‌های پایین‌دستی AI مختلف را هدف قرار دهد.
پاسخ‌های وظیفه اکنون شامل یک شیء عمومی result_summary است تا سرویس‌های مختلف بتوانند انواع متفاوت نتایج را نمایش دهند.

احراز هویت

در وب‌سایت وارد شوید و یک کلید API در صفحه کلیدهای API ایجاد کنید.
کلید کامل API زمانی که ایجاد می شود فقط یک بار نشان داده می شود.
در هر درخواست، کلید را در هدر Authorization ارسال کنید.

Authorization: Bearer wm_xxxxxxxxxxxxxxxxx

API Key Permissions and Limits

Each API key can have independent scopes, an IPv4/IPv6/CIDR allowlist, a total requests-per-minute limit, and a task submissions-per-minute limit.
A valid key without the required scope or outside its source IP allowlist returns 403.
Every valid-key request consumes the total request limit, including requests rejected by scope, IP, or submission policy.
Batch requests consume one total request unit and one submission unit per uploaded file.
Rate-limited responses return 429 with Retry-After and both X-RateLimit-* and X-SubmissionLimit-* headers.
Task creation also has a per-key concurrency limit and returns X-ConcurrencyLimit-* headers; a concurrency rejection uses 429.
For batch concurrency, only files that pass image validation reserve slots, and success headers report the actual active slots after task binding.

Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1785902400
X-SubmissionLimit-Limit: 10
X-SubmissionLimit-Remaining: 9
X-ConcurrencyLimit-Limit: 3
X-ConcurrencyLimit-Active: 1
X-ConcurrencyLimit-Remaining: 2

قوانین آپلود

حداکثر حجم فایل: 20 مگابایت در هر تصویر.
فرمت های پشتیبانی شده: JPEG، PNG، WEBP.
Backend محتوای واقعی فایل را تأیید می کند، نه فقط پسوند فایل را.

اجرای اندازه آپلود

آپلودهای دسته‌ای به‌طور پیش‌فرض حداکثر 8 تصویر را با محدودیت 20 مگابایت برای هر تصویر و 20 مگابایت محدودیت کل محتوای فایل می‌پذیرند.
یک فایل یا دسته ای که از حد مجاز خود فراتر می رود، 413 را قبل از اعتبارسنجی تصویر یا ایجاد کار برمی گرداند. هیچ دسته ای جزئی ایجاد نمی شود.
پشتیبان تعداد بایت های دریافتی واقعی را حتی زمانی که Content-Length وجود ندارد یا از انتقال تکه تکه شده استفاده می شود، اعمال می کند.

وضعیت‌های وظیفه

queued: پذیرفته شده و در انتظار پردازش AI است.
running: اکنون در حال پردازش است، یا به توزیع‌کننده تحویل شده و وضعیت نتیجه نهایی به‌صورت دوره‌ای بررسی می‌شود.
batch_waiting_ai: هر مورد در دسته منتظر است تا سرویس AI آنلاین شود.
batch_running: دسته از قبل به توزیع کننده تحویل داده شده است و هنوز در حال پردازش است.
done: با موفقیت به پایان رسید.
failed: پردازش ناموفق بود.
waiting_ai: تا آنلاین شدن دوباره سرویس AI در صف می‌ماند و سپس به‌طور خودکار ادامه می‌یابد.

منابع نتیجه

fresh: توسط اجرای جدید AI تولید شد.
cached_exact: با حافظه نهان نسخه فعلی AI مطابقت داشت.
cached_stale: AI آفلاین، آخرین نتیجه ذخیره شده در حافظه پنهان برگشت داده شد.
pending: هنوز نتیجه نهایی وجود ندارد.
failed: وظیفه ناموفق بود.
وقتی کاری هنوز انجام نشده است، error_message را برای آخرین دلیل تلاش مجدد یا انتظار بررسی کنید.

سهمیه و صورتحساب

اگر لازم است ادغام شما برای جلوگیری از شکست سهمیه، از `GET /api/open/quota` قبل از ارسال بارهای کاری بزرگ استفاده کنید.
فقط اجرای `fresh` از AI سهمیه مصرف می‌کند.
نتایج `cached_exact`، `cached_stale`، `pending`، و `failed` سهمیه را مصرف نمی کنند.
حساب‌های رایگان ابتدا از سهمیه روزانه استفاده می‌کنند. حساب‌های پولی طبق پالیسی بخش پشتی، نخست بسته‌های سهمیه دوره‌ای فعال و سپس سهمیه موقت یا ثابت را مصرف می‌کنند.
وقتی سهمیه تمام شود، ارسال وظیفه به‌جای ایجاد وظیفه جدید، `429` و یک پیام خطا برمی‌گرداند.

حافظه پنهان و تازگی نتیجه

بخش پشتی نتایج موفق را براساس هش تصویر و نسخه AI در کش ذخیره می‌کند و namespace سرویس پایین‌دستی را نیز در نظر می‌گیرد.
`cached_exact` به این معنی است که همان تصویر قبلاً یک نتیجه موفقیت آمیز برای نسخه AI فعلی داشته است، بنابراین نیازی به اجرای AI جدید نیست.
`cached_stale` یعنی سرویس AI آفلاین است و بخش پشتی آخرین نتیجه تاریخی موجود را برگردانده است.
وقتی مقدار `is_latest_ai_version` برابر false است، نتیجه را به‌عنوان داده تاریخی قابل استفاده اما نیازمند بررسی ذخیره کنید.
فرض نکنید هر وظیفه `done` سهمیه مصرف کرده است؛ `result_source` را بررسی کنید.

Task completion webhooks

Send signed task completion events to your HTTPS endpoint with automatic retries.
This API key is inactive. Existing records remain available, but new, enabled, test, and secret-rotation operations are blocked.

X-WaterMeter-Webhook-Id: whev_new_event
X-WaterMeter-Webhook-Replay-Of: whev_original_event
replay_of_event_id: whev_original_event
blocked endpoint management: HTTP 409
canceled delivery status: canceled

GET`/api/open/quota`

سهمیه فعلی و استفاده باقیمانده را بخوانید.

درخواست مثال

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

نمونه پاسخ

{
  "ok": true,
  "email": "[email protected]",
  "quota": {
    "account_type": "free",
    "daily_limit": 20,
    "used": 3,
    "remaining": 17,
    "day_tag": "2026-06-01",
    "is_unlimited": false,
    "monthly_remaining": 0,
    "monthly_bonus_remaining": 0,
    "fixed_remaining": 0,
    "nearest_expire_at": null,
    "quota_summary_text": "Free daily quota: 3/20 used today. Remaining: 17."
  }
}

GET`/api/open/ai-status`

وضعیت سرویس عمومی را برای ارسال وظیفه و استفاده از نتایج حافظه پنهان بخوانید.

درخواست مثال

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

نمونه پاسخ

{
  "ok": true,
  "is_online": true,
  "busy": false,
  "active_jobs": 0,
  "public_status": "online",
  "public_status_label": "online",
  "public_status_reason": "ready",
  "accepts_new_tasks": true,
  "can_return_cached_result": true,
  "queue_state": "idle",
  "queue_count": 0,
  "current_ai_version": "water_v2:wm-ai-v2-2026-06-01",
  "last_checked_at": "2026-06-01T06:15:30Z"
}

POST`/api/open/tasks`

یک تصویر آپلود کنید و یک کار واحد ایجاد کنید.

درخواست مثال

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

نمونه پاسخ

{
  "ok": true,
  "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
  "status": "queued",
  "result_source": "pending",
  "visibility": "private",
  "ai_online": true,
  "is_latest_ai_version": false,
  "final_reading": "-",
  "result_summary": {
    "resultKind": "unknown",
    "primaryLabel": "Result",
    "primaryValue": "-",
    "secondaryLabel": "Detail",
    "secondaryValue": "-",
    "summaryText": "No result is available yet."
  },
  "error_message": "",
  "created_at": "2026-06-01T06:16:10Z"
}

GET`/api/open/tasks/{task_id}`

وضعیت یک کار و خواندن نهایی را بخوانید.

درخواست مثال

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

نمونه پاسخ

{
  "ok": true,
  "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
  "status": "done",
  "result_source": "fresh",
  "ai_online": true,
  "is_latest_ai_version": true,
  "final_reading": "123.45",
  "meter_type": "pointer",
  "success": "yes",
  "result_summary": {
    "resultKind": "water_meter",
    "primaryLabel": "Final Reading",
    "primaryValue": "123.45",
    "secondaryLabel": "Meter Type",
    "secondaryValue": "pointer",
    "summaryText": "Water meter recognition finished."
  },
  "error_message": "",
  "created_at": "2026-06-01T06:16:10Z"
}

GET`/api/open/tasks`

کارهای اخیر متعلق به کاربر اصلی API را بخوانید.

درخواست مثال

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

نمونه پاسخ

{
  "ok": true,
  "items": [
    {
      "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
      "status": "done",
      "result_source": "cached_exact",
      "final_reading": "123.45",
      "meter_type": "pointer",
      "success": "yes",
      "result_summary": {},
      "ai_online": true,
      "is_latest_ai_version": true,
      "created_at": "2026-06-01T06:16:10Z",
      "error_message": ""
    }
  ]
}

POST`/api/open/batches`

چندین تصویر را در یک درخواست بارگذاری کنید.

درخواست مثال

curl -X POST "https://watermeterai.com/api/open/batches" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "files=@D:\data\meter_001.jpg" \
  -F "files=@D:\data\meter_002.jpg"

نمونه پاسخ

{
  "ok": true,
  "batch_id": "5a14f4e5f6d34fdabce00e62c0dd0001",
  "status": "batch_running",
  "total_count": 2,
  "done_count": 0,
  "failed_count": 0,
  "pending_count": 2,
  "items": [
    {
      "index": 0,
      "file_name": "meter_001.jpg",
      "task_id": "task_a",
      "status": "queued",
      "result_source": "pending",
      "final_reading": "-",
      "failure_kind": "",
      "error_message": ""
    },
    {
      "index": 1,
      "file_name": "meter_002.jpg",
      "task_id": "task_b",
      "status": "queued",
      "result_source": "pending",
      "final_reading": "-",
      "failure_kind": "",
      "error_message": ""
    }
  ]
}

GET`/api/open/batches/{batch_id}`

پیشرفت دسته ای و وضعیت وظایف هر فایل را بخوانید.

درخواست مثال

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

نمونه پاسخ

{
  "ok": true,
  "batch_id": "5a14f4e5f6d34fdabce00e62c0dd0001",
  "status": "batch_done",
  "total_count": 2,
  "done_count": 2,
  "failed_count": 0,
  "pending_count": 0,
  "items": [
    {
      "index": 0,
      "file_name": "meter_001.jpg",
      "task_id": "task_a",
      "status": "done",
      "result_source": "fresh",
      "final_reading": "123.45",
      "failure_kind": "",
      "error_message": ""
    },
    {
      "index": 1,
      "file_name": "meter_002.jpg",
      "task_id": "task_b",
      "status": "done",
      "result_source": "cached_exact",
      "final_reading": "456.78",
      "failure_kind": "",
      "error_message": ""
    }
  ]
}

جریان توصیه شده

قبل از ارسال حجم کاری بزرگ، `GET /api/open/ai-status` را بررسی کنید.
`task_id` یا `batch_id` را بلافاصله پس از ارسال در سیستم خود ذخیره کنید.
`queued`، `running`، `waiting_ai`، `batch_waiting_ai` و `batch_running` را وضعیت‌های غیرنهایی بدانید و بررسی دوره‌ای وضعیت را ادامه دهید.
وقتی مسیر شبکه به بخش پشتی تأخیر زیادی دارد و سرویس مستقر از حالت دسته‌ای پشتیبانی می‌کند، از درخواست دسته‌ای استفاده کنید.
درخواست های دسته ای در حال حاضر از طریق `webBackend -> dispatchCenter -> waterMeterAi` جریان دارند.
`batch_waiting_ai` به این معنی است که هر آیتمی هنوز منتظر سرویس AI است، هنوز به طور فعال اجرا نشده است.
وقتی سرویس مستقر `CAD` است، فعلاً از `POST /api/open/tasks` استفاده کنید و آپلود دسته‌ای را در دسترس ندانید.

یادداشت های خطا

400: درخواست نامعتبر است یا سرویس مستقر از آپلود دسته‌ای پشتیبانی نمی‌کند.
401: کلید API مفقود، نامعتبر، منقضی شده یا غیرفعال شده است.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: وظیفه یا دسته ای یافت نشد یا متعلق به کاربر فعلی نیست.
413: فایل خیلی بزرگ است.
415: نوع تصویر پشتیبانی نشده یا محتوای تصویر نامعتبر.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

آپلود دسته ای 400 در دسترس نیست

{
  "detail": "batch upload is not supported for business: cax"
}

401 کلید API وجود ندارد یا نامعتبر است

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

فایل 413 خیلی بزرگ است

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

سهمیه 429 تمام شد

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

برای آزمایش روند کامل آماده هستید؟

از فضای کاری وب برای اولین عکس استفاده کنید، سپس به کلیدهای API بروید، زمانی که قالب نتیجه با سیستم شما مطابقت داشت.

ثبت نام و آپلود عکس یک کلید API ایجاد کنید

API OCR میتر آب

با یک آپلود واقعی شروع کنید

نمای کلی

احراز هویت

API Key Permissions and Limits

قوانین آپلود

اجرای اندازه آپلود

وضعیت‌های وظیفه

منابع نتیجه

سهمیه و صورتحساب

حافظه پنهان و تازگی نتیجه

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

جریان توصیه شده

یادداشت های خطا

برای آزمایش روند کامل آماده هستید؟

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`