مرجع واجهة البرمجة العامة v1

هذه الصفحة تعكس المواصفات الإنجليزية لواجهة القراءة فقط. للتفاصيل الكاملة انظر النسخة الإنجليزية أو ملف OpenAPI.

واجهة البرمجة العامة BOS v1 — OpenAPI Reference

Phase 7 Lite (PR-0067 follow-up) — Documents shipped read-only endpoints only.
Machine-readable spec: public-api-v1-openapi.yaml
Architecture: AD-003 — read-only v1, scoped tokens, rate limits. No write endpoints.

---

Base URL

{origin}/api/v1

Example: https://app.example.com/api/v1/parties

Version negotiation uses the {version} route segment (v1). The api.version middleware adds deprecation headers when applicable.

---

Authentication

Requirement	Detail
Scheme	Authorization: Bearer {sanctum_token}
Tenant scope	Token must include ability tenant:{uuid} matching the tenant you intend to read
Resource scope	Each route group requires an additional api:* ability (see table below)
CRM routes	Tenant must have crm module enabled; otherwise 422

Scoped abilities (App\Integration\Api\ApiAbilities)

Ability	Routes
(none beyond tenant)	GET /meta
api:parties.read	/parties, /parties/{party}
api:items.read	/items, /items/{item}
api:inventory.read	/inventory/availability
api:sales.read	/sales-invoices, /sales-invoices/{id}
api:purchases.read	/purchase-bills, /purchase-bills/{id}
api:crm.read	/crm/leads, /crm/opportunities, show routes

Example token creation (staff user)

$user->createToken('integration', [
    'tenant:'.$tenantId,
    'api:parties.read',
    'api:items.read',
])->plainTextToken;

Missing ability → 403 JSON { "message": "..." }.

---

Rate limiting

Public v1 routes use middleware throttle:120,1 — 120 requests per minute per token/IP (Laravel throttle bucket).

---

Tenant isolation

• Tenant is resolved from the Sanctum token ability — never from query/body.
• Operational data is RLS-scoped (app.current_tenant).
• Cross-tenant UUIDs return 404 (not 403) for operational records.

---

Pagination

List endpoints accept:

Param	Default	Max
page	1	—
per_page	25	100

Response shape (Laravel API resource pagination):

{
  "data": [ ... ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 25, "total": 42, "last_page": 2 }
}

---

Endpoints

GET /meta

Probe API version and resolved tenant.

Response 200

{
  "data": {
    "api_version": "v1",
    "tenant_id": "019e9eab-..."
  }
}

---

Parties (api:parties.read)

GET /parties — active parties only; optional ?q= search on name/code.

GET /parties/{party} — single party; archived parties → 404.

Sample party object:

{
  "id": "...",
  "name": "Acme Ltd",
  "name_translations": { "en": "Acme Ltd" },
  "code": "C-001",
  "email": "buyer@acme.test",
  "phone": null,
  "is_customer": true,
  "is_supplier": false,
  "updated_at": "2026-06-06T12:00:00+00:00"
}

---

Catalog (api:items.read)

GET /items — active items; optional ?q= on SKU/name.

GET /items/{item} — active item only.

---

Inventory (api:inventory.read)

GET /inventory/availability?item_id={uuid}&warehouse_id={uuid?}

{
  "data": {
    "item_id": "...",
    "warehouse_id": null,
    "on_hand": "125.000000"
  }
}

---

Sales (api:sales.read)

GET /sales-invoices — posted invoices and credit notes only.

GET /sales-invoices/{salesDocument} — includes lines array on detail.

---

Purchasing (api:purchases.read)

GET /purchase-bills — posted bills and debit notes.

GET /purchase-bills/{purchaseDocument} — includes lines on detail.

---

CRM (api:crm.read + module)

GET /crm/leads, GET /crm/leads/{crmLead}
GET /crm/opportunities, GET /crm/opportunities/{crmOpportunity}

Module disabled → 422.

---

Explicitly not in v1

• Write/create/update/delete on any entity
• Staff routes under /api/* (non-versioned SPA API)
• Portal routes /api/portal/*
• POS routes /api/v1/pos/* (internal POS surface — not part of AD-003 public integration API)
• Webhooks, connectors (separate integration module)

---

Tests

Feature coverage: backend/tests/Feature/Phase5PublicApiTest.php

---

Last updated: 2026-06-06 (Phase 7 Lite)