App
Für Entwickler

Öffentliche Punkto-API

Integrieren Sie das Punkto-Treueprogramm in Ihr eigenes Produkt — Punkte gutschreiben und einlösen, QR-Codes zum Einlösen generieren, Kundensaldo, Empfehlungslink, Name und Avatar abrufen.

Zugriff beantragenMelden Sie sich in Ihrem Business-Dashboard an, um sich zu bewerben — kostenlos.

So funktioniert's

1

Anfrage stellen

Beschreiben Sie in Ihrem Business-Dashboard → Einstellungen → API, was Sie entwickeln und wozu Sie Zugriff benötigen.

2

Wir prüfen sie

Unser Team prüft die Anfrage — in der Regel innerhalb weniger Tage.

3

Schlüssel erhalten

Nach der Genehmigung erscheint Ihr API-Schlüssel im Dashboard. Kopieren Sie ihn sofort — aus Sicherheitsgründen wird er nur einmal angezeigt.

Authentifizierung

Jede Anfrage benötigt Ihren API-Schlüssel als Bearer-Token im Authorization-Header. Alle Endpunkte handeln im Namen Ihres Unternehmens; Kunden werden anhand der Telefonnummer identifiziert, da Drittanbieter-Apps keine interne Punkto-Kunden-ID haben.

Authorization: Bearer $PUNKTO_API_KEY

Endpunkte

GET/business

Ihr Unternehmensprofil

Lesen Sie die öffentlichen Daten Ihres Unternehmens sowie die Punkte-/Rabattkonfiguration — Öffnungszeiten, Adresse, Punkte pro Währungseinheit, maximaler Rabattsatz und -stufen — damit sich Ihre Integration selbst konfiguriert, statt Limits fest zu codieren.

Anfrage

curl https://api.punkto.app/api/public/v1/business \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "business": {
    "id": "cknq0abc10000...",
    "name": "Coffee Corner",
    "slug": "coffee-corner",
    "city": "Warszawa",
    "workingHours": { "mon": { "open": "08:00", "close": "18:00" } },
    "pointsPerCurrencyUnit": 0.1,
    "maxDiscountRatio": 0.2,
    "maxDiscountPerReceipt": null,
    "discountTiers": null,
    "category": { "slug": "cafes", "name": "Cafes" }
  }
}
POST/points/earn

Punkte gutschreiben

Schreiben Sie einem Kunden nach einem Kauf Punkte gut — zum gleichen Satz wie beim QR-Scan in der App (abgerundet).

Anfrage

curl -X POST https://api.punkto.app/api/public/v1/points/earn \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "amount": 49.90}'

Antwort

{
  "balance": 5,
  "transaction": {
    "id": "cknq0x1a20001...",
    "type": "earn",
    "points": 5,
    "createdAt": "2026-09-23T23:16:50.250Z"
  }
}
POST/points/redeem

Punkte abziehen

Lösen Sie Punkte als Rabatt auf einen Rechnungsbetrag ein. Der Betrag wird automatisch durch Ihre konfigurierten Rabattgrenzen begrenzt.

Anfrage

curl -X POST https://api.punkto.app/api/public/v1/points/redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20, "receiptAmount": 49.90}'

Antwort

{
  "balance": 130,
  "discountAmount": 20,
  "transaction": {
    "id": "cknq0x1a20002...",
    "type": "redeem",
    "points": 20,
    "createdAt": "2026-09-23T23:18:12.104Z"
  }
}
POST/points/redeem-code

QR-Code zum Einlösen generieren

Stellen Sie einen kurzlebigen Code (2 Minuten) aus, mit dem ein Kunde Punkte vor Ort einlösen kann. Rendern Sie `code` selbst als QR-Code, oder lassen Sie den 6-stelligen `shortCode` eingeben.

Anfrage

curl -X POST https://api.punkto.app/api/public/v1/points/redeem-code \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20}'

Antwort

{
  "code": "eyJhbGciOiJIUzI1NiIs...",
  "shortCode": "482913",
  "expiresIn": 120,
  "requestedPoints": 20,
  "grantedPoints": 20,
  "capped": false
}
GET/businesses

Unternehmen auflisten

Öffentliches Verzeichnis aktiver Punkto-Unternehmen — dieselbe Liste, die in der Kunden-App angezeigt wird.

Anfrage

