# معماری پلتفرم API هپی‌ملک

## هدف

ارائه خدمات و داده‌های هپی‌ملک به وب‌سایت‌های بنگاهی، اپلیکیشن‌های خدماتی، شرکت‌های ساختمانی، شهرداری‌ها، سازمان‌ها، مؤسسات پژوهشی و پلتفرم‌های همکار، بدون دسترسی مستقیم آن‌ها به دیتابیس داخلی.

## لایه‌های معماری

1. **Developer Portal**: درخواست دسترسی، مستندات، Sandbox و وضعیت سرویس.
2. **API Gateway**: احراز هویت، Scope، Rate Limit، سهمیه، Origin/IP و Request ID.
3. **Domain APIs**: ملک، لید، خدمات، ارزیابی، رصدخانه، پژوهش و پروژه.
4. **Event & Webhook Layer**: انتشار رویداد، صف، Retry و HMAC Signature.
5. **Admin Control Plane**: شریک، کلید، قرارداد، پشتیبانی، مصرف، رخداد و نسخه.
6. **Audit & Analytics**: لاگ غیرحساس، گزارش خطا، هزینه، مصرف و SLA.

## اصول قرارداد API

- Base URL: `/api/v1`
- فرمت: JSON UTF-8
- زمان: ISO-8601 UTC
- شناسه درخواست: `X-Request-ID`
- تکرارنشدن POST: `Idempotency-Key`
- خطا: Problem Details JSON
- نسخه شکسته: فقط با نسخه جدید مسیر یا Header
- Pagination: Cursor-based برای داده‌های حجیم

## Scopeهای اصلی

```text
properties:read       properties:write
cities:read           leads:write
services:read         service_requests:write
valuations:read       valuations:write
observatory:read      reports:read
research_calls:read   research_submissions:write
projects:read         webhooks:manage
usage:read            widgets:read
```

## طبقه‌بندی داده

- `public`: قابل نمایش عمومی.
- `business`: داده تجاری محدود به شریک.
- `personal`: اطلاعات مشتری؛ نیازمند رضایت، قرارداد و حداقل‌گرایی.
- `sensitive`: فقط پس از بررسی ویژه حقوقی و امنیتی.

## چرخه کلید

- ساخت در Sandbox.
- نمایش Secret فقط یک‌بار.
- ذخیره Hash و نسخه رمزگذاری‌شده فقط برای نیاز عملیاتی Webhook.
- گردش حداکثر هر ۹۰ روز برای Live Secret.
- ابطال فوری در رخداد امنیتی.
- دوره هم‌پوشانی کوتاه برای Zero-downtime Rotation.

## Webhook

Headerهای پیشنهادی:

```text
X-HM-Event-ID
X-HM-Event-Type
X-HM-Timestamp
X-HM-Signature: v1=<hex-hmac-sha256>
X-HM-Delivery-ID
```

متن امضا:

```text
{timestamp}.{raw_request_body}
```

سیاست Retry: نمایی، حداکثر ۸ تلاش، سپس `abandoned`. پاسخ موفق باید در بازه 200 تا 299 باشد.

## OAuth 2.0 و مدل تجاری

هر پلن دارای موارد زیر است:

- هزینه ثابت ماهانه.
- سهمیه ماهانه.
- Rate Limit در دقیقه.
- هزینه مصرف اضافه.
- محصولات و Scopeهای مجاز.
- SLA پشتیبانی.
- محیط Sandbox و Live.

## الزامات Live Access

- کاربرد تأییدشده و مالک کسب‌وکار مشخص.
- قرارداد API Terms و در صورت داده شخصی DPA.
- UAT موفق.
- Webhook یا Error Handling تست‌شده.
- Monitoring و Contact اضطراری.
- Origin/IP مشخص.
- برنامه مدیریت Secret و Incident Response.