Philia Pro — Documentación para integradores

Conecta tu software al motor de fidelización de Philia Pro. Cualquier POS, sistema de reservas o plataforma de gestión puede otorgar y canjear puntos en nombre de sus clientes.

1. Modelo de negocio: quién es quién

Tu software nunca reemplaza a Philia Pro — actúa en nombre del negocio (el partner) que ya tiene su cuenta aquí. Philia Pro es siempre el dueño de los puntos, sellos y vales; tu integración solo los otorga y canjea a través de la API.

El negocio final es el partner en Philia Pro, no tu software. Cada partner tiene sus propios miembros, tarjetas y datos, completamente aislados del resto de la plataforma.
Tu software nunca ve el token de otro partner. Cada Agent Key pertenece a un único partner y solo puede operar sobre sus propios recursos.
Un mismo partner puede usar más de un software conectado a la vez (por ejemplo, un hotel que usa tu POS para el restaurante y otra herramienta para reservas) — ambos comparten el mismo saldo de puntos de sus clientes.

2. Antes de integrar — checklist

El negocio final ya tiene una cuenta activa en Philia Pro, con al menos un club y una tarjeta configurada.
El negocio generó su propia Agent Key desde su panel (Configuración → Agent Keys) y te la entregó — tÃº nunca la generas en su nombre.
Elegiste el preset de permisos correcto al crear la key: "pos" alcanza para otorgar puntos y canjear premios.
Revisaste el catálogo de endpoints en la documentación interactiva (arriba) y el contrato de errores (sección 5).

3. Autenticación

No hay intercambio de credenciales por un token de sesión — la Agent Key ES la credencial, en cada request:

X-Agent-Key: rl_agent_<tu key>
Accept: application/json

La key no expira por tiempo. El negocio puede revocarla en cualquier momento desde su panel; si recibes 401, avísale para que genere una nueva.

4. Idempotencia (obligatoria en canjear y deducir)

Los endpoints que mueven puntos (otorgar, canjear, deducir) aceptan el header Idempotency-Key, que es OBLIGATORIO en canjear y deducir (sin él responden 400 IDEMPOTENCY_KEY_REQUIRED) y recomendado en otorgar y revertir. Si tu integración reintenta una operación por timeout de red, envía el mismo valor y la API te devuelve la respuesta original en vez de duplicar la operación.

Idempotency-Key: <valor único de tu operación>

Genera un valor único por operación de tu lado (UUID, hash de tu propia transacción interna, etc.) — hasta 255 caracteres.
Un reintento con la misma key y la misma ruta devuelve la respuesta cacheada, con el header Idempotency-Replayed: true.
Un reintento mientras la primera solicitud todavía se está procesando recibe HTTP 409 — espera antes de reintentar, no insistas de inmediato.
Sin este header, el comportamiento es el de siempre: cada request se procesa de forma independiente.

5. Endpoints principales

El catálogo completo, con esquemas de request/response, vive en la documentación interactiva. Estos son los que más vas a usar:

URL base: https://app.philiapro.com/api/agent/v1

POST	/partner/transactions/purchase	Registra una compra y otorga puntos según la tarjeta.
POST	/partner/transactions/redeem	Canjea un premio y descuenta los puntos correspondientes.
POST	/partner/transactions/deduct	Descuenta puntos manualmente (por ejemplo, un canje fuera de plataforma).
GET	/partner/members/{id}/balance/{cardId}	Consulta el saldo de puntos de un miembro en una tarjeta.
GET	/partner/transactions	Lista transacciones, con filtros por miembro, tarjeta y fecha.

6. Catálogo de errores

200 / 201	Procesado correctamente	Guarda el transaction_id devuelto.
401	Agent Key inválida o revocada	Pídele al negocio una key nueva.
403	Scope insuficiente o feature desactivada para ese partner	Revisa el código y el campo required_scope en la respuesta.
402	La suscripción del negocio no está al día (past_due, cancelled, incomplete o suspended)	Avísale al negocio que regularice su facturación desde su panel; mientras tanto, las lecturas (saldo, listado de transacciones) siguen funcionando.
404	Recurso no encontrado (tarjeta, miembro, premio)	Verifica el identificador enviado.
409	Idempotency-Key todavía procesándose	Espera y no reintentes de inmediato.
422	Validación fallida, saldo insuficiente, o límite del plan alcanzado	El campo message explica el motivo exacto.
429	Límite de requests por minuto excedido	Reintenta con backoff exponencial.

Una respuesta exitosa trae error: false. Una respuesta con error trae error como un objeto ({ code, message, retryStrategy, requestId }), nunca un booleano — el campo retryStrategy (no_retry, backoff, fix_request o contact_support) le indica a tu integración cómo reaccionar sin tener que hardcodear el código HTTP.

7. Preguntas frecuentes

¿Puedo probar sin una cuenta real?

Sí, hay una cuenta de sandbox compartida (sin límite de sucursales, con la Agent API habilitada) — pide las credenciales escribiendo a hola@philiapro.com.

¿Qué pasa si el negocio cambia de plan?

Los límites y permisos (por ejemplo, cuántas Agent Keys puede tener) se ajustan automáticamente; tu integración recibe 403 con el código FEATURE_DISABLED o LIMIT_REACHED si algo deja de estar disponible.

¿Los puntos se calculan en tu sistema o en el mío?

Siempre en Philia Pro. Tú envías el monto de la compra (o los puntos si ya los calculaste) y la tarjeta configurada del negocio determina el resto.