# حلول Find Match API

> URL: https://hotelmapping.org/ar/products/match-api-solutions/ · اللغة: العربية

تأخذ Find Match API سجل فندق واحدًا لديكم (الاسم والعنوان والإحداثيات، وإن وُجد الهاتف وعنوان الموقع الإلكتروني) وتبحث عن مقابله في قاعدة بيانات hotelmapping.org. تعود في الاستجابة معرّف HM ID المطابق ودرجة ثقة بين 0 و1 والقرار الصادر بحسب هذه الدرجة. وتعمل أيضًا مع السجلات التي لا تملك رمز مورّد.

## ما الذي تكسبه

- **دون الحاجة إلى رمز مورّد:** يكفي الاسم ومعلومات الموقع لفنادقكم المتعاقد معها أو سجلات الإكسترانت أو اسم فندق مكتوب كنص حر.
- **الدرجة والقرار معًا:** تعود في كل استجابة درجة الثقة وحقل القرار. ويمكنكم أيضًا تقييد ما تقبلونه تلقائيًا بقاعدة العمل الخاصة بكم.
- **تتحمل فروق الكتابة:** تمر الاختصارات واللواحق الناقصة والأسماء بالأحرف السيريلية والعربية بالتطبيع. وتُقارن فروق مثل "Rsrt." و"Resort" على مستوى الحرف والكلمة في تشابه الاسم.
- **قائمة المرشحين:** تعود أكثر المرشحين احتمالًا مع مسافاتهم ودرجاتهم؛ فيسهل اتخاذ القرار في السجلات التي تحتاج إلى مراجعة.

## قبل وبعد

سجل من نظام الوكالة نفسه دون رمز مورّد

**kontratli_oteller.csv**

```csv
internal_id,name,city,lat,lng,phone
K-0192,Отель Лара Палм,Анталья,36.8567,30.7969,0242 000 00 00
```

نتيجة Find Match API

**POST /v1/match → 200 OK**

```json
{
  "reference": "K-0192",
  "normalized_name": "lara palm",
  "decision": "auto_match",
  "hm_id": "HM-1052207",
  "name": "Lara Palm Hotel",
  "confidence": 0.973,
  "signals": {
    "name_similarity": 0.95,
    "distance_m": 63,
    "phone_match": true
  }
}
```

_هذه بيانات توضيحية؛ اسم الفندق والهاتف والرموز لا تخص منشأة حقيقية. يُحوَّل الاسم الروسي إلى أحرف لاتينية وتُفصل لاحقة "فندق" ثم تتم المقارنة._

## كيف يعمل

1. **الطلب:** يُرسَل اسم الفندق ومعلومات الموقع إلى نقطة النهاية POST /v1/match. وكلما أُضيفت الإحداثيات والعنوان والهاتف وعنوان الموقع الإلكتروني ازدادت قوة المطابقة.
2. **التطبيع:** تُفصل عن الاسم لواحق مثل "Hotel" و"Resort & Spa" و"Otel"، وتُحوَّل الأسماء الروسية والعربية إلى أحرف لاتينية، ويُحوَّل الهاتف إلى الصيغة الدولية ويُختزل عنوان الموقع إلى اسم النطاق.
3. **البحث عن المرشحين:** يُقارن السجل بالفنادق القريبة منه فقط: خلية جغرافية بنحو 500 متر، وتشابه الاسم، ونفس الهاتف أو النطاق.
4. **حساب الدرجات:** يجتمع تشابه الاسم وتشابه التضمين (embedding) متعدد اللغات والمسافة وتطابق الهاتف والموقع الإلكتروني وعدد النجوم والرمز البريدي لإنتاج درجة احتمال بين 0 و1.
5. **القرار:** إذا بلغت الدرجة 0.97 فأكثر يعود auto_match، وبين 0.80 و0.97 يعود review، وما دون 0.80 يعود no_match؛ وفي استجابة no_match تكون قيمة hm_id هي null. وتتضمن الاستجابة أيضًا أكثر المرشحين احتمالًا.

## مثال API

**البحث عن مطابقة بالاسم والإحداثيات**

```bash
curl -X POST https://api.hotelmapping.org/v1/match \
  -H "X-API-Key: $HM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "res-55821",
    "name": "Sunset Bay Rsrt. & Spa - Adults",
    "city": "Belek",
    "country": "TR",
    "lat": 36.8539,
    "lng": 31.0556
  }'
```

**200 OK**

```json
{
  "reference": "res-55821",
  "decision": "auto_match",
  "hm_id": "HM-1048213",
  "name": "Sunset Bay Resort & Spa",
  "confidence": 0.984,
  "candidates": [
    { "hm_id": "HM-1048213", "confidence": 0.984, "distance_m": 42 },
    { "hm_id": "HM-1048390", "confidence": 0.412, "distance_m": 310 }
  ]
}
```

_أمثلة الشيفرة توضيحية؛ وقد تتغير أسماء الحقول عند إصدار v1._

## متى تُستخدم Find Match API؟

