# Developer Portal Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.


**Goal:** Transform monolithic API docs into multi-API developer portal with landing page and 4 separate OpenAPI specs.

**Architecture:** Split current `en/index.yaml` into 4 OpenAPI specs (public, b2b-v1, b2b-v2, developers). Create landing page with use cases and AI coding guide. Use shared components via $ref.

**Tech Stack:** Redocly, OpenAPI 3.1, Markdown

## Task 1: Create Directory Structure

**Files:**

- Create: `docs/en/public/`
- Create: `docs/en/b2b-v1/`
- Create: `docs/en/b2b-v2/`
- Create: `docs/en/developers/`


**Step 1: Create directories**

```bash
mkdir -p docs/en/public docs/en/b2b-v1 docs/en/b2b-v2 docs/en/developers
```

**Step 2: Verify structure**

```bash
ls -la docs/en/
```

Expected: 4 new directories visible

**Step 3: Commit**

```bash
git add docs/en/
git commit -m "chore: create multi-api directory structure"
```

## Task 2: Create Public API OpenAPI Spec

**Files:**

- Create: `docs/en/public/openapi.yaml`


**Step 1: Create Public API spec with paths**

Create `docs/en/public/openapi.yaml`:

```yaml
openapi: 3.1.1
info:
  title: 'Altegio Public API'
  version: '1.0.0'
  description: |
    Public API for integrating online booking into third-party websites and mobile applications.

    **Base URL:** `https://api.alteg.io/api`

    ## Authentication

    All requests require partner authorization via Bearer token:
```

Authorization: Bearer <partner_token>

```

