Documentação da API

Envie eventos de transação do portador de cartão para o emparelhamento de ofertas em tempo real. O principal ponto de integração para instituições financeiras.

Envie muitos eventos de transação em uma única requisição assinada — para feeds legados ou de alto volume.

Prefere um arquivo diário? Envie um CSV de transações pelo Portal da Instituição — validado e correspondido como o webhook.

Obtenha as ofertas elegíveis de um portador para exibir no seu app ou no widget integrável.

Inscreva um portador em uma oferta para que as transações dele passem a corresponder a ela.

Histórico de resgates paginado por cursor para integração com BI/data warehouse. Autenticado pela chave de API da instituição.

Razão de liquidações paginado por cursor com o valor financiado pelo comerciante, a receita da Saldo e o repasse à instituição.

Funil de engajamento para um período de datas: visualizações do widget, portadores de cartão únicos, impressões, adições e resgates.

Retorna as ofertas ativas e com orçamento disponível para o portador, respeitando a ordem do seu programa e a elegibilidade por portador.

Parâmetros de consulta

• cardholder_token Obrigatório. O token opaco do portador.
• locale Opcional. en, es ou pt-BR — localiza o título e a descrição de cada oferta. Se o seu programa não oferecer esse idioma, o feed usa o primeiro idioma suportado pelo programa.
• segment Opcional. O código de segmento do portador vindo dos seus próprios sistemas (ex.: premium). Ofertas que você limitou a segmentos só aparecem quando ele corresponde; ofertas sem restrição sempre aparecem. Usado apenas nesta requisição: a Saldo nunca armazena o segmento de um portador.
• limit Opcional. 1–100 (também limitado pela configuração do seu widget).
• personalize Opcional. Defina true para ordenar o feed por afinidade do portador; adiciona um reason a cada oferta.
• prefer_merchants, prefer_categories Opcional. prefer_merchants e prefer_categories aceitam dicas separadas por vírgula, usadas apenas em memória e nunca armazenadas.

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
}

Cria o vínculo portador–oferta para o matching começar. Idempotente — reenviar retorna already_added.

Corpo da requisição

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..." }

Envie o mesmo segment ao adicionar uma oferta limitada a segmentos (caso contrário, 403 segment_not_eligible). Se o portador já tiver o número máximo de ofertas ativas do seu programa, a requisição retorna 409 max_active_offers.

Lista de resgates paginada por cursor para a instituição que faz a chamada. Os tokens de portador de cartão são mascarados para os primeiros/últimos 4 caracteres.

Parâmetros de consulta

• from, to — carimbos de data/hora ISO 8601 (opcional)
• cursor — valor opaco da resposta anterior (opcional)
• limit — de 1 a 1000 (padrão 100)

Exemplo

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 do razão de liquidações paginadas por cursor com o valor financiado pelo comerciante, a receita da comissão da Saldo, o repasse à instituição e o status.

Parâmetros de consulta

• status — pending | settled | reversed (opcional)
• from, to, cursor, limit — mesma semântica dos resgates

Funil de engajamento agregado para um período de datas. Por padrão, usa os últimos 30 dias quando from / to são omitidos.

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