Skip to main content

​
Quickstart Guide

Get the WispHub API running locally in just a few steps. This guide will have you making your first API request in under 5 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Docker installed on your system
  • A WispHub Net API key
  • Basic familiarity with REST APIs

​
Step 1: Configure Environment Variables

Create a .env file in your project root with your WispHub credentials:
.env
# WispHub Net (required)
WISPHUB_NET_KEY=your_api_key_here
WISPHUB_NET_HOST=https://api.wisphub.net

# JWT Authentication (required)
JWT_SECRET_KEY=your_very_long_random_secret_here
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60

API_USERNAME=admin
API_PASSWORD_HASH=$2b$12$... # bcrypt hash of your password

# Business rules (optional)
MAX_ACTIVE_TICKETS_PER_ZONE=3
Never commit your .env file to version control. Add it to your .gitignore file.
Generate a secure JWT_SECRET_KEY with: openssl rand -hex 32Generate the bcrypt hash of your password with Python:
from passlib.context import CryptContext
ctx = CryptContext(schemes=["bcrypt"], deprecated="auto")
print(ctx.hash("your_password"))

​
Step 2: Build the Docker Image

Clone the repository and build the Docker image: 
git clone https://github.com/soporte-ainovapro/wisphub-api.git
cd wisphub-api
docker build -t wisphubapi:latest .
The build process will:
  • Use Python 3.12-slim base image
  • Install all dependencies from requirements.txt
  • Create a non-root user for security
  • Configure health checks

​
Step 3: Run the Container

Start the API server using Docker: 
docker run -d \
  --name wisphub_api_server \
  -p 8000:8000 \
  --env-file .env \
  wisphubapi:latest
The API will be available at http://localhost:8000
The container runs Gunicorn with 4 Uvicorn workers by default, providing async request handling and automatic worker restart on failures.

​
Step 4: Verify Installation

Test the health check endpoint to confirm the API is running: 
curl http://localhost:8000/health
Expected response: 
{
  "success": true,
  "action": null,
  "message": null,
  "data": {
    "status": "ok",
    "service": "WispHub Local API"
  }
}

​
Step 5: Explore the API

Visit the interactive API documentation to explore all available endpoints: 
http://localhost:8000/docs
The Swagger UI provides:
  • Complete endpoint documentation
  • Request/response schemas
  • Interactive API testing
  • Authentication configuration

​
Make Your First Request

​
Step 1: Obtain a JWT Token

All API endpoints (except /health) require a JWT Bearer token. Obtain one first: 
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=your_password" \
  | jq -r '.access_token')

echo "Token: $TOKEN"

​
Step 2: Call a Protected Endpoint

Use the token in the Authorization header: 
curl http://localhost:8000/api/v1/clients/ \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "type": "success",
  "action": "CLIENTS_LISTED",
  "message": null,
  "data": [
    {
      "service_id": 123,
      "name": "John Doe",
      "document": "1234567890",
      "phone": "3001234567",
      "address": "Calle Principal 123",
      "zone_id": 1,
      "internet_plan_name": "Plan Básico 10MB",
      "internet_plan_price": 35000.0,
      "status": "active"
    }
  ]
}

​
Next Steps

Now that you have the API running, explore these topics:

Architecture

Learn about the caching system and middleware design

API Reference

Explore all available endpoints and schemas

Authentication

Understand API key configuration and security

Deployment

Deploy to production with advanced Docker configurations

​
Common Issues

Change the host port mapping:
docker run -d --name wisphub_api_server -p 8001:8000 --env-file .env wisphubapi:latest
Access the API at http://localhost:8001
Check the logs:
docker logs wisphub_api_server
Common causes:
  • Missing or invalid environment variables
  • Port conflicts
  • Insufficient Docker resources
There are two possible causes:
  • 401 from the API itself: Your JWT token is missing, expired, or invalid. Obtain a new one with POST /api/v1/auth/token.
  • Error communicating with WispHub Net: Verify your WISPHUB_NET_KEY in the .env file is correct and has the necessary permissions.

​
Development Mode

For local development with hot-reload, see the Local Development guide.