API REST — Integración de suscripciones

1. Introducción

Huella expone una API REST para que la página web comercial (checkout de planes) sincronice pagos de suscripción con el panel multi-tenant de colegios. La pasarela de pago vive en la web; Huella no aloja el formulario de cobro, solo recibe la confirmación del pago exitoso.

Para operación del panel (empresas, demos, avisos) consulte el manual de SuperAdmin. Para el colegio (configuración, académico, RRHH, finanzas), use el manual de usuario.

2. Autenticación

Todos los endpoints requieren un token compartido configurado en el servidor Huella (HUELLA_API_TOKEN).

Respuestas de autenticación:

3. URL base y convenciones

• Prefijo: todas las rutas están bajo /api.
• Formato: JSON en peticiones (Content-Type: application/json) y respuestas.
• Fechas: formato Y-m-d (ej. 2026-07-05).
• Moneda: valores numéricos en COP sin separadores.
• NIT: 9 dígitos sin dígito de verificación ni guión.

Ejemplo de URL base en producción (ajuste en config.php de esta carpeta):

https://huella.su-dominio.com/api

4. Listar planes

GET /api/public/planes

Devuelve el catálogo activo para la web comercial (Demo, Básico, Profesional). El query tipo acepta plataforma o app (mismo resultado; default plataforma).

Parámetros (query string)

Respuesta 200

{
  "ok": true,
  "tipo": "plataforma",
  "planes": [
    {
      "plan_id": 2,
      "codigo": "basico",
      "nombre": "Básico",
      "tipo": "plataforma",
      "dias_aviso": 7,
      "activo": true,
      "es_demo": false,
      "capacidades": ["Estudiantes", "Calificaciones", "Boletines"],
      "tarifas": [
        {
          "rango_alumnos_id": 1,
          "etiqueta": "Hasta 50 alumnos",
          "alumnos_desde": 1,
          "alumnos_hasta": 50,
          "requiere_cotizacion": false,
          "precio_mensual": 80000,
          "precio_mensual_fmt": "$80.000"
        }
      ],
      "periodos": [
        {
          "periodo_facturacion_id": 1,
          "codigo": "mensual",
          "nombre": "Mensual",
          "meses": 1,
          "descuento_pct": 0
        }
      ]
    }
  ]
}

capacidades son nombres legibles de módulos incluidos. Tarifas por rango de alumnos y periodos de facturación (mensual, trimestral, semestral, anual). Detalle operativo: manual SuperAdmin.

5. Cotizar plan

GET /api/public/cotizar

Calcula el precio del periodo según plan, cantidad de alumnos y periodo de facturación.

Parámetros

Respuesta 200: { "ok": true, "cotizacion": { ... } }. Si el rango exige cotización personalizada, cotizacion.ok es false y requiere_cotizacion es true.

6. Listar temas

GET /api/public/temas

Temas visuales disponibles para registro o selección en la web comercial. El tag se usa en login: /login?tag=….

Respuesta 200 (extracto)

{
  "ok": true,
  "temas": {
    "default": {
      "id": 1,
      "show_name": "Predeterminado",
      "primary": "#1B4F8A",
      "tag": "baDZr8M69O"
    },
    "red": { "id": 2, "show_name": "Rojo", "tag": "8XmnVjnR1L" }
  }
}

7. Listar ciudades

GET /api/public/ciudades

{
  "ok": true,
  "ciudades": [
    { "ciudad_id": 1, "nombre": "Cundinamarca" }
  ]
}

8. Listar municipios

GET /api/public/municipios?ciudad_id=1

El municipio_id se usa en POST /public/empresas.

{
  "ok": true,
  "ciudad_id": 1,
  "municipios": [
    {
      "municipio_id": 912,
      "ciudad_id": 1,
      "nombre": "Soacha",
      "codigo_dane": "25754"
    }
  ]
}

9. Consultar empresa (colegio)

GET /api/public/empresas/consulta

Valida si existe un colegio cliente antes del pago. Indique nit y/o email.

Respuesta 200

{
  "ok": true,
  "existe": true,
  "activo": true,
  "empresa": {
    "empresa_id": 12,
    "nombre": "Colegio Ejemplo",
    "nit": "900123456",
    "email": "admin@colegio.edu.co",
    "activo": true,
    "plan_actual": "basico",
    "plan_nombre": "Básico",
    "plan_vence": "2026-08-04",
    "es_demo": false,
    "dias_restantes": 20,
    "estado_suscripcion": "al_dia"
  }
}

Si no existe: existe: false, empresa: null (HTTP 200). Estados: al_dia, proximo_vencer, vencido. No se expone la empresa gestora.

10. Alta comercial (sin demo)

POST /api/public/empresas

Crea un colegio con su administrador sin plan demo. Queda activo: false hasta el webhook de pago.

Cuerpo JSON

Ejemplo

{
  "nit": "900999888",
  "nombre": "Colegio Los Álamos",
  "direccion": "Calle 10 # 20-30",
  "barrio": "Centro",
  "telefono": "3001234567",
  "email": "admin@losalamos.edu.co",
  "municipio_id": 912,
  "tema_id": 1
}

11. Confirmar pago de suscripción

POST /api/webhooks/suscripcion/pago

Llame este endpoint después de que la pasarela confirme el cobro. Huella registra el pago, renueva la suscripción y, por defecto, activa el colegio si estaba inactivo.

Cuerpo JSON

Ejemplo

{
  "referencia": "TX-98437261",
  "nit": "900123456",
  "plan_codigo": "basico",
  "alumnos": 50,
  "periodo_codigo": "mensual",
  "valor": 80000,
  "pasarela": "WOMPI",
  "activar_empresa": true,
  "reset_datos_demo": false
}

Respuesta 201 (pago nuevo) o 200 si idempotente: true (misma referencia ya procesada).

12. Códigos de error

13. Idempotencia y referencias

Huella antepone un prefijo a la referencia de la pasarela. Formato: WEB[-PASARELA]-referencia. Variable: HUELLA_PAGO_PREFIJO (default WEB).

14. Flujo recomendado (web comercial)

Cliente nuevo que paga (sin demo)

1. Planes y cotización: GET /planes, GET /cotizar, temas y municipios.
2. Registrar colegio: POST /empresas → empresa_id.
3. Cobrar en la pasarela con el monto cotizado.
4. Confirmar: POST /webhooks/suscripcion/pago con plan, alumnos, periodo y activar_empresa: true.
5. Login: correo de la empresa y clave = NIT (9 dígitos).

Cliente existente / demo

1. GET /empresas/consulta (NIT o correo).
2. Checkout Help U → cobro → POST /webhooks/suscripcion/pago (opcional reset_datos_demo: true).

Las solicitudes de demo desde /registro crean colegios inactivos con plan demo; se activan con este webhook o desde el panel (ver bandeja de demos).

15. Configuración en Huella

Variables en el .env del servidor Huella: