API Pública

    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-api

    Ejemplo 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_aqui

    Puedes 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

    GET
    /tenant/:slug/info

    Obtener información pública del tenant

    Response

    {
      "id": "uuid",
      "name": "Mi Negocio",
      "slug": "mi-negocio",
      "logoUrl": "https://...",
      "primaryColor": "#F97316",
      "widget": {
        "title": "...",
        "subtitle": "...",
        "enabled": true
      }
    }
    GET
    /tenant/:slug/leaderboard

    Top 10 referidores del mes actual

    Response

    {
      "leaderboard": [
        { "rank": 1, "customerId": "uuid", "count": 15, "points": 750 },
        ...
      ]
    }
    GET
    /tenant/:slug/badges

    Lista de insignias activas del programa

    Response

    {
      "badges": [
        { "id": "uuid", "name": "Primer Referido", "icon": "trophy", ... }
      ]
    }
    GET
    /tenant/:slug/challenges

    Desafíos activos en el momento

    Response

    {
      "challenges": [
        { "id": "uuid", "name": "Refiere 5 amigos", "target_value": 5, ... }
      ]
    }
    POST
    /tenant/:slug/track

    Registrar evento de tracking (clicks, views)

    Request Body

    {
      "eventType": "widget_view",
      "referralCode": "ABC123",
      "metadata": { "source": "landing" }
    }

    Response

    { "success": true }
    GET
    /customer/:code/stats
    API Key

    Estadísticas de un cliente (requiere API Key)

    Response

    {
      "referralCode": "ABC123",
      "points": 500,
      "tier": "gold"
    }
    GET
    /v1/customers?search=&page=1&page_size=50
    API Key

    Bú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 }
    }
    GET
    /v1/customers/:id
    API Key

    Obtener 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" } }
    GET
    /v1/customers/:id/points
    API Key

    Consultar saldo y estado de lealtad (scope loyalty:read)

    Response

    { "data": { "id": "uuid", "points": 320, "tier": "gold", "referral_code": "ANA123" } }
    GET
    /v1/customers/:id/transactions?limit=50&before=
    API Key

    Historial paginado de puntos y transacciones (scope transactions:read)

    Response

    { "data": [{ "id": "uuid", "type": "purchase", "points": 20 }], "pagination": { "has_more": false } }
    GET
    /v1/loyalty/summary
    API Key

    Resumen agregado del programa (scope loyalty:read)

    Response

    { "data": { "customers": 120, "outstanding_points": 45600, "transactions": 890 } }
    GET
    /v1/customers/resolve?phone=%2B521234567890
    API Key

    Coincidencia 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" } }
    GET
    /v1/customers/:id/external-ids
    API Key

    IDs de origen vinculados al cliente (customers:read).

    Response

    { "data": [{ "provider": "zoho", "external_id": "123456" }] }
    GET
    /v1/program/rules
    API Key

    Reglas públicas del programa del negocio de la API Key (loyalty:read).

    Response

    { "data": { "points_per_unit": 1, "unit_name": "litros", "currency": "MXN" } }
    GET
    /v1/rewards
    API Key

    Recompensas activas del negocio (loyalty:read).

    Response

    { "data": [{ "id": "uuid", "name": "Descuento", "points_cost": 100 }] }
    POST
    /v1/purchases
    API Key

    Registra 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-purchase

    Response

    { "data": { "transaction_id": "uuid", "points_awarded": 40, "balance": 370, "idempotent_replay": false } }
    POST
    /v1/purchases/:id/reverse
    API Key

    Revierte 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-reversal

    Response

    { "data": { "reversal_id": "uuid", "balance": 330, "debt_points": 0, "review_required": false } }
    POST
    /v1/customers/:id/points
    API Key

    Bono 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-points

    Response

    { "data": { "transaction_id": "uuid", "points_awarded": 50, "balance": 370, "idempotent_replay": false } }