HelpU App — API / WS comercial
Única API comercial. Base: https://app.helpu.com.co/api.
PW, checkout Wompi y las apps consumen este WS. Huella/Habitta no
publican mostrador (/api/public/* ni webhook de pago).
1. Autenticación
Todos los endpoints salvo GET /api/health exigen token. El health responde servicio: helpu-ws (nombre de contrato estable).
Authorization: Bearer {HELPU_WS_TOKEN}
X-Helpu-Ws-Token: {HELPU_WS_TOKEN}Sin token → 401. Token vacío en el servidor → 503.
2. Catálogo
| Método | Ruta | Uso |
|---|---|---|
| GET | /api/health | Salud del servicio (sin token) |
| GET | /api/planes?producto=huella|habitta&tipo=plataforma|asamblea | Planes y tarifas |
| GET | /api/cotizar?producto=&plan=&alumnos|unidades=&periodo= | Cotización |
Fuente de verdad de precios: App (planes.valor_unitario). Sin WS las apps no cotizan.
3. Mostrador (escribe BD de producto)
| Método | Ruta | Uso |
|---|---|---|
| GET | /api/temas?producto= | Temas visuales |
| GET | /api/ciudades?producto= | Ciudades |
| GET | /api/municipios?producto=&ciudad_id= | Municipios |
| GET | /api/empresas/consulta?producto=&nit=&email= | ¿Existe el NIT? Incluye tiene_plan_pago, puede_comprar_packs_multi, plataforma_vigente, metrica_usada, tope_self_service, requiere_cotizacion_por_uso, metrica_minima_pago (Habitta unidades / Huella alumnos). |
| POST | /api/empresas | Alta comercial (colegio o conjunto) |
| POST | /api/demos | Solicitud demo (desde /registro Huella o Habitta) |
| POST | /api/pagos/confirmar | Confirmar Wompi (plan o plan asamblea). Plan asamblea > 1 sin plan de pago vigente → 422; plan de 1 sin plataforma usable → asigna demo + plan asamblea. |
/api/public/* de Huella/Habitta.
App usa las conexiones PostgreSQL de cada producto.
Correos gestora (demo recibida, acceso admin al aprobar/pagar) salen desde App.
El formulario /registro de VitrinaApp (y Huella/Habitta) llama POST /api/demos.
4. PQRS
4.1 HelpU (soporte comercial)
Auth: HELPU_WS_TOKEN. Datos en BD de App.
| Método | Ruta | Uso |
|---|---|---|
| POST | /api/pqrs | Alta. canal=web (PW) marca origen Sitio web; si no, WS. |
| GET | /api/pqrs?email= o ?pqrs_id= | DTO público. No usar en la web abierta (el token listaría por correo). |
201: { ok, pqrs_id, estado }. Historial y correos al pasar a En proceso/Cerrado.
4.2 Habitta (conjunto — web externa del cliente)
Auth: Basic Auth Admin del conjunto + plan pqrs_web (o portal.pqrs). Escribe en bd_habitta. No usa HELPU_WS_TOKEN.
| Método | Ruta | Uso |
|---|---|---|
| GET | /api/habitta/unidades?tipo=A|C | Listado de apartamentos (A) o casas (C). |
| POST | /api/habitta/pqrs | Alta PQRS del conjunto (asunto, descripcion, tipo, id). |
4.3 Huella (colegio — web externa del cliente)
Auth: Basic Auth Admin del colegio + módulo PQRS (rrhh.pqrs). Escribe en bd_huella.
| Método | Ruta | Uso |
|---|---|---|
| POST | /api/huella/pqrs | Alta PQRS del colegio (asunto, descripcion, persona_id del estudiante; opcional categoria, area). |
5. Facturación electrónica
Prefijo /api/fe/: probar, opciones, emitir, consultar, pdf, xml, reenviar-email.
Credenciales viajan en cada body. Factus emitir = POST /v2/bills/validate.
Referencias estables: HUE{empresa}-{dc}, HAB{empresa}-{dc}, HEL-{dc}.
6. Productos Huella / Habitta / Vitrina
routes/api.php vacío en productos. No publican WS de mostrador: HelpU App escribe en las BD de producto (o API interna en Vitrina).
Manuales: Huella · Habitta · Vitrina (integración).
7. Vitrina
Definición completa: pw/docs/vitrina/ · API interna VitrinaApp.
| Método | Ruta WS HelpU App | Uso |
|---|---|---|
| GET | /api/planes?producto=vitrina | Catálogo Starter / Pro / Demo |
| GET | /api/cotizar?producto=vitrina&plan=&productos=&periodo= | Cotización por productos activos |
| GET | /api/empresas/consulta?producto=vitrina&nit= | Cliente existente |
| POST | /api/empresas (producto=vitrina) | Alta + provisionar tenant inactivo |
| POST | /api/demos (producto=vitrina) | Solicitud demo |
| POST | /api/pagos/confirmar | Activar plan tras Wompi |
API interna VitrinaApp (mismo HELPU_WS_TOKEN):
| Método | Ruta VitrinaApp | Uso |
|---|---|---|
| GET | /api/internal/tenants | Listado SuperAdmin |
| POST | /api/internal/tenants | Alta tenant (demo=true opcional) |
| PUT | /api/internal/tenants/{id} | Activar, suspender, plan |
| POST | /api/internal/tenants/procesar-vencimientos | Cron vencimientos |
Detalle: pw/docs/vitrina/ws.php.