Documentación de la API
Integra Ripple con tu aplicación usando nuestra API REST. Accede a datos públicos o autenticados según tus necesidades.
Inicio Rápido
Base URL
https://gzkqopqsirlugkybhals.supabase.co/functions/v1/public-apiEjemplo con cURL
curl "https://gzkqopqsirlugkybhals.supabase.co/functions/v1/public-api/tenant/mi-negocio/info"
Autenticación
Algunos endpoints requieren una API Key para acceso
Header de Autenticación
X-API-Key: tu_api_key_aquiPuedes generar una key con permisos finos desde Configuración → Integraciones IA. La clave se muestra una sola vez.
Límites de Uso
100
requests / minuto
429
status si excedes
60s
ventana de reset
Headers de respuesta: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Endpoints
/tenant/:slug/infoObtener información pública del tenant
Response
{
"id": "uuid",
"name": "Mi Negocio",
"slug": "mi-negocio",
"logoUrl": "https://...",
"primaryColor": "#F97316",
"widget": {
"title": "...",
"subtitle": "...",
"enabled": true
}
}/tenant/:slug/leaderboardTop 10 referidores del mes actual
Response
{
"leaderboard": [
{ "rank": 1, "customerId": "uuid", "count": 15, "points": 750 },
...
]
}/tenant/:slug/badgesLista de insignias activas del programa
Response
{
"badges": [
{ "id": "uuid", "name": "Primer Referido", "icon": "trophy", ... }
]
}/tenant/:slug/challengesDesafíos activos en el momento
Response
{
"challenges": [
{ "id": "uuid", "name": "Refiere 5 amigos", "target_value": 5, ... }
]
}/tenant/:slug/trackRegistrar evento de tracking (clicks, views)
Request Body
{
"eventType": "widget_view",
"referralCode": "ABC123",
"metadata": { "source": "landing" }
}Response
{ "success": true }/customer/:code/statsEstadísticas de un cliente (requiere API Key)
Response
{
"referralCode": "ABC123",
"points": 500,
"tier": "gold"
}/v1/customers?search=&page=1&page_size=50Búsqueda amplia de clientes; requiere permiso explícito customers:read. No viene en la clave mínima de un asistente.
Response
{
"data": [{ "id": "uuid", "name": "Ana", "points": 320, "tier": "gold" }],
"pagination": { "page": 1, "page_size": 50, "total": 1, "has_more": false }
}/v1/customers/:idObtener IDs, contacto y estado general de un cliente (scope customers:read)
Response
{ "data": { "id": "uuid", "user_id": "uuid", "name": "Ana", "phone": "521...", "referral_code": "ANA123" } }/v1/customers/:id/pointsConsultar saldo y estado de lealtad (scope loyalty:read)
Response
{ "data": { "id": "uuid", "points": 320, "tier": "gold", "referral_code": "ANA123" } }/v1/customers/:id/transactions?limit=50&before=Historial paginado de puntos y transacciones (scope transactions:read)
Response
{ "data": [{ "id": "uuid", "type": "purchase", "points": 20 }], "pagination": { "has_more": false } }/v1/loyalty/summaryResumen agregado del programa (scope loyalty:read)
Response
{ "data": { "customers": 120, "outstanding_points": 45600, "transactions": 890 } }/v1/customers/resolve?phone=%2B521234567890Coincidencia exacta por teléfono confirmado (customers:lookup). Alternativa: provider=zoho&external_id=ID. Un conflicto devuelve 409.
Response
{ "data": { "id": "uuid", "name": "Ana", "phone": "+521234567890" } }/v1/customers/:id/external-idsIDs de origen vinculados al cliente (customers:read).
Response
{ "data": [{ "provider": "zoho", "external_id": "123456" }] }/v1/program/rulesReglas públicas del programa del negocio de la API Key (loyalty:read).
Response
{ "data": { "points_per_unit": 1, "unit_name": "litros", "currency": "MXN" } }/v1/rewardsRecompensas activas del negocio (loyalty:read).
Response
{ "data": [{ "id": "uuid", "name": "Descuento", "points_cost": 100 }] }/v1/purchasesRegistra una compra una sola vez por ticket y negocio (purchases:write). amount es cantidad elegible, p. ej. litros; el importe monetario opcional va en metadata.total_amount.
Request Body
{
"customer_id": "uuid",
"ticket_id": "GAS-1842",
"source": "pos",
"amount": 40.5,
"currency": "MXN",
"purchased_at": "2026-10-05T12:00:00Z",
"metadata": { "total_amount": 490.00 }
}
Header obligatorio: Idempotency-Key: gas-1842-purchaseResponse
{ "data": { "transaction_id": "uuid", "points_awarded": 40, "balance": 370, "idempotent_replay": false } }/v1/purchases/:id/reverseRevierte una compra atómicamente, incluso después de diez minutos (purchases:write). Puede dejar deuda auditable si ya se canjearon puntos.
Request Body
{
"reason": "Ticket cancelado"
}
Header obligatorio: Idempotency-Key: gas-1842-reversalResponse
{ "data": { "reversal_id": "uuid", "balance": 330, "debt_points": 0, "review_required": false } }/v1/customers/:id/pointsBono manual excepcional y auditado (points:write); no usar para tickets de compra.
Request Body
{
"points": 50,
"description": "Bono por ticket GAS-1842",
"external_reference": "GAS-1842"
}
Header obligatorio: Idempotency-Key: gas-1842-pointsResponse
{ "data": { "transaction_id": "uuid", "points_awarded": 50, "balance": 370, "idempotent_replay": false } }