Documentazione API

Benvenuto nella documentazione API di FidelityApp. Queste API RESTful permettono ai software gestionali (es. sistemi di cassa, CRM, gestori di appuntamenti) di comunicare direttamente con il circuito fedeltà del negoziante.

Autenticazione (API Key)

Tutte le richieste API devono essere autenticate. Il negoziante deve generare la propria API Key all'interno dell'app FidelityApp (sezione Configurazione Negozio -> Integrazione API). La chiave deve essere inclusa nell'header HTTP Authorization come Bearer token.

Nota: L'utilizzo delle API è riservato ai negozianti con piano PRO attivo.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxx

Content-Type: application/json

POST

Aggiungi Punti

Questo endpoint permette di inviare l'importo speso da un cliente. Il server calcolerà automaticamente i punti da assegnare in base al tasso di conversione (es. 1€ = 10 punti) impostato dal negoziante nell'app.

URL: https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints

Body Parameters (JSON)

Parametro	Tipo	Obbligatorio	Descrizione
customerId	string	Sì	L'ID univoco del cliente (es. `100456`). Questo codice a 6 cifre viene generato dinamicamente dal QR Code del cliente o può essere digitato manualmente.
amountSpent	number	Sì	L'importo totale speso in valuta locale (es. 25.50). Deve essere maggiore di 0.

Esempio Richiesta

{
  "customerId": "100456",
  "amountSpent": 45.00
}

Esempio Risposta (200 OK)

{
  "success": true,
  "message": "Punti aggiunti con successo",
  "data": {
    "pointsEarned": 45,
    "amountSpent": 45.00
  }
}

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customerId' => '100456',
    'amountSpent' => 45.00
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_live_YOUR_API_KEY",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

const axios = require('axios');

const data = {
  customerId: '100456',
  amountSpent: 45.00
};

axios.post('https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints', data, {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

import requests
import json

url = "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints"
payload = json.dumps({
  "customerId": "100456",
  "amountSpent": 45.00
})
headers = {
  'Authorization': 'Bearer sk_live_YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String json = "{\"customerId\":\"100456\",\"amountSpent\":45.00}";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints"))
            .header("Authorization", "Bearer sk_live_YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints");
        request.Headers.Add("Authorization", "Bearer sk_live_YOUR_API_KEY");
        
        var content = new StringContent("{\"customerId\":\"100456\",\"amountSpent\":45.00}", Encoding.UTF8, "application/json");
        request.Content = content;
        
        var response = await client.SendAsync(request);
        var responseString = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine(responseString);
    }
}

curl -X POST "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiAddPoints" \
     -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"customerId": "100456", "amountSpent": 45.00}'

POST

Invia Notifica Push

Invia una notifica push (promemoria, offerta, ecc.) agli smartphone dei clienti. Puoi inviarla a un singolo cliente specifico oppure a tutto il tuo database clienti in un colpo solo.

URL: https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification

Body Parameters (JSON)

Parametro	Tipo	Obbligatorio	Descrizione
title	string	Sì	Il titolo della notifica.
message	string	Sì	Il testo principale della notifica.
customerId	string	No	Se specificato (es. `100456`), la notifica verrà inviata SOLO a questo cliente. Se omesso, verrà inviata in broadcast a tutti i clienti del negozio.

Esempio Richiesta

{
  "title": "Promemoria Appuntamento",
  "message": "Ti aspettiamo domani alle 15:00!",
  "customerId": "100456"
}

Esempio Risposta (200 OK)

{
  "success": true,
  "message": "Notifica inviata con successo",
  "data": {
    "recipients": 1
  }
}

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Promemoria Appuntamento',
    'message' => 'Ti aspettiamo domani alle 15:00!',
    'customerId' => '100456'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer sk_live_YOUR_API_KEY",
    "Content-Type: application/json"
  ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>

const axios = require('axios');

const data = {
  title: 'Promemoria Appuntamento',
  message: 'Ti aspettiamo domani alle 15:00!',
  customerId: '100456'
};

axios.post('https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification', data, {
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data));

import requests
import json

url = "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification"
payload = json.dumps({
  "title": "Promemoria Appuntamento",
  "message": "Ti aspettiamo domani alle 15:00!",
  "customerId": "100456"
})
headers = {
  'Authorization': 'Bearer sk_live_YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        String json = "{\"title\":\"Promemoria Appuntamento\",\"message\":\"Ti aspettiamo domani alle 15:00!\",\"customerId\":\"100456\"}";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification"))
            .header("Authorization", "Bearer sk_live_YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification");
        request.Headers.Add("Authorization", "Bearer sk_live_YOUR_API_KEY");
        
        var content = new StringContent("{\"title\":\"Promemoria Appuntamento\",\"message\":\"Ti aspettiamo domani alle 15:00!\",\"customerId\":\"100456\"}", Encoding.UTF8, "application/json");
        request.Content = content;
        
        var response = await client.SendAsync(request);
        var responseString = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine(responseString);
    }
}

curl -X POST "https://us-central1-fidelity-app-d561d.cloudfunctions.net/apiSendNotification" \
     -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title": "Promemoria Appuntamento", "message": "Ti aspettiamo domani alle 15:00!", "customerId": "100456"}'

Gestione Errori

Se una richiesta fallisce, l'API restituirà un codice di stato HTTP appropriato e un oggetto JSON contenente i dettagli dell'errore.

{
  "error": "API Key non valida"
}

400 Bad Request: Parametri mancanti o non validi.
401 Unauthorized: API Key mancante o non valida.
403 Forbidden: Il negozio non ha il piano PRO attivo o il cliente ha disattivato le notifiche.
404 Not Found: Il customerId fornito non esiste.
500 Internal Server Error: Errore imprevisto sui nostri server.