08 — Endpoints API¶

Convenciones generales¶

Base URL: https://app.tudominio.com (dashboard) y https://widget.tudominio.com (widget). Ambas resuelven al mismo backend Django.
Formato: JSON request/response. Content-Type: application/json.
Auth: la mayoría requieren Authorization: Bearer <ACCESS_TOKEN>. Los endpoints públicos del widget NO.
Errores: DRF estándar, {"detail": "..."} con HTTP status apropiado.
Trailing slash: Django impone / al final salvo en widget (/v3/health, /v3/faq, /v3/frontend/config aceptan ambos).

Mapa por capas¶

Prefijo	Auth	Quién lo usa
`/health`, `/api/health/`	❌	Load balancer / monitoring
`/v3/*`	❌	Widget embebido (público, lectura)
`/api/auth/*`	❌ (excepto profile)	Páginas de login/registro
`/api/dashboard/*`	✅ JWT	Frontend del dashboard cliente
`/api/account/*`	✅ JWT	Gestión de la cuenta del comprador
`/api/accounts/*`	✅ JWT	Idem (alias flatten para compatibilidad)
`/api/billing/stripe/webhook/`	❌ (firma Stripe)	Stripe
`/api/sa/*`	✅ JWT (rol superadmin)	Frontend `apps/superadmin`
`/admin/`	✅ session Django	Operación low-level (DBA/dev)

Widget público (`/v3/*`)¶

Todos sin auth. El tenant se identifica con header X-Client-ID: <bot_slug> o query ?tenant=<bot_slug>.

Método	Endpoint	Descripción
GET	`/v3/health`	Liveness probe del servicio del widget
GET	`/v3/frontend/config`	`ui_config` (colores, logo, idiomas) + `content` (texts, navItems, supported_languages)
GET	`/v3/faq?language=<lang>&category=<opcional>`	FAQs agrupadas por categoría

Detalle completo del contrato en 13-widget-embebido.md.

Autenticación (`/api/auth/*`)¶

Método	Endpoint	Auth	Descripción
POST	`/api/auth/register/`	❌	Registro legacy (email + password)
POST	`/api/auth/signup/`	❌	Registro moderno (con verificación email obligatoria)
POST	`/api/auth/login/`	❌	Login con email/password, devuelve par JWT
POST	`/api/auth/token/`	❌	Idem login (compat SimpleJWT)
POST	`/api/auth/token/refresh/`	❌	Refresca el access token
POST	`/api/auth/logout/`	✅	Blacklist del refresh token
POST	`/api/auth/verify-email/`	❌	Verifica email con token
POST	`/api/auth/resend-verification/`	❌	Reenvía email de verificación
POST	`/api/auth/password-reset-request/`	❌	Envía email de reset
POST	`/api/auth/password-reset-confirm/`	❌	Confirma reset con token
GET, PATCH	`/api/auth/profile/`	✅	Perfil del usuario logueado
POST	`/api/auth/change-password/`	✅	Cambia password (requiere current)
PATCH	`/api/auth/update-my-email/`	✅	Cambia email (envía verificación al nuevo)
POST	`/api/auth/social/`	❌	Login con OAuth (Google)
GET	`/api/auth/social/links/`	✅	Lista providers OAuth conectados
DELETE	`/api/auth/social/unlink/<provider>/`	✅	Desconecta un provider
POST	`/api/auth/invitation-request/`	❌	Solicita invitación (modo prelaunch)
GET	`/api/auth/prelaunch-status/`	❌	¿Está activo el modo prelaunch?

Detalle de flujos en 09-autenticacion.md.

Dashboard cliente (`/api/dashboard/*`)¶

Todos requieren JWT del usuario logueado.

Bots¶

Método	Endpoint	Descripción
GET	`/api/dashboard/bots/`	Lista de bots del usuario (filtrados por permisos)
GET	`/api/dashboard/bots/<bot_id>/`	Detalle de un bot
POST	`/api/dashboard/bots/`	Crear nuevo bot
PATCH	`/api/dashboard/bots/<bot_id>/`	Editar bot (branding, dominio, etc.)
DELETE	`/api/dashboard/bots/<bot_id>/`	Soft-delete (status='deleted')
POST	`/api/dashboard/bots/<bot_id>/plan-select/`	Cambia el plan
GET	`/api/dashboard/bots/<bot_slug>/embed/`	Devuelve el `<script>` que el cliente pega en su web. Body en sección Embed snippet
GET	`/api/dashboard/stats/?bot_id=<bot_slug>`	KPIs del Help Center del bot (FAQs por idioma, idiomas activos, limits del plan, branding). Sin `bot_id` devuelve el primer bot de la cuenta. Body en sección Stats response

Método	Endpoint	Descripción
GET	`/api/dashboard/bots/<bot_id>/config/`	`ui_config` + `content` actual
PATCH	`/api/dashboard/bots/<bot_id>/config/`	Actualiza colores, logo, idiomas
POST	`/api/dashboard/bots/<bot_id>/config/logo/`	Sube logo (multipart)
POST	`/api/dashboard/bots/<bot_id>/config/avatar/`	Sube avatar

