Су өлшегіші OCR API

Су өлшегіші OCR API. Бұл бет веб-сайттың үшінші тарап интеграциялары үшін ашық HTTP API туралы құжаттайды.

Шынайы жүктеуден бастаңыз

Алдымен тіркеліп, жұмыс орнына өзіңіздің су өлшегішінің фотосын жүктеңіз, содан кейін интеграцияға дайын болғанда API кілт жасаңыз.

Тіркелу және фотосурет жүктеу API кілт жасау

API интерфейстерін іздеу

Жалпы шолу

Барлық сыртқы интеграциялар үшін веб-сайттың backend-ін пайдаланыңыз.
Үшінші тарап бағдарламаларынан waterMeterAi қызметін тікелей қолданбаңыз.
Ашық API веб-порталмен бірдей пайдаланушылар, квота, кэш, тапсырмалар және аудит ережелерін бөліседі.
Backend орналастыру конфигурациясы бойынша әртүрлі төменгі AI қызметтеріне бағыттала алады.
Тапсырма жауаптары енді әртүрлі бизнес әртүрлі нәтижелер түрлерін көрсете алатын жалпы result_summary объектісін қамтиды.

Аутентификация

Веб-сайтқа кіріп, API Keys бетінде 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

Жүктеу ережелері

Максималды файл өлшемі: әр суретке 20MB.
Қолдау көрсетілетін форматтар: JPEG, PNG, WEBP.
Backend файл мазмұнын тексереді, тек файл кеңейтімін ғана емес.

Жүктеу өлшемін бақылау

Пакеттік жүктеулер әдепкі бойынша 8 суретке дейін қабылдайды, әр суретке шектеу 20MB және жалпы файл мазмұны 20MB.
Шектеуден асып кеткен файл немесе пакет кескінді тексеру немесе тапсырма жасау алдында 413 қайтарады; Жартылай партия жасалмайды.
Backend нақты қабылданған байт санын қамтамасыз етеді, тіпті 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` қайтарады және жаңа тапсырма жасаудың орнына қате хабарламасын қосады.

Кэш және нәтиже жаңалығы

Backend сәтті нәтижелерді сурет хэші мен AI нұсқасы бойынша кэштейді және төменгі бизнес namespace мәнін де ескереді.
`cached_exact` сол кескіннің ағымдағы AI нұсқасында сәтті нәтиже бергенін білдіреді, сондықтан жаңа AI іске қосу қажет болмады.
`cached_stale` AI қызметі офлайн және backend соңғы қолжетімді тарихи нәтижені қайтарғанын білдіреді.
Егер `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` күйлерін аяқталмаған деп санап, күйді мерзімді тексеруді жалғастырыңыз.
Backend-ке желі жолы жоғары кідіріс болғанда және орналастырылған бизнес пакеттік режимді қолдаған кезде пакеттік сұраныстарды қолданыңыз.
Пакеттік сұраныстар қазіргі уақытта `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 кілт жасау

Су өлшегіші OCR API

Шынайы жүктеуден бастаңыз

Жалпы шолу

Аутентификация

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}`