Superadmin Operations Guide

Superadmin Operations Guide

Guía en español: Guía de Superadmin — documentación para usuarios no técnicos.

This guide covers day-to-day superadmin tasks. All operations require the X-Admin-Key header.

---

Accessing the Superadmin API

All superadmin endpoints are at /api/superadmin/. Include the key in every request:

curl -H "X-Admin-Key: {SUPER_ADMIN_KEY}" https://api.clinicflow.lat/api/superadmin/stats

Caution

The value is the SUPER_ADMIN_KEY environment variable. Store it securely — anyone with this key has full control over all clinics.

Also accessible from the dashboard at /superadmin (UI with the same capabilities).

---

Accepting Demo Requests

When a potential customer fills the landing page form, a demo request is created with status pending.

View pending requests:

curl -H "X-Admin-Key: {KEY}" \
  "https://api.clinicflow.lat/api/superadmin/demo-requests?status=pending"

Accept and generate invite code:

curl -X POST \
  -H "X-Admin-Key: {KEY}" \
  -H "Content-Type: application/json" \
  -d '{"expiresInDays": 7}' \
  "https://api.clinicflow.lat/api/superadmin/demo-requests/{id}/accept"

Returns: { "inviteCode": "ABC123DEF456" } — send this to the clinic owner.

Reject a request:

curl -X POST \
  -H "X-Admin-Key: {KEY}" \
  "https://api.clinicflow.lat/api/superadmin/demo-requests/{id}/reject"

---

Crear Códigos de Invitación Manualmente

Para crear un código sin una solicitud de demo:

curl -X POST \
  -H "X-Admin-Key: {KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "pro",
    "expiresInDays": 30,
    "email": "clinica@email.com",
    "notes": "Código para Clínica Ejemplo"
  }' \
  "https://api.clinicflow.lat/api/superadmin/invite-codes"

Si se incluye email, solo ese correo puede usar el código. Sin email, cualquiera puede usarlo.

Para acceso permanente (Forever Free):

-d '{"plan": "forever_free", "notes": "Cliente beta"}'

---

Managing Clinic Plans

Extend a trial or upgrade a plan:

curl -X PATCH \
  -H "X-Admin-Key: {KEY}" \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro", "expiresInDays": 365}' \
  "https://api.clinicflow.lat/api/superadmin/clinics/{clinicId}"

Grant Forever Free status:

-d '{"plan": "forever_free"}'

Suspend a clinic:

-d '{"is_active": false}'

Reactivate a clinic:

-d '{"is_active": true}'

---

Revocar un Código No Usado

curl -X PATCH \
  -H "X-Admin-Key: {KEY}" \
  "https://api.clinicflow.lat/api/superadmin/invite-codes/{id}/revoke"

Solo funciona si el código no ha sido usado. Los códigos ya usados no se pueden revocar (la clínica ya fue creada).

---

Ver Estadísticas Globales

curl -H "X-Admin-Key: {KEY}" \
  "https://api.clinicflow.lat/api/superadmin/stats"

Returns: total clinics, active clinics, pending demo requests, today’s appointments across all clinics, revenue this month, plan distribution.

---

Bull Board (Job Queue Dashboard)

Monitor background jobs (appointment reminders, daily agendas):

URL: https://api.clinicflow.lat/admin/queues
Auth: HTTP Basic Auth (QUEUES_ADMIN_USER / QUEUES_ADMIN_PASS)

Retry a Failed Job

1. Open Bull Board
2. Find the failed job in appointment-reminders or daily-agenda queue
3. Click the job → Retry

Common Failure Causes

Failure	Cause	Fix
WhatsApp 4xx	Token expired	Update WhatsApp token in clinic settings
WhatsApp 401	Phone number deregistered	Clinic must re-setup WhatsApp
Appointment not found	Appointment was deleted	Safe to ignore — job will fail permanently
Redis timeout	Redis rate limit	Check Railway dashboard, upgrade Redis plan if needed

---

Dashboard Superadmin UI

The dashboard has a superadmin section at /superadmin (requires SUPER_ADMIN_KEY to log in). It provides a UI for:

• Viewing and acting on demo requests
• Managing invite codes
• Viewing clinic list and updating plans
• Global statistics

For complex operations or bulk updates, use the API directly.