ComProPass API

v1

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.

Knowledge Base

Artículos de soporte por audiencia. Acceso público sin autenticación para contenido public.

Care API

CRUD de pacientes y registro de visitas. Requiere credenciales de tenant.

Events API

Gestión de boletos y check-in en eventos. Requiere credenciales de tenant.

URLs base

        
          # Producción

          https://compropass.app/v1

          # Futuro (subdominio dedicado)

          https://api.compropass.app/v1

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.

Header	Descripción	Requerido en
x-client-id	ID del cliente en ComProPass	audience ≠ public
x-tenant-id	ID del programa / tenant	audience ≠ public
x-compro-key	API Key del tenant	audience ≠ public

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

Códigos de error

Código HTTP	code	Causa
400	BAD_REQUEST	Parámetros inválidos o faltantes
401	INVALID_API_KEY	Credenciales incorrectas o ausentes
403	AUDIENCE_NOT_ALLOWED	Audiencia no accesible con las credenciales actuales
404	—	Recurso no encontrado
405	—	Método HTTP no permitido (solo GET)
500	—	Error interno del servidor

Knowledge Base API

público sin key

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.

GET /v1/kb Listar y buscar artículos

Parámetros de query

Parámetro	Tipo	Default	Descripción
q	string	—	Búsqueda por texto en título y contenido
audience	string	public	Audiencia: `public` \| `manager` \| `cashier`
category	string	—	Filtrar por categoría (ej: `wallet`, `lealtad`, `vcard`)
limit	number	20	Máximo de resultados (máx 50)

Ejemplos

Buscar artículos públicos sobre Google Wallet:

curl https://compropass.app/v1/kb?q=google+wallet

Artículos para manager con credenciales:

curl https://compropass.app/v1/kb?audience=manager \

    -H "x-client-id: {client_id}" \

    -H "x-tenant-id: {tenant_id}" \

    -H "x-compro-key: {api_key}"

Respuesta

          {

    "articles": [

      {

        "id": "pub_03",

        "title": "Cómo agregar tu tarjeta a Google Wallet",

        "content": "Para agregar tu tarjeta digital...",

        "category": "wallet",

        "audience": "public",

        "updated_at": "2026-04-15T10:23:00Z"

      }

    ],

    "total": 1,

    "audience": "public"

}

GET /v1/kb/:id Artículo individual

Ejemplo

curl https://compropass.app/v1/kb/pub_03

Respuesta

          {

    "article": {

      "id": "pub_03",

      "title": "Cómo agregar tu tarjeta a Google Wallet",

      "content": "Para agregar tu tarjeta digital...",

      "category": "wallet",

      "audience": "public",

      "updated_at": "2026-04-15T10:23:00Z"

    }

}

Care API

requiere key

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

Método	Ruta	Descripción
GET	/v1/care/patients	Listar pacientes
POST	/v1/care/patients	Crear paciente
GET	/v1/care/patients/:id	Detalle de paciente
POST	/v1/care/patients/:id/visits	Registrar visita

Events API

requiere key

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

Método	Ruta	Descripción
GET	/v1/events/tickets	Listar boletos
POST	/v1/events/tickets	Crear boleto
GET	/v1/events/tickets/:id	Detalle de boleto
POST	/v1/events/tickets/:id/checkin	Check-in de boleto

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

        {

    "name": "search_knowledge_base",

    "description": "Busca artículos en la base de conocimiento de ComProPass para responder preguntas de soporte L1. Úsalo cuando el usuario pregunte sobre Wallet, puntos, sellos, vCard o acceso al portal.",

    "input_schema": {

      "type": "object",

      "properties": {

        "query": {

          "type": "string",

          "description": "Término de búsqueda relevante a la pregunta del usuario"

        },

        "audience": {

          "type": "string",

          "enum": ["public", "manager", "cashier"],

          "description": "Audiencia del artículo según el rol del usuario"

        }

      },

      "required": ["query"]

    }

}

2. Implementar el tool handler

        // Node.js — cuando Claude llama search_knowledge_base

async function handleToolCall(toolName, toolInput) {

    if (toolName === 'search_knowledge_base') {

      const { query, audience = 'public' } = toolInput;

      const url = new URL('https://compropass.app/v1/kb');

      url.searchParams.set('q', query);

      url.searchParams.set('audience', audience);

      url.searchParams.set('limit', '5');

      const res  = await fetch(url.toString());

      const data = await res.json();

      return data.articles.map(a => `## ${a.title}\n${a.content}`).join('\n\n');

    }

}

3. Flujo completo

1 Usuario envía pregunta → Claude recibe con el tool search_knowledge_base disponible

2 Claude decide si necesita buscar en KB y llama el tool con un query relevante

3 Tu backend llama GET /v1/kb?q=... y devuelve los artículos a Claude como tool_result

4 Claude sintetiza una respuesta clara usando el contenido real del KB