FAQs¶

Método	Endpoint	Descripción
GET	`/api/dashboard/bots/<bot_id>/faqs/`	Lista FAQs (filtrar por `?lang=` y `?category=`)
POST	`/api/dashboard/bots/<bot_id>/faqs/`	Crea una FAQ
PATCH	`/api/dashboard/bots/<bot_id>/faqs/<id>/`	Edita FAQ
DELETE	`/api/dashboard/bots/<bot_id>/faqs/<id>/`	Borra FAQ
POST	`/api/dashboard/bots/<bot_id>/faqs/import`	Importa FAQs desde CSV/JSON
DELETE	`/api/dashboard/bots/<bot_id>/faqs/clear-all`	Borra todas las FAQs (con confirmación)

Categorías¶

Método	Endpoint	Descripción
GET	`/api/dashboard/bots/<bot_id>/categories/`	Lista categorías
POST	`/api/dashboard/bots/<bot_id>/categories/`	Crea categoría (con translations)
PATCH	`/api/dashboard/bots/<bot_id>/categories/`	Renombra/traduce
DELETE	`/api/dashboard/bots/<bot_id>/categories/`	Borra (mueve FAQs a sin categoría)

Billing (cliente)¶

Método	Endpoint	Descripción
GET	`/api/dashboard/plans/`	Lista pública de planes activos
GET	`/api/dashboard/subscriptions/`	Suscripciones del usuario
GET	`/api/dashboard/subscriptions/<id>/`	Detalle de una suscripción
POST	`/api/dashboard/billing/checkout/`	Crea Stripe Checkout Session
POST	`/api/dashboard/billing/portal/`	Crea Stripe Billing Portal Session
GET	`/api/dashboard/invoices/`	Lista de facturas del usuario
GET	`/api/dashboard/invoices/<id>/pdf/`	Descarga PDF de factura

Onboarding¶

Método	Endpoint	Descripción
POST	`/api/dashboard/onboarding/intents/reserve/`	Reserva un intent (slug + plan + email)
POST	`/api/dashboard/onboarding/intents/<intent_id>/checkout/`	Inicia checkout
GET	`/api/dashboard/onboarding/intents/<intent_id>/`	Estado del intent
POST	`/api/dashboard/onboarding/intents/<intent_id>/finalize/`	Crea bot + Account tras pago OK

Bot users (invitados)¶

Método	Endpoint	Descripción
GET	`/api/dashboard/bot-users/`	Lista usuarios invitados a los bots del owner
POST	`/api/dashboard/bot-users/invite/`	Invita por email con permisos granulares
PATCH	`/api/dashboard/bot-users/<id>/`	Edita permisos
DELETE	`/api/dashboard/bot-users/<id>/`	Revoca acceso

Perfil¶

Método	Endpoint	Descripción
GET, PATCH	`/api/dashboard/profile/me/`	Perfil del usuario logueado (alias de `/api/auth/profile/`)
GET	`/api/dashboard/profiles/`	Templates de configuración inicial de bot

Account¶

Método	Endpoint	Descripción
GET	`/api/account/` o `/api/accounts/me/`	Info de la cuenta del usuario
PATCH	`/api/accounts/<uuid>/`	Edita la cuenta
POST	`/api/account/email-verification/request/`	Solicita verificación del email de la cuenta
POST	`/api/account/email-verification/confirm/`	Confirma con token
PATCH	`/api/account/update-email/`	Cambia email de la cuenta
POST	`/api/account/close/`	Cierra la cuenta (soft-delete)
POST	`/api/account/cancel-close/`	Cancela el cierre dentro del período de gracia

Stripe webhook (`/api/billing/stripe/webhook/`)¶

Método	Endpoint	Auth	Descripción
POST	`/api/billing/stripe/webhook/`	Firma Stripe (`Stripe-Signature` header)	Sincroniza eventos: subscription.created/updated/deleted, invoice.payment_succeeded/failed, checkout.session.completed

Más detalle en 10-billing-stripe.md.

Superadmin (`/api/sa/*`)¶

Todos requieren JWT del rol superadmin. Lo usa el frontend apps/superadmin.

Tenants (Accounts + Bots)¶

Método	Endpoint	Descripción
GET	`/api/sa/tenants/`	Lista todos los bots de la plataforma
GET	`/api/sa/tenants/<bot_id>/`	Detalle de un bot (KPIs, suscripción, propietario)
POST	`/api/sa/tenants/<bot_id>/promote/`	Promueve a "verified" tras revisión de PII
GET	`/api/sa/accounts/`	Lista todas las accounts
GET	`/api/sa/accounts/<id>/`	Detalle de account
GET	`/api/sa/accounts/<id>/bots/`	Bots de esa account

Plans (catálogo editable)¶

Método	Endpoint	Descripción
GET	`/api/sa/plans/`	Lista todos los planes
POST	`/api/sa/plans/`	Crea plan (sincroniza con Stripe si tiene `stripe_price_id`)
PATCH	`/api/sa/plans/<id>/`	Edita features, precio, traducciones
DELETE	`/api/sa/plans/<id>/`	Desactiva plan (no borra; pone `is_active=False`)

