# Developer Portal Restructure Design

## Overview

Transform the current monolithic API documentation into a multi-API developer portal with a landing page and 4 separate API documentations.

**Target audience:** Professional developers + vibe-coders/AI integrators (equal priority)

**Style:** Developer-first, minimalist (Stripe/Twilio style)

## Structure

```
docs/
├── redocly.yaml              # Main config
├── @theme/                   # Custom styles
└── en/                       # English (primary locale)
    ├── index.md              # Landing page → /en/
    ├── sidebars.yaml         # Main navigation
    ├── public/               # Public API → /en/public/
    │   ├── openapi.yaml
    │   └── sidebars.yaml
    ├── b2b-v1/               # B2B API v1 → /en/b2b-v1/
    │   ├── openapi.yaml
    │   └── sidebars.yaml
    ├── b2b-v2/               # B2B API v2 → /en/b2b-v2/
    │   ├── openapi.yaml
    │   └── sidebars.yaml
    ├── developers/           # Developers API → /en/developers/
    │   ├── openapi.yaml
    │   └── sidebars.yaml
    └── components/           # Shared schemas, headers
        ├── headers/
        └── schemas/
```

**URL structure:**

- `/` → redirect to `/en/`
- `/en/` → landing page
- `/en/public/` → Public API docs
- `/en/b2b-v1/` → B2B v1 docs
- `/en/b2b-v2/` → B2B v2 docs
- `/en/developers/` → Developers docs


Future locales: `/pt/`, `/es/` with identical structure.

## Landing Page (`/en/index.md`)

### Hero Section

```
Altegio API
Build powerful integrations for appointment scheduling and business management.

[Get API Key]  [Quick Start →]
```

### API Cards (4 cards)

| Public API | B2B API v1 | B2B API v2 | Developers |
|  --- | --- | --- | --- |
| Online booking integration for websites & apps | Full business operations: scheduling, clients, payments, inventory | Next-gen endpoints with improved design | Marketplace apps, webhooks, integrations |


### Quick Start

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

### Use Cases

| Icon | Title | Description |
|  --- | --- | --- |
| 🗓️ | 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 |


### AI Coding Guide

**"Works great with AI assistants"**

| Method | 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 context: `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 directly: `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"
```

## API Documentation Structure

### Public API (`/en/public/`)

Tags:

- Authentication B2C
- Online Booking
- Client Personal Cabinet


### B2B API v1 (`/en/b2b-v1/`)

Groups:

- **POS & Scheduling**
  - Authentication B2B
  - Locations
  - Services
  - Team Members
  - Clients
  - Users & Permissions
  - Appointments
  - Events
  - Schedule & Resources
  - Products
  - Inventory
  - Sales
  - Payments
  - Notifications
  - Online Booking Settings
- **Administrative**
  - Analytics & Reports
  - Tags
  - Deposits
  - Loyalty Cards
  - Subscriptions & Certificates
  - Loyalty Programs
  - Salary
  - Custom Fields
  - Chain Management
  - Chain Loyalty Programs
  - Fiscalization
  - Utilities


### B2B API v2 (`/en/b2b-v2/`)

Same two groups as v1:

- **POS & Scheduling** (partially filled: positions, events)
- **Administrative** (to be expanded)


Will be populated with new documented methods over time.

### Developers API (`/en/developers/`)

Tags:

- Marketplace
- Webhooks
- VoIP Integration
- Dictionaries


## Sidebar Navigation

**Main sidebar** (`/en/sidebars.yaml`):

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

Each API documentation has its own `sidebars.yaml` with tags and endpoints.

## Migration Strategy

1. Create new directory structure under `/en/`
2. Split current `index.yaml` into 4 separate OpenAPI specs
3. Move paths, schemas, responses to respective API directories
4. Create shared `components/` for reusable schemas and headers
5. Build landing page `index.md`
6. Update `redocly.yaml` with multi-API configuration
7. Set up redirects from old URLs


## Redocly Configuration

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

redirects:
  '/':
    to: '/en/'
```