المصادقة | SalonBookIt Developers

الملخص

عام

API Key

يحدد نشاطك التجاري في كل طلب. مطلوب لجميع نقاط النهاية.

يُحصل عليه من لوحة التحكم
يُرسل في الرأس X-API-Key
البادئة hh_pub_ (pública) o hh_sec_ (privada)

مصادق

JWT Token

يصادق على عميل معين. مطلوب لنقاط النهاية الخاصة.

يُحصل عليه عبر /api/v1/auth/login/
يُرسل في الرأس Authorization
ينتهي خلال 24 ساعة

API Keys

مفتاح API الخاص بك يحدد نشاطك التجاري ويجب تضمينه في جميع طلبات API.

الحصول على مفتاح API

سجل الدخول إلى Dashboard
اذهب إلى الإعدادات → التكاملات
انقر على إنشاء مفتاح API جديد
Asigna un nombre descriptivo (ej: "Widget Web", "App Móvil")
انسخ واحفظ مفتاح API بشكل آمن

استخدام مفتاح API

ضمّن مفتاح API في الرأس X-API-Key لكل طلب:

cURL

curl -X GET "https://app.salonbookit.com/api/v1/negocio/" \
  -H "X-API-Key: hh_pub_live_abc123def456..."

JavaScript

const response = await fetch('https://app.salonbookit.com/api/v1/servicios/', {
    headers: {
        'X-API-Key': 'hh_pub_live_abc123def456...'
    }
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://app.salonbookit.com/api/v1/servicios/',
    headers={'X-API-Key': 'hh_pub_live_abc123def456...'}
)
data = response.json()

PHP

$ch = curl_init('https://app.salonbookit.com/api/v1/servicios/');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: hh_pub_live_abc123def456...'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

أنواع مفتاح API

Las API Keys tienen dos dimensiones: tipo (pública/privada) y entorno (producción/pruebas).

Por tipo

البادئة	النوع	الاستخدام
`hh_pub_`	Pública	Para widgets y frontend. Permisos limitados a lectura y crear reservas.
`hh_sec_`	Privada	Para backend. No exponer en código cliente.

Por entorno

Sufijo	البيئة	الاستخدام
`_live_`	الإنتاج	بيانات حقيقية، معاملات حقيقية
`_test_`	اختبار	بيانات اختبار، بدون رسوم حقيقية

Ejemplos de formatos completos:

hh_pub_live_... - Pública de producción (para widgets en producción)
hh_pub_test_... - Pública de pruebas (para desarrollo de widgets)
hh_sec_live_... - Privada de producción (para tu backend)
hh_sec_test_... - Privada de pruebas (para desarrollo backend)

أمان مفاتيح API

لا تضمّن أبداً مفتاح API في كود من جانب العميل يكون مرئياً للجمهور. للويدجت، نستخدم مفتاح API بصلاحيات محدودة تسمح فقط بعمليات القراءة وإنشاء الحجوزات.

مصادقة JWT

تستخدم نقاط النهاية التي تتطلب مصادقة العميل رموز JWT. تشمل هذه النقاط:

عرض حجوزات العميل
عرض/تعديل ملف العميل
الاستعلام عن نقاط الولاء
عرض سجل الطلبات

الحصول على رمز JWT

POST /api/v1/auth/login/

Request

cURL

curl -X POST "https://app.salonbookit.com/api/v1/auth/login/" \
  -H "X-API-Key: hh_pub_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "cliente@ejemplo.com",
    "password": "contraseña123"
  }'

Response (200 OK) - العميل

JSON

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tipo": "cliente",
    "cliente": {
      "id": 123,
      "nombre": "Juan",
      "apellido": "García",
      "email": "cliente@ejemplo.com",
      "telefono": "+34612345678",
      "puntos": 150,
      "nivel": "gold"
    }
  }
}

Response (200 OK) - Staff

Si las credenciales corresponden a un miembro del staff:

JSON

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tipo": "staff",
    "staff": {
      "id": 1,
      "nombre": "María",
      "apellido": "López",
      "email": "maria@salon.com",
      "telefono": "+34612345678",
      "rol": "admin",
      "permisos": {
        "puede_ver_reservas": true,
        "puede_crear_reservas": true,
        "puede_ver_clientes": true
      }
    }
  }
}

استخدام رمز JWT

ضمّن الرمز في الرأس Authorization مع البادئة Bearer:

cURL

curl -X GET "https://app.salonbookit.com/api/v1/cliente/reservas/" \
  -H "X-API-Key: hh_pub_live_abc123..." \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

تجديد الرمز

تنتهي صلاحية الرموز خلال 24 ساعة. استخدم نقطة تجديد للحصول على رمز جديد:

POST /api/v1/auth/refresh/

cURL

curl -X POST "https://app.salonbookit.com/api/v1/auth/refresh/" \
  -H "X-API-Key: hh_pub_live_abc123..." \
  -H "Authorization: Bearer TOKEN_ACTUAL"

Rate Limiting

لدى الواجهة حدود للطلبات لضمان خدمة مستقرة:

الحد	النافذة	الوصف
120 requests	دقيقة واحدة	الحد العام لكل مفتاح API
20 محاولة	15 دقيقة	تسجيل الدخول (لكل IP)
10 محاولات	ساعة واحدة	التسجيل (لكل IP)

رؤوس حد الطلبات

كل استجابة تتضمن رؤوس معلوماتية:

Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704067200

Header	الوصف
`X-RateLimit-Limit`	الحد الأقصى للطلبات المسموح بها
`X-RateLimit-Remaining`	الطلبات المتبقية في النافذة الحالية
`X-RateLimit-Reset`	الطابع الزمني يونكس عند إعادة تعيين العداد

خطأ 429: طلبات كثيرة جداً

إذا تجاوزت الحد، ستتلقى خطأ 429:

JSON

{
  "success": false,
  "error": "لقد تجاوزت حد الطلبات. حاول مرة أخرى خلال 45 ثانية.",
  "code": "RATE_LIMIT_EXCEEDED"
}

أخطاء المصادقة

الرمز	HTTP Status	الوصف
`MISSING_API_KEY`	401	لم يتم تضمين رأس X-API-Key
`INVALID_API_KEY`	401	مفتاح API غير صالح أو غير موجود
`API_KEY_DISABLED`	403	تم تعطيل مفتاح API
`API_KEY_EXPIRED`	403	انتهت صلاحية مفتاح API
`INVALID_TOKEN`	401	رمز JWT غير صالح أو مشوه
`TOKEN_EXPIRED`	401	رمز JWT منتهي الصلاحية
`INVALID_CREDENTIALS`	401	البريد الإلكتروني أو كلمة المرور غير صحيحة