API-н баримт бичиг

wallmarkets API нь хүргэлт, буцаалт, бүтээгдэхүүн, супермаркет дансуудыг програмчлалын аргаар удирдах боломжийг олгоно. Бүх төгсгөлийн цэгүүд JSON буцаадаг бөгөөд API түлхүүрээр баталгаажуулах шаардлагатай.

Суурь URL

https://www.wallmarkets.store/api/v1

Хариултын формат

Хариу бүр статус талбар болон өгөгдлийн ачааллыг (эсвэл алдаа гарсан тохиолдолд алдааны объект) агуулна.

{
  "status": "success",
  "data": { ... }
}

Хүсэлт бүрийг Authorization толгой хэсэгт Bearer токен хэлбэрээр API түлхүүрээ оруулан баталгаажуул.

API түлхүүр үүсгэх

Дансны тохиргоо > API түлхүүрүүд хэсэгт түлхүүрүүд үүсгэ. Түлхүүр бүр дараахыг дэмждэг:

• Хүрээ: Нөөц тус бүрээр хандалтыг хязгаарлах (жишээ нь deliveries:read, returns:write, products:read)
• Хугацаа дуусах: Сонголттой дуусах огноо — хугацаа дууссан түлхүүрүүд автоматаар татгалзагдана
• Эргэлт: Түлхүүрийг эргүүлэх нь түлхүүрийн ID-г өөрчлөхгүйгээр шинэ нууц авах боломжийг олгоно

Нэвтрэлтийн толгой

Authorization: Bearer YOUR_API_KEY

Жишээ хүсэлт

curl -X GET \
  https://www.wallmarkets.store/api/v1/deliveries \
  -H 'Authorization: Bearer wm_live_abc123...'

Хурдны хязгаарлалт нь үйлчилгээний тогтвортой байдлыг хамгаална. Хязгаарлалт нь төлөвлөгөөгөөр ялгаатай:

Төлөвлөгөөгөөр хязгаарлалт

Хурдны хязгаарын толгой

Хариу бүр дараах толгой хэсгүүдийг агуулна:

• X-RateLimit-Limit: Цагт хамгийн их хүсэлт
• X-RateLimit-Remaining: Одоогийн цонхонд үлдсэн хүсэлтүүд
• X-RateLimit-Reset: Цонх шинэчлэгдэх UTC эпох секунд

Шаардлагатай хүрээ: deliveries:read / deliveries:write

Хүргэлтийн жагсаалт

Баталгаажуулсан хэрэглэгчийн хүргэлтүүдийн хуудасласан жагсаалтыг буцаана.

# Query Parameters
?page=1&per_page=20&status=pending&date_from=2024-01-01&supermarket_id=5

Хүргэлт авах

{
  "id": 123,
  "supermarket_name": "E-mart",
  "subchain_name": "Sukhbaatar Branch",
  "products": [
    {"product_id": 8, "name": "Product A", "quantity": 10, "unit_price": 5000},
    {"product_id": 15, "name": "Product B", "quantity": 5, "unit_price": 12000}
  ],
  "total_value": 110000,
  "delivery_date": "2024-10-15",
  "status": "completed",
  "created_at": "2024-10-01T10:30:00Z"
}

Хүргэлт үүсгэх

{
  "supermarket_id": 5,
  "subchain_id": 12,
  "products": [
    {"product_id": 8, "quantity": 10},
    {"product_id": 15, "quantity": 5}
  ],
  "delivery_date": "2024-10-20",
  "notes": "Urgent delivery"
}

Хүргэлтийн төлөв шинэчлэх

{
  "status": "completed"
}

Хүчинтэй шилжилтүүд: pending → in_transit → completed, эсвэл pending → cancelled.

Шаардлагатай хүрээ: returns:read / returns:write

Буцаалтын жагсаалт

Хуудасласан жагсаалтыг буцаана. Хүргэлт, супермаркет, шалтгаан эсвэл огнооны мужаар шүү.

# Query Parameters
?page=1&per_page=20&reason=damaged&delivery_id=123

Буцаалт үүсгэх

{
  "delivery_id": 123,
  "product_id": 8,
  "quantity": 3,
  "reason": "damaged",
  "return_date": "2024-10-18",
  "description": "Products arrived damaged during transit"
}

Буцаалт авах

{
  "id": 42,
  "delivery_id": 123,
  "product_id": 8,
  "product_name": "Product A",
  "quantity": 3,
  "reason": "damaged",
  "description": "Products arrived damaged during transit",
  "return_date": "2024-10-18",
  "credit_amount": 15000,
  "created_at": "2024-10-18T09:15:00Z"
}

Шаардлагатай хүрээ: products:read / products:write

Бүтээгдэхүүний жагсаалт

Баталгаажуулсан хэрэглэгчийн бүх бүтээгдэхүүнийг буцаана. Ангилалаар шүүх эсвэл нэрээр хайх.

# Query Parameters
?page=1&per_page=50&category=Dairy&search=milk

Бүтээгдэхүүн авах

{
  "id": 8,
  "sequential_id": "P-0008",
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy",
  "created_at": "2024-08-01T12:00:00Z"
}

Бүтээгдэхүүн үүсгэх

{
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy"
}

Өвөрмөц sequential_id автоматаар оноогдоно.

Бүтээгдэхүүн шинэчлэх

{
  "price": 5500
}

Зөвхөн оруулсан талбарууд шинэчлэгдэнэ. Түүхэн хүргэлтийн бүртгэлд нөлөөлөхгүй.

Шаардлагатай хүрээ: supermarkets:read / supermarkets:write

Супермаркетын жагсаалт

[
  {
    "id": 5,
    "name": "E-mart",
    "branches": [
      {"id": 12, "name": "Sukhbaatar Branch", "address": "..."},
      {"id": 13, "name": "Bayangol Branch", "address": "..."}
    ]
  }
]

Супермаркет авах

Супермаркетийн дэлгэрэнгүй мэдээллийг бүх салбар, хүргэлтийн цонх, холбоо барих мэдээллийн хамт буцаана.

Супермаркет үүсгэх

{
  "name": "E-mart",
  "contact_email": "buyer@emart.mn",
  "branches": [
    {
      "name": "Sukhbaatar Branch",
      "address": "Peace Avenue 15, UB",
      "delivery_window": "08:00-12:00"
    }
  ]
}

Үйл явдал болоход бодит цагийн HTTP дуудлага хүлээн авахын тулд вебхукуудад бүртгүүл. 10 дараалсан хүргэлтийн алдааны дараа вебхукууд автоматаар идэвхгүй болно.

Үйл явдлын төрөл

Вебхук ачааллын жишээ

{
  "event": "delivery.completed",
  "timestamp": "2024-10-15T14:30:00Z",
  "data": {
    "delivery_id": 123,
    "supermarket_name": "E-mart",
    "subchain_name": "Sukhbaatar Branch",
    "total_value": 110000,
    "completed_at": "2024-10-15T14:30:00Z"
  }
}

Дахин оролдох бодлого

Амжилтгүй хүргэлтүүдийг экспоненциал бэкаффоор (1 мин, 5 мин, 30 мин) дахин оролдоно. 10 дараалсан алдааны дараа захиалга автоматаар идэвхгүй болно. Вебхук тохиргооноос дахин идэвхжүүл.

HTTP статус кодууд

Алдааны хариуны формат

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "delivery_date must be in the future",
    "field": "delivery_date"
  }
}