🚀 API Loyalty System

Integra il sistema di fidelizzazione MyGestApp nelle tue applicazioni con le nostre API REST complete e sicure

Quick Start Documentazione

📚 Navigazione

🎯 Introduzione

Le API REST del Sistema Loyalty MyGestApp permettono l'integrazione del sistema di fidelizzazione con qualsiasi applicazione esterna, offrendo controllo completo su clienti, transazioni e programmi fedeltà.

🌐 Specifiche Tecniche

  • Base URL: https://my.gest.app/api/v1/loyalty_api_core.php
  • Formato: JSON (application/json)
  • Autenticazione: API Key via header X-API-Key
  • Rate Limit: 1000 richieste/ora per API key
  • HTTPS: Richiesto per tutte le chiamate

Casi d'uso principali

E-commerce

Accumulo punti automatico per ogni ordine, gestione sconti fedeltà e programmi VIP personalizzati.

POS/Casse

Pagamenti con crediti fedeltà, verifica PIN in tempo reale e accumulo punti istantaneo.

App Mobile

Consultazione saldi, cronologia transazioni e gestione carte digitali direttamente in app.

⚡ Quick Start

Inizia in 4 semplici passi e integra le API in meno di 15 minuti.

1

Ottieni API Key

Autentica il tuo merchant per ottenere l'API key necessaria

2

Test Connessione

Verifica la connessione con l'endpoint health check

3

Trova Clienti

Cerca i tuoi clienti per email o numero tessera

4

Prima Transazione

Accumula punti o elabora pagamenti con crediti

🔐 Autenticazione

Ottenere API Key

POST /auth/token

Genera API key usando le credenziali merchant.

Richiesta cURL 
curl -X POST "https://my.gest.app/api/v1/loyalty_api_core.php?endpoint=auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "tuo-merchant@example.com",
    "password": "tua-password"
  }'

✅ Risposta Success

{
  "success": true,
  "data": {
    "api_key": "loy_abc123...",
    "expires_at": "2026-08-06 01:29:43",
    "merchant": {
      "id": 5,
      "business_name": "Il Tuo Business",
      "email": "merchant@example.com"
    }
  }
}

Uso API Key

Includi l'API key in tutte le richieste successive tramite header:

Header Richiesta 
X-API-Key: loy_your_api_key_here

⚠️ Sicurezza API Key

  • Mantieni l'API key sempre segreta
  • Non esporla mai in codice client-side pubblico
  • Rigenera periodicamente le chiavi
  • Usa HTTPS per tutte le comunicazioni

📡 Endpoints Principali

Health Check

GET /health

Verifica stato API (non richiede autenticazione).

Richiesta 
curl "https://my.gest.app/api/v1/loyalty_api_core.php?endpoint=health"

Trova Cliente

POST /customers/find

Cerca cliente per email o numero tessera.

Parametro Tipo Richiesto Descrizione
email string Opzionale* Email del cliente
card_number string Opzionale* Numero tessera fedeltà

*Almeno uno dei due parametri è richiesto

Esempio Richiesta 
curl -X POST "https://my.gest.app/api/v1/loyalty_api_core.php?endpoint=customers/find" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: loy_your_api_key" \
  -d '{"email": "cliente@example.com"}'

Accumula Punti

POST /transactions/earn

Registra vendita e accumula punti fedeltà.

Parametro Tipo Richiesto Descrizione
email string Richiesto* Email del cliente
amount float Richiesto Importo vendita (€)
description string Opzionale Descrizione transazione
external_id string Opzionale ID univoco sistema esterno
Esempio Completo 
curl -X POST "https://my.gest.app/api/v1/loyalty_api_core.php?endpoint=transactions/earn" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: loy_your_api_key" \
  -d '{
    "email": "cliente@example.com",
    "amount": 25.50,
    "description": "Ordine #1234",
    "external_id": "order_1234"
  }'

Paga con Crediti

POST /transactions/pay

Pagamento usando crediti fedeltà (richiede PIN cliente).

🔒 Sicurezza PIN

I pagamenti con crediti richiedono sempre il PIN del cliente per garantire la sicurezza delle transazioni.

💡 Esempi di Integrazione

🛒 E-commerce - Accumulo Punti Automatico

PHP - Checkout Hook 
// Dopo completamento ordine
$orderTotal = 125.50;
$customerEmail = "cliente@example.com";
$orderId = "ORD-2025-001";

$response = callLoyaltyAPI('transactions/earn', [
    'email' => $customerEmail,
    'amount' => $orderTotal,
    'description' => "Ordine E-commerce #{$orderId}",
    'external_id' => $orderId
]);

if ($response['success']) {
    $pointsEarned = $response['data']['points_earned'];
    showMessage("Hai guadagnato {$pointsEarned} punti!");
}

📱 JavaScript - Controllo Saldo

JavaScript - App Mobile 
async function getCustomerBalance(email) {
    try {
        const response = await fetch(
            'https://my.gest.app/api/v1/loyalty_api_core.php?endpoint=customers/find',
            {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-API-Key': 'loy_your_api_key'
                },
                body: JSON.stringify({ email: email })
            }
        );
        
        const data = await response.json();
        
        if (data.success) {
            return {
                points: data.data.card.points_balance,
                credits: data.data.card.credit_balance
            };
        }
    } catch (error) {
        console.error('Errore API:', error);
    }
}

❌ Gestione Errori

Codici di Stato HTTP

Codice Significato Descrizione
200 OK Richiesta elaborata con successo
400 Bad Request Parametri mancanti o non validi
401 Unauthorized API key mancante o non valida
404 Not Found Risorsa non trovata
409 Conflict Transazione duplicata
500 Internal Error Errore interno del server

❌ Formato Errore Standard

{
  "success": false,
  "error": "Customer not found",
  "code": 404,
  "timestamp": "2025-08-06T01:29:50+02:00"
}

🆘 Supporto e Risorse

📧 Supporto Tecnico

Per assistenza tecnica, problemi di integrazione o domande:

  • Email: support@gest.app
  • Tempo di risposta: Entro 24 ore
  • Supporto: Lunedì - Venerdì 9:00-18:00

🚀 Aggiornamenti e Versioning

Versione corrente: v1.0

Gli aggiornamenti sono sempre retrocompatibili. Eventuali breaking changes verranno comunicati con almeno 30 giorni di anticipo.

🎯 Pronto per iniziare?

Ottieni la tua API key e integra il sistema loyalty in pochi minuti

Ottieni API Key Contatta il Team