Users¶

Método	Endpoint	Descripción
GET	`/api/sa/users/`	Lista todos los usuarios SaaS
POST	`/api/sa/admin-users/`	Crea otro superadmin
GET	`/api/sa/users/<id>/`	Detalle
PATCH	`/api/sa/users/<id>/`	Activa/desactiva, cambia rol

Invoices¶

Método	Endpoint	Descripción
GET	`/api/sa/invoices/`	Lista todas las facturas (paginado)
GET	`/api/sa/invoices/<id>/`	Detalle

Analytics¶

Método	Endpoint	Descripción
GET	`/api/sa/analytics/overview/`	KPIs globales: MRR, accounts activas, bots, churn
GET	`/api/sa/analytics/by-plan/`	Distribución por plan
GET	`/api/sa/activity-feed/`	Feed cronológico de eventos importantes

Invitations / Pre-launch¶

Método	Endpoint	Descripción
GET	`/api/sa/invitation-requests/`	Solicitudes pendientes
POST	`/api/sa/invitation-requests/<pk>/action/`	Aprueba/rechaza
POST	`/api/sa/prelaunch-mode/`	Activa/desactiva el modo prelaunch
GET	`/api/sa/prelaunch-codes/`	Lista códigos de prelaunch generados

Catálogos auxiliares¶

Método	Endpoint	Descripción
GET, POST, PATCH, DELETE	`/api/sa/business-categories/`	Industrias
GET, POST, PATCH, DELETE	`/api/sa/business-types/`	Tipos de negocio

Health endpoints¶

Método	Endpoint	Auth	Descripción
GET	`/health`	❌	Lightweight: status DB
GET	`/health/`	❌	Idem (con slash)
GET	`/api/health/`	❌	Idem
GET	`/v3/health`	❌	Health del widget service

Respuesta:

{ "status": "ok", "db": true }

Response shapes que el frontend depende de¶

Stats response¶

GET /api/dashboard/stats/?bot_id=<bot_slug> devuelve:

{
  "bot_slug": "acme",
  "bot_name": "ACME Help Center",
  "plan": {
    "name": "Starter",
    "display_name": "Starter",
    "price": 19,
    "tier": "starter"
  },
  "usage": {
    "faqs_total": 87,
    "faqs_per_language": { "es": 45, "en": 42 },
    "languages_active": 2,
    "primary_language": "es"
  },
  "limits": {
    "faqs_per_language": 100,
    "languages": 2,
    "bots": 1,
    "branding": true
  },
  "account": {
    "id": "8f7c…-uuid",
    "bots_count": 1
  },
  "scope": "bot",
  "bot_id_filter": "acme"
}

usage.faqs_per_language cuenta solo las FAQs is_active=true.
usage.languages_active cuenta los idiomas con al menos una FAQ activa.
limits.faqs_per_language=null significa "ilimitado" (no se usa en los planes actuales).
limits.branding=false quiere decir "el comprador puede ocultar el footer Powered by".
Si la cuenta no tiene bots, el endpoint devuelve usage.faqs_total=0, limits del plan más barato y bot_slug=null. El frontend usa esto para renderizar el estado "crea tu primer bot".

Embed snippet¶

GET /api/dashboard/bots/<bot_slug>/embed/ devuelve:

{
  "bot_id": "acme",
  "tenant_slug": "acme",
  "companyName": "ACME Help Center",
  "snippet": "<!-- BlimX Chatbot -->\n<script>window.blimxTenant = \"acme\";</script>\n<script defer src=\"https://widget.tu-dominio.com/static/v3/blimx-v3-chatbot-loader.js\"\n        data-bot-id=\"acme\"\n        data-frame=\"https://widget.tu-dominio.com/static/v3/blimx-v3-chatbot-frame.html\"></script>"
}

El host del snippet (widget.tu-dominio.com) se toma de la variable de entorno EMBED_BASE_HOST. Si no está, default https://superbot.pocololo.com (entorno demo).
El campo bot_id se llama así por compatibilidad con el frontend viejo; siempre contiene el slug, no el UUID.
403 con {"error":"website_channel_not_enabled","channel":"website"} si el bot tiene el canal website deshabilitado en su config.

Endpoints eliminados intencionalmente¶

Por si te suena alguno y no lo encuentras:

❌ /v3/chat, /v3/chat-stream — no hay chat IA
❌ /v3/lead-capture — no hay leads
❌ /v3/upload — el widget no recibe archivos del visitante
❌ /api/integrations/webhook/lead — eliminado
❌ /api/dashboard/flows/, /api/dashboard/shop/ — eliminados
❌ /api/sa/tenants/<id>/flows/ — eliminado (no hay flow editor)
❌ /api/sa/tenants/<id>/creation-stats/ — eliminado (no hay bot_jobs)
❌ /api/dashboard/profile/sessions/ — eliminado (revocación vía token_version + JWT blacklist)
❌ /api/internal/lead-capture-email/, /api/internal/booking-email/ — eliminados

Si necesitas alguna de estas funcionalidades, hay que volver a implementarla. El framework lo permite, pero no viene incluida.