Skip to content
Last updated

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 APIB2B API v1B2B API v2Developers
Online booking integration for websites & appsFull business operations: scheduling, clients, payments, inventoryNext-gen endpoints with improved designMarketplace apps, webhooks, integrations

Quick Start

# 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

IconTitleDescription
🗓️Booking WidgetEmbed scheduling into websites, mobile apps, or kiosks
🤖AI Assistants & ChatbotsLet GPT, Claude or custom bots book appointments via API
📊Analytics DashboardBuild custom reports, BI integrations, data warehouses
🔄CRM SyncTwo-way sync with Salesforce, HubSpot, custom CRMs
📱White-label AppsBuild branded booking apps for your clients
💳POS IntegrationConnect payments, receipts, fiscal printers
📦Inventory AutomationSync stock levels with suppliers, e-commerce
🔔Custom NotificationsWebhooks for real-time events, custom messaging

AI Coding Guide

"Works great with AI assistants"

MethodHow to use
Claude / ChatGPTCopy the OpenAPI spec URL and paste into chat: "Use this API spec to build a booking integration"
Cursor / CopilotAdd spec to project context: curl -o altegio-api.yaml https://developer.alteg.io/en/b2b-v1/openapi.yaml
Claude CodePoint to docs: "Read https://developer.alteg.io/en/public/ and implement appointment booking"
MCP ServerConnect 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

Main sidebar (/en/sidebars.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

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/'