Documentación de la API

Envía eventos de transacción del tarjetahabiente para el emparejamiento de ofertas en tiempo real. El punto de integración principal para las instituciones financieras.

Enviá muchos eventos de transacción en una sola solicitud firmada — para feeds heredados o de alto volumen.

¿Preferís un archivo diario? Subí un CSV de transacciones desde el Portal de Institución — validado y emparejado como el webhook.

Obtené las ofertas elegibles de un tarjetahabiente para mostrarlas en tu app o en el widget integrable.

Inscribí a un tarjetahabiente en una oferta para que sus transacciones empiecen a emparejarse con ella.

Historial de canjes paginado por cursor para la integración con BI/almacén de datos. Autenticado mediante la clave de API de la institución.

Libro mayor de liquidaciones paginado por cursor con el monto financiado por el comercio, los ingresos de Saldo y el pago a la institución.

Embudo de interacción para un período de fechas: vistas del widget, tarjetahabientes únicos, impresiones, adiciones y canjes.

Devuelve las ofertas activas y con presupuesto disponible para el tarjetahabiente, respetando el orden de tu programa y la elegibilidad por tarjetahabiente.

Parámetros de consulta

• cardholder_token Obligatorio. El token opaco del tarjetahabiente.
• locale Opcional. en, es o pt-BR — localiza el título y la descripción de cada oferta. Si tu programa no ofrece ese idioma, el feed usa el primer idioma admitido por tu programa.
• segment Opcional. El código de segmento del tarjetahabiente según tus propios sistemas (p. ej. premium). Las ofertas que limitaste a segmentos solo aparecen si coincide; las ofertas sin restricción siempre aparecen. Se usa solo en esta solicitud: Saldo nunca guarda el segmento de un tarjetahabiente.
• limit Opcional. 1–100 (también limitado por la configuración de tu widget).
• personalize Opcional. Poné true para ordenar el feed por afinidad del tarjetahabiente; agrega un reason a cada oferta.
• prefer_merchants, prefer_categories Opcional. prefer_merchants y prefer_categories aceptan pistas separadas por comas, usadas solo en memoria y nunca almacenadas.

curl "https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/offers?cardholder_token=tok_ch_abc123&locale=es&limit=20" \
  -H "Authorization: Bearer slk_..."

{
  "offers": [
    {
      "id": "0b1...",
      "title": "Spend $200 at Acme, get $15 back",
      "description": "Gasta $200 en Acme y recibe $15",
      "merchant_id": "aaaa...",
      "min_spend": 200.00,
      "cashback_amount": 13.20,
      "currency": "USD",
      "starts_at": "2026-04-01T00:00:00Z",
      "expires_at": "2026-06-30T00:00:00Z",
      "added": false
    }
  ],
  "total": 12,
  "personalized": false
}

Crea el vínculo tarjetahabiente–oferta para que empiece el emparejamiento. Idempotente — reintentarlo devuelve already_added.

Cuerpo de la solicitud

curl -X POST "https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/offers/0b1.../add" \
  -H "Authorization: Bearer slk_..." \
  -H "Content-Type: application/json" \
  -d '{ "cardholder_token": "tok_ch_abc123", "card_token": "tok_card_xyz789" }'

// 201 Created
{ "status": "added", "cardholder_offer_id": "c0f..." }

// 200 OK (idempotent re-add)
{ "status": "already_added", "cardholder_offer_id": "c0f..." }

Envía el mismo segment al agregar una oferta limitada a segmentos (de lo contrario, 403 segment_not_eligible). Si el tarjetahabiente ya tiene el máximo de ofertas activas de tu programa, la solicitud devuelve 409 max_active_offers.

Lista de canjes paginada por cursor para la institución que realiza la llamada. Los tokens de tarjetahabiente se enmascaran a los primeros/últimos 4 caracteres.

Parámetros de consulta

• from, to — marcas de tiempo ISO 8601 (opcional)
• cursor — valor opaco de la respuesta anterior (opcional)
• limit — de 1 a 1000 (predeterminado 100)

Ejemplo

curl https://saldo-consumer-api-git-staging-kalantech.vercel.app/api/v1/reporting/redemptions?limit=2 \
  -H "Authorization: Bearer slk_..."

{
  "data": [
    {
      "id": "8f3...",
      "created_at": "2026-04-29T14:32:11.000Z",
      "status": "settled",
      "merchant_funded_amount": 15.00,
      "institution_payout_amount": 13.20,
      "offer": {
        "id": "0b1...",
        "title": "Spend $200 at Acme, get $15 back",
        "merchant_name": "Acme Inc."
      },
      "cardholder_token_masked": "tok_...c123"
    }
  ],
  "pagination": {
    "limit": 2,
    "next_cursor": "2026-04-29T14:32:11.000Z|8f3..."
  }
}

Entradas del libro mayor de liquidaciones paginadas por cursor con el monto financiado por el comercio, los ingresos de la comisión de Saldo, el pago a la institución y el estado.

Parámetros de consulta

• status — pending | settled | reversed (opcional)
• from, to, cursor, limit — misma semántica que los canjes

Embudo de interacción agregado para un período de fechas. De forma predeterminada usa los últimos 30 días cuando se omiten from / to .

{
  "window": { "from": "...", "to": "..." },
  "data": {
    "widget_views": 12834,
    "unique_cardholders": 4291,
    "offer_impressions": 38420,
    "offer_add_successes": 5102,
    "redemptions": 612
  }
}