> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raptora.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Хэрэгслийн жишээ

> Захиалга шалгах, цаг товлох хэрэгслийг эхнээс нь тохируулах.

Хоёр түгээмэл хэрэгслийг алхам алхмаар тохируулна. Жишээн дэх `api.demo.mn` хаягийг өөрийн API-аар солино.

## Хэрэгсэл яаж ажилладаг вэ

Agent ярианы явцад хэрэгслийн **тайлбарыг** уншаад хэзээ дуудахаа шийднэ. Харилцагчаас хэрэгтэй утгаа асууж авна, танай API руу хүсэлт илгээнэ, хариуг нь ойлгомжтой хэлээр буцааж хэлнэ.

```mermaid theme={null}
sequenceDiagram
  participant C as Харилцагч
  participant A as Agent
  participant S as Танай API
  C->>A: Захиалга маань хэзээ ирэх вэ?
  A->>C: Захиалгын дугаараа хэлнэ үү.
  C->>A: 4215
  A->>S: GET /orders/4215
  S-->>A: { "status": "shipped", "eta": "10.29" }
  A->>C: Таны захиалга маргааш хүргэгдэнэ.
```

## Жишээ 1: Захиалгын төлөв шалгах

Мэдээлэл унших хэрэгсэл. `GET` хүсэлт тул харилцагчаас зөвшөөрөл асуухгүй шууд дуудна.

![Захиалгын төлөв шалгах хэрэгсэл](https://mintcdn.com/raptora-ai/yUv-rZM9Mm_JbqjR/images/tools/editor-light.png?fit=max\&auto=format\&n=yUv-rZM9Mm_JbqjR\&q=85\&s=ddf85e86a8606f7bad640e0bbad7a95e)

**1. Нэр, тайлбар**

**Хэрэгсэл** хуудасны **Шинэ хэрэгсэл** дараад **HTTP Request**-ийг сонгоно.

| Талбар | Утга |
| - | - |
| Нэр | Захиалгын төлөв шалгах |
| Тайлбар | Захиалгын дугаараар төлөв, хүргэлтийн огноог буцаана. Харилцагч захиалга хаана яваа, хэзээ ирэхийг асуувал дууд. |

**2. Холболт**

```text theme={null}
Method: GET
URL:    https://api.demo.mn/orders/{orderId}
```

`{orderId}`-г agent харилцагчийн хэлсэн дугаараар солино.

**3. Parameters**

| Талбар | Утга |
| - | - |
| Нэр | `orderId` |
| Төрөл | `string` |
| Тайлбар | Захиалгын дугаар |
| Заавал | Асаалттай |
| Харилцагч хэлсэн байх | Асаалттай |

**Харилцагч хэлсэн байх** асаалттай тул agent дугаар зохиохгүй, заавал асууна.

**4. Authorization ба хариу**

**Bearer token** сонгоод API түлхүүрээ оруулна. **Хариу** хэсэгт agent-д хэрэгтэй талбаруудыг сонгоно: `status`, `eta`.

Танай API ингэж хариулна гэж үзье:

```json theme={null}
{
  "orderId": "4215",
  "status": "shipped",
  "eta": "2026-10-29",
  "items": [{ "name": "Galaxy A55", "qty": 1 }],
  "warehouse": { "code": "UB-03" }
}
```

Agent зөвхөн `status`, `eta`-г харна. Хариу богино байх тусам agent хурдан, зөв хариулна.

**5. Турших ба холбох**

**Request** табд `orderId` оруулаад **Илгээх** дарна. Ажиллаж байвал **Хадгалах**, дараа нь [agent](https://docs.raptora.io/agent/configure.md)-ын **Мэдлэг ба хэрэгсэл** хэсгээс сонгоно.

## Жишээ 2: Цаг захиалах

Өгөгдөл өөрчлөх хэрэгсэл. `POST` дээр **Дуудахаас өмнө харилцагчаас зөвшөөрөл авах** анхнаасаа асаалттай: agent юу хийхээ хэлж, харилцагч «тийм» гэсний дараа л дуудна.

![Цаг захиалах хэрэгсэл](https://mintcdn.com/raptora-ai/yUv-rZM9Mm_JbqjR/images/tools/booking-light.png?fit=max\&auto=format\&n=yUv-rZM9Mm_JbqjR\&q=85\&s=1f4981ca67b5b276ab2f65186f7070ee)

**1. Нэр, тайлбар**

| Талбар | Утга |
| - | - |
| Нэр | Цаг захиалах |
| Тайлбар | Сонгосон салбарт үйлчлүүлэх цаг товлоно. Харилцагч салбар, цагаа хэлж, зөвшөөрсний дараа дууд. |

**2. Холболт**

```text theme={null}
Method: POST
URL:    https://api.demo.mn/bookings
```

**3. Parameters**

| Нэр | Төрөл | Тайлбар |
| - | - | - |
| `branch` | `string` | Салбарын нэр |
| `time` | `datetime` | Үйлчлүүлэх цаг |

Хоёуланд нь **Заавал**, **Харилцагч хэлсэн байх**-ыг асаана.

URL-д ороогүй параметрүүд body-д JSON-оор явна:

```json theme={null}
{ "branch": "Хан-Уул", "time": "2026-11-01T11:00:00+08:00" }
```

**4. Ярианд ингэж харагдана**

> **Харилцагч:** Бямба гарагт 11 цагт Хан-Уул салбарт очмоор байна.
>
> **Agent:** Бямба гараг 11:00-д Хан-Уул салбарт цаг захиалах уу?
>
> **Харилцагч:** Тийм.
>
> **Agent:** Захиаллаа. Бямба гарагт 11:00-д хүлээж байна.

## Agent-ын зааварт нэмэх

Хэрэгслийг хэзээ ашиглахыг заавартаа бас бичвэл agent илүү найдвартай дуудна.

```text theme={null}
[Хэрэгсэл]
- Харилцагч захиалгаа асуувал «Захиалгын төлөв шалгах»-аар шалга.
- Цаг товлохдоо салбар, цагийг давтан хэлж баталгаажуулаад «Цаг захиалах»-ыг дууд.
- Хэрэгсэл алдаа өгвөл уучлал гуйж, ажилтан руу шилжүүл.
```

## Танай серверийн жишээ

Raptora-аас ирэх хүсэлтийг хүлээж авах хамгийн энгийн сервер. Token-оо шалгаад JSON буцаана.

```js Node.js (Express) theme={null}
import express from "express";

const app = express();
app.use(express.json());

app.get("/orders/:orderId", (req, res) => {
  if (req.headers.authorization !== `Bearer ${process.env.RAPTORA_TOKEN}`) {
    return res.status(401).json({ error: "unauthorized" });
  }
  res.json({ orderId: req.params.orderId, status: "shipped", eta: "2026-10-29" });
});

app.post("/bookings", (req, res) => {
  const { branch, time } = req.body;
  res.json({ ok: true, branch, time });
});

app.listen(3000);
```

```python Python (FastAPI) theme={null}
import os
from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/orders/{order_id}")
def order_status(order_id: str, authorization: str = Header("")):
    if authorization != f"Bearer {os.environ['RAPTORA_TOKEN']}":
        raise HTTPException(status_code=401)
    return {"orderId": order_id, "status": "shipped", "eta": "2026-10-29"}

@app.post("/bookings")
def book(body: dict):
    return {"ok": True, **body}
```

> [!TIP]
>
> Хүсэлт үнэхээр Raptora-аас ирснийг шалгах бол [хүсэлтийн гарын үсэг](https://docs.raptora.io/integrations/request-signing.md) асаана.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.