Use the donor contract now. Expect more surfaces later.

selsal-api already publishes interactive Swagger and machine-readable artifacts. Use those for endpoints, schemas, and auth wiring. Client APIs live under /client/*, admin dashboard APIs live under /admin/*, and driver APIs are planned later, so this guide stays explicit about what is available now and what operational details are easier to explain in prose than in OpenAPI alone.

Open Swagger UI Download OpenAPI JSON Download Postman

Available Downloads

Pick the artifact that matches the job. Client APIs are namespaced under /client/* and admin APIs under /admin/*.

Artifact	Route	Typical Use
HTML	/docs	Interactive Swagger UI for manual inspection and request execution.
JSON	/docs/openapi.json	Best source for generated clients and automated tooling.
YAML	/docs/openapi.yaml	Same contract in a format some gateways, repos, and review workflows prefer.
Postman	/docs/postman-collection.json	Generated from the same OpenAPI contract for manual exploration and team collections.

What This Page Adds

These are the operational details and integration notes that consumers usually ask about after reading the generated contract.

The currently available product surface includes client APIs under /client/* and admin APIs under /admin/*. Driver APIs are planned later and are not part of the published contract yet.
Protected routes use bearer authentication, and Swagger keeps authorization state between requests in the browser.
Error responses support the Accept-Language header with en and ar; the default language is ar.
File preview and download endpoints redirect to short-lived signed storage URLs instead of streaming the object directly through the API process.
File uploads currently accept multipart payloads up to 10 MB.
Generated filenames preserve the original file extension and are normalized before storage.

How To Use These Docs

Keep the contract authoritative and use this page only for context that does not belong inside the schema.

Start with Swagger UI when you need to inspect live behavior or test auth-protected requests quickly.
Move to OpenAPI JSON when generating SDKs, mocks, or contract checks.
Use the Postman collection when a team wants a shareable manual exploration workspace.
Treat this guide as the place for lifecycle notes, limits, and rollout status that may not be obvious from the schema alone.

Notes For Consumers

These conventions help explain behavior that is visible at runtime but easy to miss when skimming endpoints.

Uploads and file access The upload endpoint returns generated filenames plus relative preview and download URLs. Consumers should store the returned filename or URLs rather than reconstructing them client-side.

Auth lifecycle OTP, refresh, profile, and session-management flows live under both the /client/donors/* and /admin/admins/* auth surfaces. Driver auth flows are intentionally not described here yet because they are not part of the current public contract.