Bot API asoslari

Bot API — oddiy HTTPS interfeys. Har bir metod bitta URL; parametrlar query, JSON, form yoki multipart orqali yuboriladi; javob doim JSON.

So'rov manzili

https://api.zamin.app/bot<TOKEN>/<metod>

Masalan: https://api.zamin.app/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe. Metod nomi katta-kichik harfga sezgir emas (getMe = getme), lekin hujjatdagidek yozish tavsiya etiladi.

GET yoki POST

Har bir metod GET va POST bilan ishlaydi. Parametrlarni quyidagi usullardan biri bilan yuboring:

• Query, form va multipart'da murakkab qiymatlar (reply_markup, commands, allowed_updates) JSON matn sifatida yuboriladi.
• Mantiqiy qiymatlar: true/false, matnda "true", "false", "1", "0".
• Butun sonlar: son yoki raqamli matn (16 xonagacha).
• Noma'lum parametrlar xato bermaydi, shunchaki e'tiborga olinmaydi.
• JSON va form tanasi ≤64 KB; multipart'dagi har bir matn maydoni ≤64 KB; fayl ≤50 MB (rasm ≤20 MB).

import os
import requests

TOKEN = os.environ["ZAMIN_BOT_TOKEN"]
API = f"https://api.zamin.app/bot{TOKEN}"

# JSON
requests.post(f"{API}/sendMessage", json={"chat_id": 4810235517, "text": "Salom"}, timeout=15)

# Query satri (GET)
requests.get(f"{API}/sendMessage", params={"chat_id": 4810235517, "text": "Salom"}, timeout=15)

# JSON
curl -s -X POST "https://api.zamin.app/bot$ZAMIN_BOT_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 4810235517, "text": "Salom"}'

# Query satri (GET)
curl -s "https://api.zamin.app/bot$ZAMIN_BOT_TOKEN/sendMessage?chat_id=4810235517&text=Salom"

Javob shakli

Muvaffaqiyatli javob:

{
  "ok": true,
  "result": { "id": 1000001, "is_bot": true, "first_name": "Ob-havo", "username": "ObHavoBot" }
}

Xato:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

429 javobida qo'shimcha parameters.retry_after (soniya) bo'ladi. Bu har bir limit uchun bir xil shakl:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 3",
  "parameters": { "retry_after": 3 }
}

HTTP status kodi error_code bilan bir xil. Parametr tekshiruvi xatolarida tavsif Bad Request: <maydon>: <sabab> ko'rinishida bo'ladi, masalan Bad Request: text: message text is empty.

Autentifikatsiya va token

Token so'rov manzilida bo'ladi — boshqa sarlavha yoki kalit kerak emas. Token ko'rinishi: <bot_id>:<36 ta url-safe belgi> (A-Z a-z 0-9 _ -).

• Noto'g'ri yoki bekor qilingan token: 401 Unauthorized.
• Bitta IP manzildan (IPv6 uchun /64 tarmoqdan) 10 daqiqada 20 marta noto'g'ri token yuborilsa, shu IP'dan keladigan noto'g'ri tokenli so'rovlar vaqtincha 429 oladi. To'g'ri tokenli so'rovlar bloklanmaydi.
• Bot bloklangan (suspended) yoki egasining hisobi cheklangan bo'lsa: 403 Forbidden: bot is suspended.

Rate limitlar

Limitlar "token chelak" (token bucket) usulida: chelak to'la bo'lsa, qisqa portlash (burst) mumkin, so'ng belgilangan tezlikda to'ladi.

• Bitta qoida: qaysi limitdan oshsangiz ham javob 429 Too Many Requests: retry after N va parameters.retry_after = N (soniya) bo'ladi. Istisnolar: kunlik chatlar limiti (daily limit of chats reached, retry_after: 3600) va proksi darajasidagi IP limiti (pastda).
• Rad etilgan so'rov hech narsa sarflamaydi. Limit rad etgan so'rov hech narsa qilmagan: xabar yuborilmagan, fayl saqlanmagan, boshqa limitlardan olingan tokenlar qaytarilgan. retry_after soniya kutib, aynan o'sha so'rovni qayta yuborish xavfsiz (umumiy 50/s so'rovlar limitiga esa har bir so'rov, rad etilgani ham, kiradi).
• Tayyor yordamchi: Python yordamchi klassi (with_retry).

Xato kodlari

Har bir metod sahifasida uning o'ziga xos xatolari bor. Quyidagilar istalgan metodda bo'lishi mumkin:

Fayllarni yuklab olish

Fayl yuborilgan xabarda file_id bo'ladi. getFile bilan file_path'ni oling va faylni quyidagi manzildan yuklab oling:

GET https://api.zamin.app/file/bot<TOKEN>/<file_path>

• file_id shu botga xos: boshqa bot uni ishlata olmaydi.
• Bot ko'rgan faylni qayta yuklamasdan, file_id orqali qayta yuborishi mumkin.
• Faylni URL orqali yuborib bo'lmaydi: multipart bilan yuklang.

Telegram Bot API'dan farqlar

Zamin Bot API shakllari Telegram'ga o'xshash, lekin bir xil emas. Asosiy farqlar: