# API plan — POST /api/v1/provider/subscriptions   (audience: `provider` · flow: `billing`)

> مكتفٍ بذاته. ابنِ من هذا الملف عبر `docs/build/build-api.md`. لا تجمع خطوات فلو متعدّد في endpoint واحد.

## 1) Identity
- **Endpoint:** `POST /api/v1/provider/subscriptions`
- **Audience / platform:** `provider` — `app`
- **Flow / screen:** `billing` — Figma: تأكيد اشتراك أعمال — **screen link:** https://www.figma.com/design/pIFyEHCimnG9rIRh3TMnHC/HR?node-id=17561-1350&m=dev — **action:** تأكيد
- **Auth / guard:** `auth:provider`
- **Rate limit:** none
- **Ownership:** self morph
- **Consumer:** اشتراك الشركة

## 2) How it works — logic
- نفس الباحث بدون بوابة.

## 3) Request
- Path / query: —
- Body: `plan_id`
- Files: —
- **Form Request:** `App\Http\Requests\Api\Provider\Billing\SubscribeRequest` (extends `BaseApiRequest`).
- [x] no client-only rules
- [x] enum via Rule::enum
- [x] unique/exists soft-delete-aware
- [x] phone country_code+PhoneNormalizer
- [x] messages in validation.php

## 4) Response
- **Success:** 201
- **UI copy:** ar `تم تفعيل تجربة الأعمال` · en `Business trial started`
- **Shape:** flat `data` · enums `{value,label}` · token داخل Resource إن وُجد.
- **Errors:** 422 · 401 · 403 · 404

## 5) Postman
- **Folder path:** `Logic` / `provider-billing` · **Request name:** `subscribe`
- **URL:** `{{base_url}}provider/subscriptions` · **POST**
- **Auth:** Bearer {{provider_token}}
- **Body:** قيم عربية واقعية (محمد العلي / 0551112233 / الرياض)
- **Examples:** ✅ success · ⚠️ 422 · ❌ 401

## 6) Build checklist
- [ ] route + thin controller + service + Form Request + Resource
- [ ] lang ar+en · tests · Postman من §5