يربط منتج [مطابقة الفنادق](https://hotelmapping.org/ar/products/hotel-mapping-solutions/) ملفات الموردين بمعرّف HM ID دفعةً واحدة. أما Find Match API فمخصصة للاستعلام الفوري عن سجل واحد. من مجالات الاستخدام النموذجية:

- ربط فنادقكم المتعاقد معها أو سجلات الإكسترانت واحدًا واحدًا بـ[HM ID](https://hotelmapping.org/ar/glossary/hm-id/). وتُخطَّط المطابقة الدفعية للفنادق المتعاقد معها عبر البوابة.
- تجربة سجلات نموذجية قبل البدء بالعمل مع مورّد جديد.
- تحويل أسماء الفنادق المكتوبة كنص حر في أنظمة الحجز أو CRM أو المحاسبة إلى هوية قياسية.
- ربط اسم فندق يُكتب في مربع بحث أو لدى مساعد ذكاء اصطناعي، مع معلومات موقعه، بالمنشأة الصحيحة.

نشرح المنطق العام للمطابقة في [دليل مطابقة الفنادق](https://hotelmapping.org/ar/guide/what-is-hotel-mapping/).

## حقل القرار في الاستجابة

| درجة الثقة | `decision` | ماذا أفعل؟ |
| --- | --- | --- |
| 0.97 فأكثر | `auto_match` | يمكنكم استخدام HM ID مباشرةً |
| 0.80–0.97 | `review` | راجعوا المرشحين؛ وانظروا إلى فروق الاسم والمسافة والهاتف |
| دون 0.80 | `no_match` | تعود `hm_id` بقيمة null. قد لا تكون المنشأة في قاعدة البيانات بعد؛ تحققوا من الاسم والموقع |

تُضبط العتبات بحسب مجموعة اختبار موسومة يدويًا وقد تتغير بين الإصدارات. نشرح الإشارات التي تتكون منها الدرجة في مصطلح [درجة المطابقة](https://hotelmapping.org/ar/glossary/match-score/).

## للحصول على نتيجة أفضل

- **أرسلوا الإحداثيات.** يبدأ البحث عن المرشحين بالخلية الجغرافية. وإذا غابت الإحداثيات تُستخدم المدينة والعنوان؛ فيزداد عدد المرشحين وتنخفض الدرجة عادةً. وتجدون موضوع تحويل العنوان إلى إحداثيات في مصطلح [الترميز الجغرافي](https://hotelmapping.org/ar/glossary/geocoding/).
- **أضيفوا الهاتف وعنوان الموقع الإلكتروني.** رقم الهاتف نفسه أو النطاق نفسه إشارة مطابقة قوية.
- **أرسلوا الاسم كما هو.** تُحوَّل الأسماء بالأحرف السيريلية أو العربية إلى أحرف لاتينية عبر [النقحرة](https://hotelmapping.org/ar/glossary/transliteration/).
- **استخدموا حقل `reference`.** يعود معرّف سجلكم الخاص في الاستجابة كما هو؛ فيسهل ربط النتائج بجدولكم.

## الاستخدام الدفعي والحدود

بدلًا من الاستعلام عن آلاف السجلات واحدًا واحدًا، مرّروا ملفكم إلى مسار مطابقة الفنادق؛ وتعود النتيجة بملف dump يومي كامل وآخر تفاضلي. لا تفتح Find Match API هوية جديدة للسجل الذي تقل درجته عن 0.80؛ أما في مسار الاستلام الدفعي فيُفتح لهذه السجلات معرّف HM ID جديد (قرار new_id). وبمعرّف HM ID الذي تجدونه تصلون أيضًا إلى بيانات [الوجهة](https://hotelmapping.org/ar/products/destination-mapping-solutions/) و[محتوى الفنادق](https://hotelmapping.org/ar/products/hotel-descriptions-solutions/).

حقول الاستجابة تتبع API v1؛ ويُنشر المخطط القاطع في [صفحة المطورين](https://hotelmapping.org/ar/developers/).

## الأسئلة الشائعة

### ما الفرق بين Find Match API والاستعلام برمز المورّد؟

الاستعلام برمز المورّد (GET /v1/suppliers/{supplier}/codes/{code}) يجلب مباشرةً معرّف HM ID لرمز سبقت مطابقته. أما Find Match API فتبحث بالاسم والعنوان والإحداثيات عن سجل لا رمز له أو غير معروف في النظام، وتحسب درجة جديدة.

### ما الحقول الإلزامية في الطلب؟

يلزم اسم الفندق ومعلومات الموقع (الإحداثيات أو الدولة والمدينة والعنوان). الهاتف وعنوان الموقع الإلكتروني والرمز البريدي اختيارية لكنها تقوّي الدرجة.

### ماذا أفعل إذا عاد القرار review؟

قارنوا المرشحين في الاستجابة بحسب الاسم والمسافة والدرجة. ولم تُحسم بعد طريقة إرسال السجلات التي لا تستطيعون البت فيها إلى مراجعة الخبير (البوابة أو API). وتُضاف قرارات الخبراء إلى النموذج كبيانات تدريب.

### هل يمكنني البحث باسم روسي أو عربي؟

نعم. تُحوَّل الأسماء بالأحرف السيريلية والعربية إلى أحرف لاتينية أثناء التطبيع، ويدخل تشابه التضمين متعدد اللغات في الدرجة. ولا حاجة إلى ترجمة الاسم بأنفسكم.

### كيف يمكنني تجربة API؟

يمكنكم التجربة على بيانات توضيحية بحساب sandbox.

## منتجات ذات صلة

- [حلول مطابقة الفنادق](https://hotelmapping.org/ar/products/hotel-mapping-solutions/)
- [حلول مطابقة الوجهات](https://hotelmapping.org/ar/products/destination-mapping-solutions/)
- [حلول أوصاف الفنادق](https://hotelmapping.org/ar/products/hotel-descriptions-solutions/)

## مقالات ذات صلة

- [12 سؤالًا ينبغي طرحها عند اختيار Hotel Mapping API](https://hotelmapping.org/ar/guide/12-questions-hotel-mapping-api/)
- [ما هي مطابقة الفنادق (hotel mapping) وكيف تعمل؟ دليل شامل](https://hotelmapping.org/ar/guide/what-is-hotel-mapping/)
- [كلفة تكرار إدراج الفنادق على الوكالة: التحويل والإلغاء وشكاوى العملاء](https://hotelmapping.org/ar/guide/cost-of-duplicate-hotel-listings/)
