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

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

Step 2: Verify structure

ls -la docs/en/

Expected: 4 new directories visible

Step 3: Commit

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:

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

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

Expected: No errors (warnings OK)

Step 3: Commit

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

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

Step 4: Commit

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:

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

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

Step 3: Commit

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:

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

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

Step 3: Commit

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:

---
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 →

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


**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:

- 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

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:

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

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

Step 3: Validate config

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

Step 4: Commit

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

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

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

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

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

Task 11: Final Verification and PR

Step 1: Run full lint

cd docs && npx @redocly/cli lint

Step 2: Test preview

npx @redocly/cli preview --port 8080

Verify all pages work.

Step 3: Push and create PR

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
)"

Developer Portal Implementation Plan

Task 1: Create Directory Structure

Task 2: Create Public API OpenAPI Spec

Task 3: Create B2B API v1 OpenAPI Spec

Task 4: Create B2B API v2 OpenAPI Spec

Task 5: Create Developers API OpenAPI Spec

Task 6: Create Landing Page

Use Cases

Works Great with AI Assistants

Quick Prompts

Support

Task 7: Update Main Sidebar

Task 8: Update Redocly Config

Task 9: Validate All Specs

Task 10: Keep Original Spec as Reference

Task 11: Final Verification and PR

Was this helpful?