Get your partner token at [Altegio Marketplace](https://app.alteg.io/appstore/developers/1).

servers:
- url: https://api.alteg.io/api
description: Production

x-tagGroups:
- name: Public API
tags:
  - Authentication
  - Online Booking
  - Client Personal Cabinet

tags:
- name: Authentication
description: End-customer authentication methods.
- name: Online Booking
description: Booking widget integration endpoints.
- name: Client Personal Cabinet
description: End-customer account management.

paths:
# Authentication
'/v1/book_code/{location_id}':
$ref: ../paths/online-booking/book_code__company_id.yml
'/v1/booking/auth':
$ref: ../paths/booking_users/booking__auth.yml
'/v1/user/auth':
$ref: ../paths/user_bookings/user__auth.yml

# Online Booking
'/v1/bookform/{id}':
$ref: ../paths/online-booking/bookform__id.yml
'/v1/i18n/{lang_code}':
$ref: ../paths/online-booking/i18n__lang_code.yml
'/v1/book_services/{location_id}':
$ref: ../paths/online-booking/book_services__company_id.yml
'/v1/book_staff/{location_id}':
$ref: ../paths/online-booking/book_staff__company_id.yml
'/v1/book_staff_seances/{location_id}/{team_member_id}':
$ref: ../paths/online-booking/book_staff_seances__company_id__staff_id.yml
'/v1/book_dates/{location_id}':
$ref: ../paths/online-booking/book_dates__company_id.yml
'/v1/book_times/{location_id}/{team_member_id}/{date}':
$ref: ../paths/online-booking/book_times__company_id__staff_id__date.yml
'/v1/book_check/{location_id}':
$ref: ../paths/online-booking/book_check__company_id.yml
'/v1/book_record/{location_id}':
$ref: ../paths/online-booking/book_record__company_id.yml
'/v1/book_record/{location_id}/{record_id}/{record_hash}':
$ref: ../paths/online-booking/book_record__company_id__record_id__record_hash.yml
'/v1/book_record/{location_id}/{record_id}':
$ref: ../paths/online-booking/book_record__company_id__record_id.yml
'/v1/activity/{location_id}/{event_id}/book':
$ref: ../paths/online-booking/event__location_id__event_id__book.yml
'/v1/privacy_policy/{location_id}':
$ref: ../paths/gdpr/privacy_policy__company_id.yml

# Client Personal Cabinet
'/v1/booking/user':
$ref: ../paths/booking_users/booking__user.yml
'/v1/booking/user/data':
$ref: ../paths/booking_users/booking__user__data.yml
'/v1/booking/user/password':
$ref: ../paths/booking_users/booking__user__password.yml
'/v1/booking/user/phone_confirmation':
$ref: ../paths/booking_users/booking__user__phone_confirmation.yml
'/v1/user/records/{record_id}/{record_hash}':
$ref: ../paths/user_bookings/user__records__record_id__record_hash.yml
'/v1/master_record_review/{record_token}':
$ref: ../paths/client_comments/master_record_review__record_token.yml
```

**Step 2: Validate spec**

```bash
cd docs && npx @redocly/cli lint en/public/openapi.yaml
```

Expected: No errors (warnings OK)

**Step 3: Commit**

```bash
git add docs/en/public/openapi.yaml
git commit -m "feat: add Public API OpenAPI spec"
```

## Task 3: Create B2B API v1 OpenAPI Spec

**Files:**

- Create: `docs/en/b2b-v1/openapi.yaml`


**Step 1: Create B2B v1 spec header**

Create `docs/en/b2b-v1/openapi.yaml` with info, servers, tags, x-tagGroups sections. Include all tags from POS & Scheduling and Administrative groups.

**Step 2: Add all v1 paths from current index.yaml**

Copy paths sections:

- Authentication B2B (line 720-721)
- Locations (723-727)
- Services (729-752)
- Team Members (754-767)
- Clients (769-788)
- Users & Permissions (790-811)
- Appointments (813-835)
- Events v1 (837-874)
- Schedule & Resources (876-920)
- Products (922-972)
- Inventory (974-1022)
- Sales (1024-1051)
- Payments (1053-1078)
- Analytics & Reports (section from index.yaml)
- Tags (section)
- Deposits (section)
- Loyalty Cards (section)
- Subscriptions & Certificates (section)
- Loyalty Programs (section)
- Salary (section)
- Notifications (section)
- Online Booking Settings (section)
- Custom Fields (section)
- Chain Management (section)
- Chain Loyalty Programs (section)
- Fiscalization (section)
- Utilities (section)


Update all $ref paths: `paths/` → `../paths/`

**Step 3: Validate spec**

```bash
cd docs && npx @redocly/cli lint en/b2b-v1/openapi.yaml
```

**Step 4: Commit**

```bash
git add docs/en/b2b-v1/openapi.yaml
git commit -m "feat: add B2B API v1 OpenAPI spec"
```

## Task 4: Create B2B API v2 OpenAPI Spec

**Files:**

- Create: `docs/en/b2b-v2/openapi.yaml`


**Step 1: Create B2B v2 spec with same group structure as v1**

Create `docs/en/b2b-v2/openapi.yaml`:

```yaml
openapi: 3.1.1
info:
  title: 'Altegio B2B API v2'
  version: '2.0.0'
  description: |
    Next-generation B2B API with improved design and consistency.

    **Base URL:** `https://api.alteg.io/api`

    ## Authentication

    Requires both partner and user authorization:
```

Authorization: Bearer <partner_token>, User <user_token>

```

servers:
- url: https://api.alteg.io/api
description: Production

x-tagGroups:
- name: POS & Scheduling
tags:
  - Team Members
  - Events
- name: Administrative
tags:
  - Tags

tags:
- name: Team Members
description: Team member management v2.
- name: Events
description: Group events management v2.
- name: Tags
description: Client tagging system v2.

paths:
# Team Members - Positions
'/v2/companies/{location_id}/positions':
$ref: ../paths/positions/v2/api_v2.company.positions.list.create.yml
'/v2/companies/{location_id}/positions/{position_id}':
$ref: ../paths/positions/v2/api_v2.company.positions.read.update.delete.yml

# Events
'/v2/companies/{location_id}/activities':
$ref: ../paths/events/v2/api_v2.location.events.list.create.yml
'/v2/companies/{location_id}/activities/{event_id}':
$ref: ../paths/events/v2/api_v2.location.events.read.update.delete.yml
'/v2/companies/{location_id}/activities/{event_id}/records':
$ref: ../paths/events/v2/api_v2.location.events.records.create.yml
'/v2/companies/{location_id}/activities/{event_id}/records/{record_id}':
$ref: ../paths/events/v2/api_v2.location.events.records.update.delete.yml

# Tags
'/v2/companies/{location_id}/tags':
$ref: ../paths/tags/v2/api_v2.company.tags.list.create.yml
'/v2/companies/{location_id}/tags/{tag_id}':
$ref: ../paths/tags/v2/api_v2.company.tags.read.update.delete.yml
'/v2/companies/{location_id}/clients/{client_id}/tags':
$ref: ../paths/tags/v2/api_v2.company.clients.tags.list.update.yml
```

**Step 2: Validate spec**

```bash
cd docs && npx @redocly/cli lint en/b2b-v2/openapi.yaml
```

**Step 3: Commit**

```bash
git add docs/en/b2b-v2/openapi.yaml
git commit -m "feat: add B2B API v2 OpenAPI spec"
```

## Task 5: Create Developers API OpenAPI Spec

**Files:**

- Create: `docs/en/developers/openapi.yaml`


**Step 1: Create Developers API spec**

Create `docs/en/developers/openapi.yaml`:

```yaml
openapi: 3.1.1
info:
  title: 'Altegio Developers API'
  version: '1.0.0'
  description: |
    APIs for building marketplace applications, webhooks, and integrations.

    **Base URL:** `https://api.alteg.io/api`

servers:
  - url: https://api.alteg.io/api
    description: Production

x-tagGroups:
  - name: Developers
    tags:
      - Marketplace
      - Webhooks
      - VoIP Integration
      - Dictionaries

tags:
  - name: Marketplace
    description: Marketplace application management and billing.
  - name: Webhooks
    description: Event subscription and webhook configuration.
  - name: VoIP Integration
    description: Telephony integration endpoints.
  - name: Dictionaries
    description: Reference data (countries, cities, business types).

paths:
  # Marketplace
  '/v1/marketplace/application/{application_id}/salons':
    $ref: ../paths/marketplace/marketplace.partner.application_salon_list.yml
  '/v1/marketplace/application/{application_id}/tariffs':
    $ref: ../paths/marketplace/marketplace.partner.applications.tariffs.list.yml
  '/v1/marketplace/application/add_discount':
    $ref: ../paths/marketplace/marketplace.partner.application_add_discount.yml
  '/v1/marketplace/application/payment_link':
    $ref: ../paths/marketplace/marketplace.partner.application_payment_link.yml
  '/v1/marketplace/application/update_channel':
    $ref: ../paths/marketplace/marketplace.partner.applications.update_channel.yml
  '/v1/marketplace/salon/{location_id}/application/{application_id}':
    $ref: ../paths/marketplace/marketplace.partner.integration_status.yml
  '/v1/marketplace/salon/{location_id}/application/{application_id}/uninstall':
    $ref: ../paths/marketplace/marketplace.partner.uninstall.yml
  '/v1/marketplace/partner/callback':
    $ref: ../paths/marketplace/marketplace.notifications.callback_with_settings.yml
  '/v1/marketplace/partner/callback/redirect':
    $ref: ../paths/marketplace/marketplace.notifications.callback_with_settings_and_redirect.yml
  '/v1/marketplace/partner/payment':
    $ref: ../paths/marketplace/marketplace.notifications.callback_with_payment.yml
  '/v1/marketplace/partner/payment/refund/{payment_id}':
    $ref: ../paths/marketplace/marketplace.partner.callback_with_payment.refund.yml
  '/v1/marketplace/partner/short_names':
    $ref: ../paths/marketplace/marketplace.notifications.short_names.yml
  '/v1/marketplace_webhook':
    $ref: ../paths/marketplace/marketplace.webhook.yml

  # Webhooks
  '/v1/hooks_settings/{location_id}':
    $ref: ../paths/webhooks/hooks_settings__company_id.yml

  # VoIP Integration
  '/v1/voip/integration':
    $ref: ../paths/voip/voip__integration.yml
  '/v1/voip/integration/calls':
    $ref: ../paths/voip/voip.integration.calls_list.yml

  # Dictionaries
  '/v1/countries':
    $ref: ../paths/countries/countries.yml
  '/v1/cities':
    $ref: ../paths/cities/cities.yml
  '/v1/references/business_groups_with_types':
    $ref: ../paths/dicts/references__business_groups_with_types.yml
```

**Step 2: Validate spec**

```bash
cd docs && npx @redocly/cli lint en/developers/openapi.yaml
```

**Step 3: Commit**

```bash
git add docs/en/developers/openapi.yaml
git commit -m "feat: add Developers API OpenAPI spec"
```

## Task 6: Create Landing Page

**Files:**

- Create: `docs/en/index.md`


**Step 1: Create landing page content**

Create `docs/en/index.md`:

```markdown
---
title: Altegio API
---

# Altegio API

Build powerful integrations for appointment scheduling and business management.

<div class="api-cards">

## API Reference

### [Public API](public/openapi.yaml)
Online booking integration for websites and mobile apps. Embed scheduling into your platform.

### [B2B API v1](b2b-v1/openapi.yaml)
Full business operations: scheduling, clients, payments, inventory, loyalty, and more.

### [B2B API v2](b2b-v2/openapi.yaml)
Next-gen endpoints with improved design. Growing collection of modernized APIs.

### [Developers API](developers/openapi.yaml)
Marketplace applications, webhooks, VoIP integration, and reference data.

</div>

## Quick Start

```bash
# Get available time slots for online booking
curl -X GET "https://api.alteg.io/api/v1/book_times/{location_id}/{staff_id}/{date}" \
  -H "Authorization: Bearer {partner_token}" \
  -H "Accept: application/vnd.api.v2+json"
```

[Get your API key →](https://app.alteg.io/appstore/developers/1)

## Use Cases

|  |  |
|  --- | --- |
| **Booking Widget** | Embed scheduling into websites, mobile apps, or kiosks |
| **AI Assistants & Chatbots** | Let GPT, Claude or custom bots book appointments via API |
| **Analytics Dashboard** | Build custom reports, BI integrations, data warehouses |
| **CRM Sync** | Two-way sync with Salesforce, HubSpot, custom CRMs |
| **White-label Apps** | Build branded booking apps for your clients |
| **POS Integration** | Connect payments, receipts, fiscal printers |
| **Inventory Automation** | Sync stock levels with suppliers, e-commerce |
| **Custom Notifications** | Webhooks for real-time events, custom messaging |


## Works Great with AI Assistants

| Tool | How to use |
|  --- | --- |
| **Claude / ChatGPT** | Copy the OpenAPI spec URL and paste into chat: *"Use this API spec to build a booking integration"* |
| **Cursor / Copilot** | Add spec to project: `curl -o altegio-api.yaml https://developer.alteg.io/en/b2b-v1/openapi.yaml` |
| **Claude Code** | Point to docs: *"Read https://developer.alteg.io/en/public/ and implement appointment booking"* |
| **MCP Server** | Connect AI agents: `npx @redocly/mcp-server --spec https://developer.alteg.io/en/b2b-v1/openapi.yaml` |


### Quick Prompts

```
"Build a Telegram bot that books appointments using Altegio API"
"Create a React widget showing available time slots"
"Sync Altegio clients with my PostgreSQL database"
```

## Support

- Email: api@alteg.io
- [Knowledge Base](https://alteg.io/support)


```

**Step 2: Commit**

```bash
git add docs/en/index.md
git commit -m "feat: add developer portal landing page"
```

## Task 7: Update Main Sidebar

**Files:**

- Modify: `docs/en/sidebars.yaml`


**Step 1: Update sidebar with multi-API navigation**

Replace content of `docs/en/sidebars.yaml`:

```yaml
- page: index.md
  label: Home
- separator: API Reference
- page: public/openapi.yaml
  label: Public API
- page: b2b-v1/openapi.yaml
  label: B2B API v1
- page: b2b-v2/openapi.yaml
  label: B2B API v2
- page: developers/openapi.yaml
  label: Developers API
- separator: Resources
- label: Get API Key
  href: https://app.alteg.io/appstore/developers/1
```

**Step 2: Commit**

```bash
git add docs/en/sidebars.yaml
git commit -m "feat: update sidebar for multi-API navigation"
```

## Task 8: Update Redocly Config

**Files:**

- Modify: `docs/redocly.yaml`


**Step 1: Update apis section**

In `docs/redocly.yaml`, replace `apis` section:

```yaml
apis:
  public@v1:
    root: en/public/openapi.yaml
  b2b@v1:
    root: en/b2b-v1/openapi.yaml
  b2b@v2:
    root: en/b2b-v2/openapi.yaml
  developers@v1:
    root: en/developers/openapi.yaml
```

**Step 2: Update redirects**

```yaml
redirects:
  '/':
    to: '/en/'
  '/api':
    to: '/en/'
  '/api/**':
    to: '/en/'
```

**Step 3: Validate config**

```bash
cd docs && npx @redocly/cli check-config
```

**Step 4: Commit**

```bash
git add docs/redocly.yaml
git commit -m "feat: configure multi-API in redocly.yaml"
```

## Task 9: Validate All Specs

**Step 1: Lint all OpenAPI specs**

```bash
cd docs
npx @redocly/cli lint en/public/openapi.yaml
npx @redocly/cli lint en/b2b-v1/openapi.yaml
npx @redocly/cli lint en/b2b-v2/openapi.yaml
npx @redocly/cli lint en/developers/openapi.yaml
```

**Step 2: Preview locally**

```bash
npx @redocly/cli preview --port 8080
```

Open http://localhost:8080/en/ and verify:

- Landing page renders correctly
- All 4 API links work
- Sidebar navigation works


**Step 3: Fix any issues found**

## Task 10: Keep Original Spec as Reference

**Files:**

- Rename: `docs/en/index.yaml` → `docs/en/openapi-combined.yaml`


**Step 1: Rename original spec**

```bash
mv docs/en/index.yaml docs/en/openapi-combined.yaml
```

**Step 2: Update any references**

Check if anything references `index.yaml` and update to new name or remove.

**Step 3: Commit**

```bash
git add docs/en/
git commit -m "chore: rename combined spec for reference"
```

## Task 11: Final Verification and PR

**Step 1: Run full lint**

```bash
cd docs && npx @redocly/cli lint
```

**Step 2: Test preview**

```bash
npx @redocly/cli preview --port 8080
```

Verify all pages work.

**Step 3: Push and create PR**

```bash
git push -u origin feature/developer-portal-restructure
gh pr create --title "feat: restructure docs into multi-API developer portal" --body "$(cat <<'EOF'
## Summary
- Split monolithic API into 4 separate OpenAPI specs
- Added landing page with use cases and AI coding guide
- Created multi-API sidebar navigation

## APIs
- Public API (B2C): Online booking, client cabinet
- B2B API v1: Full business operations
- B2B API v2: Next-gen endpoints (positions, events, tags)
- Developers API: Marketplace, webhooks, VoIP

## Test Plan
- [ ] Landing page renders at /en/
- [ ] All 4 API specs load without errors
- [ ] Sidebar navigation works
- [ ] Search works across all APIs
EOF
)"
```