API & Integrazioni

14. API & Integrazioni

La sezione API & Integrazioni contiene strumenti per l’integrazione programmatica di 7Stamp con i tuoi sistemi esterni — CRM, POS, ERP, analisi, bot di messaggistica.

Chiavi API

La pagina principale della sezione è l’elenco delle chiavi API. Colonne:

• Nome — nome della chiave (di solito corrisponde al nome Staff collegato).
• Login — il login Staff a cui la chiave è legata.
• Chiave API — la chiave stessa (inizia con 7loc_sc_..., nascosta per impostazione predefinita, copiabile con un clic).
• Stato — Attivo.
• 🔄 — rigenera la chiave.
• 🗑️ — elimina la chiave.

Creare una chiave API

Tocca + AGGIUNGI CHIAVE API — si apre il popup Genera Chiave API:

• Scanner — menu a tendina per selezionare il Login Staff a cui la chiave sarà associata (uno Staff può avere una chiave).
• Pulsanti ANNULLA / GENERA.

Dopo GENERA la chiave viene creata e appare nell’elenco. Copiala immediatamente — la chiave completa potrebbe non essere mostrata di nuovo.

Cosa puoi fare tramite API

• Emettere una carta a un cliente tramite email/telefono.
• Aggiungere un timbro a un cliente specifico.
• Emettere un voucher (da template o personalizzato, con Redeem Code).
• Riscattare un voucher (se lavori tramite il tuo POS).
• Leggere lo stato della carta, il progresso, la cronologia.
• Iscriverti ai Webhook per ricevere eventi in tempo reale.

Webhook

I Webhook inviano gli eventi della carta a un sistema esterno. Supportati (vedi il glossario degli eventi):

• SCAN, DELIVERY_INSERT.
• REWARD_EARNED, LOTTERY_WIN.
• VOUCHER_ISSUED, ADMIN_VOUCHER_ISSUE, VOUCHER_REDEEMED.
• CARD_JOINED, CARD_ADDED_TO_WALLET, CARD_REMOVED_FROM_WALLET.
• CARD_CAMPAIGN, BIRTHDAY_GREETING.

Esempio di payload Webhook

{
  "entity": "card_event",
  "action": "created",
  "entity_id": 707,
  "event_id": "8f05e58decec48e09d328f0edebbacf6",
  "profile_id": 2,
  "profile_name": "Your Business",
  "profile_lang": "en",
  "data": {
    "event_type": "SCAN",
    "scanned_at": "2026-10-01T09:19:24.179424",
    "user_card_id": 10,
    "card_template_id": 14,
    "card_template_name": "Collect your stamps!",
    "stamps_added": 3,
    "stamps_before": 1,
    "stamps_after": 4,
    "amount": null,
    "external_order_id": "ORDER-1001",
    "workplace": { "id": 4, "name": "Bar Counter" },
    "device_type": null,
    "external_id": "odoo_contact_8821",
    "external_source": "odoo",
    "issued_vouchers": [
      {
        "id": 174,
        "unique_code": "100425813507",
        "stamp_number": 4,
        "issued_at": "2026-10-01T09:19:24.191836",
        "expires_at": "2027-01-01T23:59:59",
        "status": "ACTIVE",
        "voucher_template_id": 58,
        "voucher_description": "Free coffee",
        "voucher_image_url": "https://..."
      }
    ],
    "achieved_goals": [],
    "user": {
      "id": 2,
      "name": "Anna",
      "full_name": "Anna Smith",
      "email": "anna@example.com",
      "telegram_chat_id": null,
      "telegram_username": null,
      "whatsapp_phone": null,
      "birth_date": null
    }
  }
}

Integrazioni POS già pronte

• Poster — integrazione già pronta, si connette in pochi clic.
• Serve — integrazione già pronta.
• Altri registratori di cassa — realizzate su richiesta. Gratuite se tecnicamente fattibili (cioè, il tuo registratore espone un’API aperta o Webhook).

Broadcast via messaggistica tramite 7loc.com

Per i broadcast su WhatsApp, Telegram, Viber, si connette l’integrazione 7loc.com. Una volta attiva, il canale “messaggistica” diventa disponibile nelle Campagne accanto a PUSH ed Email.

Scenari no-code: Zapier e Make

API 7Stamp + Webhook funzionano con Zapier e Make (Integromat), permettendoti di costruire scenari senza codice:

• “Quando VOUCHER_REDEEMED — aggiungi un tag in Mailchimp”.
• “Quando REWARD_EARNED — invia una notifica su Slack”.
• “Quando BIRTHDAY_GREETING — crea un’attività nel CRM”.

---