ComProPass API

API pública de ComProPass para acceder a la base de conocimiento, gestión de pacientes y eventos. Diseñada para integrarse con sistemas externos, agentes de IA y plataformas de soporte.

URLs base

Todas las rutas documentadas aquí son relativas a la URL base. Actualmente servidas desde compropass.app/v1.

Autenticación

Los endpoints públicos (audience=public) no requieren autenticación. El resto requiere tres headers con las credenciales del tenant.

Obtén tus credenciales en el portal: Configuración → API & Webhooks.

Excepción — API de lealtad (lealtadApi): su credencial no sale del portal. La emite el equipo de ComPro y se entrega al integrador junto con los tres valores (x-compro-key, x-client-id, x-tenant-id); además usa su propia URL base, distinta de compropass.app/v1 (ver la sección de lealtad).

Códigos de error

Acceso a los artículos de soporte de ComProPass. Útil para agentes de IA, chatbots y sistemas de soporte que necesitan responder preguntas de usuarios.

Registra asistencia/acceso sin persona detrás — un torniquete, un lector de garita o el sistema de un cliente, por credencial de tenant (x-compro-key / x-client-id / x-tenant-id, ver Autenticación). Vive en hrApi, no bajo /v1 — base https://us-central1-compro-saas-core.cloudfunctions.net/hrApi.

Es registro operativo de acceso, no control de nómina: el producto registra quién pasó y cuándo; el cálculo de horas y turnos es del sistema del cliente. Hay que habilitarlo por programa desde ComPro antes de usarlo — ver el código MARCAJE_NO_HABILITADO más abajo.

Campos opcionales del body (los dos endpoints POST — en /scans, uno por fila):

Ejemplo — un marcaje:

curl -X POST https://us-central1-compro-saas-core.cloudfunctions.net/hrApi/employees/EMP001/scan \
  -H "x-compro-key: {api_key}" -H "x-client-id: {client_id}" -H "x-tenant-id: {tenant_id}" \
  -H "Content-Type: application/json" -d '{"type":"attendance"}'

{ "success": true, "scan_id": "…", "verdict": "allowed",
  "person": { "person_code": "EMP001", "name": "María García" } }

Códigos propios de esta sección:

Para comercios que ya tienen su propio motor de lealtad (acumulación, canje, reglas de negocio) y solo necesitan la capa de wallet + notificación de ComProPass. Credencial de tenant (x-compro-key / x-client-id / x-tenant-id, ver Autenticación). Vive en lealtadApi, no bajo /v1 — base https://us-central1-compro-saas-core.cloudfunctions.net/lealtadApi.

Pass-through, no motor de lealtad: ComProPass refleja el saldo que tu sistema le manda — sin anti-fraude, sin techos, sin lógica de acumulación propia. Tenés que traer vos el saldo ya calculado. Hay que habilitarlo por programa desde ComPro antes de usarlo (credencial + api_access del plan) — ver el código API_NO_HABILITADA más abajo.

Flujo de integración recomendado:

Campos del body (alta — POST /members y cada fila de /members/batch):

Base y credenciales de esta API:

Ejemplo — alta y actualización de saldo:

curl -X POST https://us-central1-compro-saas-core.cloudfunctions.net/lealtadApi/members \
  -H "x-compro-key: {api_key}" -H "x-client-id: {client_id}" -H "x-tenant-id: {tenant_id}" \
  -H "Content-Type: application/json" \
  -d '{"member_id":"CF1234567","name":"María García","balance":150}'

{ "success": true, "created": true,
  "data": { "id": "…", "member_id": "CF1234567", "name": "María García",
    "balance": 150, "status": "active",
    "apple_pass_url": "https://…", "google_save_url": "https://…",
    "wallet_state": { "google": "unknown", "apple": "unknown" } } }

curl -X PUT https://us-central1-compro-saas-core.cloudfunctions.net/lealtadApi/members/CF1234567/state \
  -H "x-compro-key: {api_key}" -H "x-client-id: {client_id}" -H "x-tenant-id: {tenant_id}" \
  -H "Content-Type: application/json" -d '{"balance":275}'

{ "applied": true, "member_id": "CF1234567", "balance": 275, "counted_mau": true,
  "delivery": { "google": "patched", "apple": "not_installed" } }

delivery muestra qué SO recibió el aviso de verdad — not_installed significa que ese miembro todavía no agregó la tarjeta en ESE SO, así que no se intentó nada ahí (no es un error). El saldo se actualiza igual y cuenta MAU sin importar el estado de instalación.

Límites de uso:

Códigos propios de esta sección:

Verificación de identidad y control de asistencia/acceso para programas de tipo student (carné de estudiante). El QR del carné abre el validador; el mismo token se consume por API para verificar o marcar asistencia.

Ejemplo — verificar un carné (público):

curl https://compropass.app/api/v1/students/<token>/verify

{
  "verified": true,
  "student": {
    "name": "María Rodríguez",
    "status": "active",
    "institution": "Universidad Latinoamericana",
    "attributes": [
      { "label": "Carrera",  "value": "Ing. en Computación" },
      { "label": "Facultad", "value": "Facultad de Ingeniería" },
      { "label": "Carné",    "value": "B12345" }
    ]
  },
  "verified_at": "2026-07-24T..."
}

Webhooks del programa student:

Entrega con firma HMAC (X-Compro-Signature) y reintentos; registro en webhook_logs. Configuración por tenant desde el portal: Configuración → API & Webhooks.

Gestión de pacientes y registro de visitas para programas de tipo patient. Documentación detallada disponible en el portal: Configuración → API & Webhooks.

Gestión de boletos y check-in para programas de tipo event. Documentación detallada disponible en el portal.

Guía: Agente Claude con KB API

Patrón recomendado para conectar un agente de soporte basado en Claude API con la Knowledge Base de ComProPass usando tool use.

1. Definir el tool en Claude API

2. Implementar el tool handler

3. Flujo completo