Zapis Appointment Assistant

Use this skill to run end-to-end booking support on Zapis.kz: collect constraints, inspect availability, propose options, and submit booking only after explicit user confirmation.

Workflow

1. Collect booking inputs.
2. Open Zapis.kz listing/profile and find matching barbers/services.
3. Extract available slots and normalize them with scripts/slots_normalize.py.
4. Present 3-5 best options in local timezone.
5. Request explicit final confirmation.
6. Submit booking and return confirmation details.

Step 1: Collect Inputs

Collect the minimum required fields before browsing:

• City or salon/profile URL on Zapis.kz
• Service (for example, haircut, beard trim)
• Preferred date range
• Preferred time window
• Preferred barber (optional)
• Phone number/name to use for booking (if required by form)

If essential fields are missing, ask focused follow-up questions before proceeding.

Step 2: Find Matching Slots

Prefer API automation for reliability. Use browser automation only when API payloads are unknown.

• Prefer direct salon/profile URLs when user has one.
• If user gives only city/service, search and shortlist relevant salons/barbers first.
• Capture slot data with: barber name, service, date, start time, timezone (if visible), booking URL.

Use scripts/zapis_api.py for authenticated schedule calls:

python3 scripts/zapis_api.py \
  --env-file references/.env.example \
  available-times \
  --payload-file references/available-times.sample.json \
  --out /tmp/zapis-slots.json

Fallback extractor (UI-level):

python3 scripts/zapis_playwright.py list-slots \
  --url "https://zapis.kz/..." \
  --service "Haircut" \
  --out /tmp/zapis-slots-ui.json

If schedule loading fails, retry once with page refresh and then report blocker with exact step.

Step 3: Normalize and Rank Options

Use scripts/slots_normalize.py to sort/deduplicate slots.

Example:

python3 scripts/slots_normalize.py --input /tmp/slots.json --tz Asia/Almaty --limit 5

Input format is documented in references/data-contract.md.

Ranking rules:

• Prioritize exact time-window matches.
• Then prioritize preferred barber.
• Then choose earliest available slot.

Step 4: Confirm Before Booking

Before pressing final submit, send a one-block confirmation summary:

• Salon + barber
• Service
• Date and time with timezone
• Final price (if visible)
• Contact data that will be submitted

Require clear user intent such as: Confirm booking. Do not submit when confirmation is ambiguous.

Use booking script in two phases:

1. Dry-run preview (no submit):

python3 scripts/zapis_playwright.py book \
  --url "https://zapis.kz/..." \
  --barber "Dias" \
  --service "Haircut" \
  --date "20 Feb" \
  --target-time "14:30" \
  --contact-name "Alex" \
  --contact-phone "+7701XXXXXXX" \
  --dry-run \
  --headed \
  --out /tmp/zapis-book-preview.json

2. Submit only after explicit user confirmation:

python3 scripts/zapis_playwright.py book \
  --url "https://zapis.kz/..." \
  --barber "Dias" \
  --service "Haircut" \
  --date "20 Feb" \
  --target-time "14:30" \
  --contact-name "Alex" \
  --contact-phone "+7701XXXXXXX" \
  --confirm \
  --headed \
  --out /tmp/zapis-book-result.json

API-first booking (recommended when payload is known):

python3 scripts/zapis_api.py --env-file .env preview --payload-file /tmp/preview-payload.json
python3 scripts/zapis_api.py --env-file .env create --payload-file /tmp/create-payload.json

Step 5: Submit and Report

After successful booking, return:

• Appointment datetime with timezone
• Barber and service
• Address/salon
• Confirmation id/reference (if present)
• Cancellation/reschedule link or instructions (if present)

If booking fails due to slot race condition, fetch nearest alternatives and offer immediate rebook options.

Reschedule/Cancel Flow

When user asks to reschedule/cancel:

1. Locate existing appointment (link/code/phone).
2. Confirm target action (reschedule or cancel).
3. For reschedule: repeat availability flow and confirm final change before submit.
4. Report final status and any penalties/constraints shown by platform.

Resources

• references/zapis-workflow.md: operational playbook and failure handling.
• references/data-contract.md: JSON schemas for slot extraction/normalization.
• references/api-automation.md: API login/schedule/booking runbook.
• references/playwright-automation.md: selectors, runbook, and troubleshooting for live automation.
• references/.env.example: required environment variables for API auth.
• references/available-times.sample.json: sample payload for schedule lookup.
• scripts/slots_normalize.py: deterministic sorting + deduplication utility.
• scripts/zapis_api.py: API-first auth/schedule/preview/create automation.
• scripts/zapis_playwright.py: Playwright automation for slot discovery and booking.