# Paziresh24 / Hamdast Widget Development

> For AI agents. Human docs: https://developers.paziresh24.com/apps/quickstart
> Full text: https://developers.paziresh24.com/llms-full.txt

## Human documentation (start here for people)

- Quick Start: https://developers.paziresh24.com/apps/quickstart
- Auth: https://developers.paziresh24.com/authorization
- SDK install: https://developers.paziresh24.com/apps/sdk/install
- APIs: https://developers.paziresh24.com/apis

## Console

https://hamdast.paziresh24.com/console

Paths:
- /console/apps/new — create widget
- /console/apps/{id}/authorization — app_key, x-api-key, scopes
- /console/apps/{id}/webhooks
- /console/apps/{id}/monetization
- /console/sandbox — preview only, API not ready

app_key (slug) for SDK/OAuth. app_id is internal console id only.

## Auth flow

1. Frontend: hamdast.js → initialize({ app_key }) → getSessionToken({ scope })
2. Backend: POST https://hamdast.paziresh24.com/api/v1/apps/{app_key}/oauth/access_token
   Headers: x-api-key. Body: { session_token }
3. API: Authorization: Bearer {access_token}

Never x-api-key in frontend. Never call Paziresh24 APIs from browser.

## Scopes (provider)

- provider.profile.read / provider.profile.write
- provider.appointment.read / provider.appointment.write
- provider.management.read / provider.management.write
- provider.prescription.read
- provider.rasan.read
- provider.rasan.write
- app.hami.messaging — Hami widget bot (x-api-key + app_id, no session)

## Scopes (user)

- user.profile.read / user.profile.write
- user.appointment.read / user.appointment.write

## Scope to API mapping

| scope | service | endpoint |
|-------|---------|----------|
| provider.profile.read | profile | GET /open-platform/v1/profile/information |
| provider.profile.write | profile | PUT /open-platform/v1/profile/information |
| provider.appointment.read | booking | GET /open-platform/v1/booking/appointments |
| provider.appointment.write | booking | DELETE /open-platform/v1/booking/appointments/{id} |
| provider.management.read | booking | GET work-hours, GET vacations |
| provider.management.write | booking | POST/PUT work-hours, POST vacations |
| provider.prescription.read | prescription | GET /v1/rx/services/search |
| provider.rasan.read | rasan | GET /v1/rasan/balance |
| provider.rasan.write | rasan | POST /v1/rasan/messages |
| app.hami.messaging | hami | POST /v1/hami/conversations, POST /v1/hami/messages (x-api-key + app_id) |
| user.profile.read | user-profile | GET /v1/user/information |

OpenAPI x-scopes like view-calendar are internal — use Hamdast scopes in getSessionToken.

## SDK (window.hamdast)

- initialize({ app_key })
- getSessionToken({ scope: string[] }) → session token
- redirect.dispatch({ path, newContext? }) — doctor iframe only
- flow.dispatch("BOOKING.RECEIPT" | "BOOKING.ONLINE_VISIT_CHANNEL") — patient addon
- payment.pay({ product_key | receipt_id, payload? })
- payment.subscribe({ plan_key? })
- payment.payForDoctorService({ amount, payload? }) — patient pays for a service on doctor profile

Events: HAMDAST_PAYMENT_SUCCESS, HAMDAST_PAYMENT_CANCEL, HAMDAST_PAYMENT_ERROR,
HAMDAST_PAYMENT_SUBSCRIBE_SUCCESS, HAMDAST_PAYMENT_SUBSCRIBE_CANCEL,
HAMDAST_PAYMENT_DOCTOR_SERVICE_SUCCESS, HAMDAST_PAYMENT_DOCTOR_SERVICE_CANCEL,
HAMDAST_PAYMENT_DOCTOR_SERVICE_ERROR

## Cookbook recipes

### Appointments list
scope: provider.appointment.read
GET https://apigw.paziresh24.com/open-platform/v1/booking/appointments

### Profile edit
scopes: provider.profile.read, provider.profile.write
GET/PUT /open-platform/v1/profile/information

### Work hours
scope: provider.management.read
GET /open-platform/v1/booking/work-hours

### Patient flow addon
flow.dispatch("BOOKING.RECEIPT") or BOOKING.ONLINE_VISIT_CHANNEL

### Payment
payment.pay → verify POST .../apps/{app_key}/monetization/verify with x-api-key

### Hami widget bot
scope: app.hami.messaging (verified in console)
Headers: x-api-key, app_id (app id). No session_token.
POST https://openapi.paziresh24.com/v1/hami/messages { user_id, content }
Recipe: ai-docs/cookbook/hami-widget-bot.md

### Doctor service payment
`payment.payForDoctorService({ amount })` — amount in Rials
Events: HAMDAST_PAYMENT_DOCTOR_SERVICE_SUCCESS | CANCEL | ERROR
`payable = amount + amount × 0.3 × 0.1` — no monetization/verify
https://developers.paziresh24.com/apps/sdk/doctor-service-payment

### Redirect to panel
redirect.dispatch({ path: "/dashboard/apps/drapp/appointments" })

## Troubleshooting

- USER_CLOSED_POPUP → retry getSessionToken
- INVALID_SESSION_TOKEN → new token
- DEVELOPER_NOT_AUTHORIZED → check x-api-key
- 403 → scope not enabled/approved in console
- hamdast undefined → load script in index.html
- CORS → use backend proxy
- redirect/flow no-op → not in iframe

## Webhooks

Svix. Console: /console/apps/{id}/webhooks. Verify signature with webhook secret.
See llms-full.txt for code sample.

## Assets

- OpenAPI bundle: https://developers.paziresh24.com/openapi-bundle.json
- TypeScript: https://developers.paziresh24.com/hamdast.d.ts
- Starter: https://github.com/paziresh24/widget-starter
- AGENTS.md: https://github.com/paziresh24/documation/blob/main/AGENTS.md

## API services

booking, profile, search, reviews, chats, channel, katibe, user-profile, widget, appointments-addon, transactions-subscriptions, prescription

Hosts:
- apigw.paziresh24.com — most open-platform APIs
- hamdast.paziresh24.com — widget, channel, OAuth
- openapi.paziresh24.com — search, user-profile, transactions, prescription (rx)

## Rules for AI agents

- NEVER x-api-key in frontend
- NEVER direct API calls from browser
- Use app_key in OAuth URLs
- Use hamdast.redirect not window.location in iframe
- Minimum scopes only