curl https://api.punkto.app/api/public/v1/businesses \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "businesses": [
    {
      "id": "cknq0abc10000...",
      "slug": "coffee-corner",
      "name": "Coffee Corner",
      "logoUrl": "https://...",
      "city": "Warszawa",
      "category": { "slug": "cafes", "name": "Cafes" }
    }
  ]
}
GET/rewards

Ihre Prämien auflisten

Der Katalog der Sonderangebote/Prämien Ihres Unternehmens — dieselbe Liste, die im Unternehmensdetail-Popup der Kunden-App angezeigt wird.

Anfrage

curl https://api.punkto.app/api/public/v1/rewards \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "rewards": [
    {
      "id": "cknq0rwd10000...",
      "name": "Free coffee",
      "costPoints": 100,
      "discountType": "amount",
      "discountValue": 10
    }
  ]
}
POST/rewards/:rewardId/redeem

Prämie einlösen

Lösen Sie für einen Kunden eine bestimmte benannte Prämie ein (z. B. „Kostenloser Kaffee“) statt eines allgemeinen Punkterabatts — zieht deren Punktekosten vom Kundensaldo ab.

Anfrage

curl -X POST https://api.punkto.app/api/public/v1/rewards/cknq0rwd10000.../redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789"}'

Antwort

{
  "balance": 50,
  "reward": { "id": "cknq0rwd10000...", "name": "Free coffee", "costPoints": 100 },
  "transaction": {
    "id": "cknq0x1a20003...",
    "type": "redeem",
    "points": -100,
    "createdAt": "2026-09-23T23:53:15.497Z"
  }
}
GET/products

Ihre Produkte/Dienstleistungen auflisten

Der Produkt-/Dienstleistungskatalog Ihres Unternehmens — dieselbe Liste, die in der Kunden-App angezeigt wird.

Anfrage

curl https://api.punkto.app/api/public/v1/products \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "products": [
    { "id": "cknq0prd10000...", "name": "Cappuccino", "price": 14.5, "emoji": "☕" }
  ]
}
GET/customers/:phone/balance

Punktesaldo des Kunden

Erfahren Sie, wie viele Punkte ein Kunde aktuell hat.

Anfrage

curl https://api.punkto.app/api/public/v1/customers/+48123456789/balance \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "points": 150
}
GET/customers/:phone/history

Punkteverlauf des Kunden

Die Punktetransaktionen eines Kunden bei Ihrem Unternehmen, neueste zuerst — nützlich für den Abgleich. Begrenzt auf `limit` Zeilen (Standard 50, maximal 200).

Anfrage

curl "https://api.punkto.app/api/public/v1/customers/+48123456789/history?limit=20" \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "transactions": [
    { "id": "cknq0x1a20001...", "type": "earn", "points": 5, "createdAt": "2026-09-23T23:16:50.250Z" },
    { "id": "cknq0x1a20002...", "type": "redeem", "points": -20, "createdAt": "2026-09-23T23:18:12.104Z" }
  ]
}
GET/customers/:phone/referral

Empfehlungslink des Kunden

Rufen Sie den Empfehlungscode eines Kunden ab — neue Nutzer, die ihn eingeben, werden als von ihm geworben verknüpft.

Anfrage

curl https://api.punkto.app/api/public/v1/customers/+48123456789/referral \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "referralCode": "GT2DEY"
}
GET/customers/:phone/profile

Name & Avatar des Kunden

Lesen Sie den Anzeigenamen und Avatar eines Kunden.

Anfrage

curl https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Antwort

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}
PATCH/customers/:phone/profile

Name & Avatar aktualisieren

Aktualisieren Sie den Anzeigenamen und/oder die Avatar-URL eines Kunden.

Anfrage

curl -X PATCH https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Anna Kowalska"}'

Antwort

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}

Gut zu wissen

  • Kunden werden anhand der Telefonnummer identifiziert — eine Drittanbieter-App hat keine interne Punkto-Kunden-ID.
  • Gehört eine Telefonnummer keinem registrierten Punkto-Kunden, liefert der Endpunkt 404 statt ein Konto anzulegen.
  • Gutgeschriebene Punkte werden abgerundet; eingelöste Punkte berücksichtigen automatisch Ihre konfigurierten Rabattstufen — zusätzliche Logik auf Ihrer Seite ist nicht nötig.

Bereit zur Integration?

Solange die öffentliche API noch finalisiert wird, prüft unser Team jede Anfrage — erzählen Sie uns von Ihrer App, wir melden uns bei Ihnen.

Zugriff beantragen

Partner-App herunterladen

Gewinne neue Kunden schnell und günstig

App StoreGoogle Play