Documentazione API

API REST per integrare il software di cassa (gestionale) col programma fedeltà. Tutte le operazioni cliente avvengono tramite il numero/codice a barre della card fisica.

Autenticazione (API key)

Ogni richiesta va autenticata con una API key generata dal negoziante nel pannello admin Shopify (sezione API key gestionale), inviata nell'header Authorization come Bearer token.

Base URL: https://fidelityapp-loyalty.appteam.it/app/api/v1

Authorization: Bearer fid_live_xxxxxxxxxxxxxxxxx

Content-Type: application/json

POST

/accounts

Iscrizione: assegna una card al cliente, oppure la collega a un conto online esistente via email/telefono. cardNumber è obbligatorio se il negozio usa card pre-stampate; se omesso e il negozio usa generazione automatica, viene creato un numero.

Body parameters (JSON)

Parametro	Tipo	Obbligatorio	Descrizione
cardNumber	string	No*	Numero/barcode della card fisica. *Obbligatorio se il negozio usa card pre-stampate.
email	string	No	Collega la card a un conto online esistente con la stessa email.
phone	string	No	Telefono del cliente, identificazione alternativa.

curl -X POST https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts \
  -H "Authorization: Bearer fid_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "000123456789",
    "email": "cliente@esempio.it",
    "phone": "+393331234567"
  }'

const axios = require('axios');

await axios.post('https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts', {
  cardNumber: '000123456789',
  email: 'cliente@esempio.it',
  phone: '+393331234567'
}, {
  headers: { Authorization: 'Bearer fid_live_xxxxxxxx' }
});

$ch = curl_init('https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer fid_live_xxxxxxxx',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'cardNumber' => '000123456789',
    'email' => 'cliente@esempio.it',
    'phone' => '+393331234567',
  ]),
]);
echo curl_exec($ch);

Risposta

201 Created
{
  "cardNumber": "000123456789",
  "email": "cliente@esempio.it",
  "phone": "+393331234567",
  "pointsBalance": 0
}

GET

/accounts/{cardNumber}

Lookup saldo: punti disponibili e valore in € spendibile come sconto.

curl https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789 \
  -H "Authorization: Bearer fid_live_xxxxxxxx"

const { data } = await axios.get(
  'https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789',
  { headers: { Authorization: 'Bearer fid_live_xxxxxxxx' } }
);

$ch = curl_init('https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer fid_live_xxxxxxxx'],
]);
echo curl_exec($ch);

Risposta

200 OK
{
  "cardNumber": "000123456789",
  "pointsBalance": 340,
  "valueAvailable": 15
}

GET

/accounts/{cardNumber}/transactions

Storico movimenti del conto, più recenti prima. Query string opzionali: limit (default 50, max 200) e before (cursore data).

curl "https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789/transactions?limit=20" \
  -H "Authorization: Bearer fid_live_xxxxxxxx"

const { data } = await axios.get(
  'https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789/transactions',
  { params: { limit: 20 }, headers: { Authorization: 'Bearer fid_live_xxxxxxxx' } }
);

$ch = curl_init('https://fidelityapp-loyalty.appteam.it/app/api/v1/accounts/000123456789/transactions?limit=20');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer fid_live_xxxxxxxx'],
]);
echo curl_exec($ch);

Risposta

200 OK
{
  "transactions": [
    {
      "id": "cl9...",
      "type": "EARN",
      "channel": "POS",
      "points": 25,
      "reason": "Accumulo vendita SCONTRINO-00123",
      "orderId": null,
      "refundId": null,
      "externalRef": "SCONTRINO-00123",
      "createdAt": "2026-06-27T10:15:00.000Z"
    }
  ]
}

POST

/earn

Accumulo punti per una vendita in negozio. externalRef è l'identificativo univoco della transazione cassa: stesso externalRef in chiamate successive non genera doppio accredito (idempotenza).

curl -X POST https://fidelityapp-loyalty.appteam.it/app/api/v1/earn \
  -H "Authorization: Bearer fid_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "000123456789",
    "externalRef": "SCONTRINO-00123",
    "amount": 25.90
  }'

await axios.post('https://fidelityapp-loyalty.appteam.it/app/api/v1/earn', {
  cardNumber: '000123456789',
  externalRef: 'SCONTRINO-00123',
  amount: 25.90
}, { headers: { Authorization: 'Bearer fid_live_xxxxxxxx' } });

$ch = curl_init('https://fidelityapp-loyalty.appteam.it/app/api/v1/earn');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer fid_live_xxxxxxxx',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'cardNumber' => '000123456789',
    'externalRef' => 'SCONTRINO-00123',
    'amount' => 25.90,
  ]),
]);
echo curl_exec($ch);

Risposta

200 OK
{
  "externalRef": "SCONTRINO-00123",
  "pointsEarned": 25
}

POST

/redeem

Riscatto punti: scala i punti dal conto e restituisce il valore in € da applicare come riga di sconto sullo scontrino. points deve essere un multiplo del blocco di riscatto configurato. saleAmount (opzionale) abilita il controllo sul tetto massimo % del carrello.

curl -X POST https://fidelityapp-loyalty.appteam.it/app/api/v1/redeem \
  -H "Authorization: Bearer fid_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "000123456789",
    "externalRef": "SCONTRINO-00124",
    "points": 100,
    "saleAmount": 40.00
  }'

await axios.post('https://fidelityapp-loyalty.appteam.it/app/api/v1/redeem', {
  cardNumber: '000123456789',
  externalRef: 'SCONTRINO-00124',
  points: 100,
  saleAmount: 40.00
}, { headers: { Authorization: 'Bearer fid_live_xxxxxxxx' } });

$ch = curl_init('https://fidelityapp-loyalty.appteam.it/app/api/v1/redeem');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer fid_live_xxxxxxxx',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'cardNumber' => '000123456789',
    'externalRef' => 'SCONTRINO-00124',
    'points' => 100,
    'saleAmount' => 40.00,
  ]),
]);
echo curl_exec($ch);

Risposta

200 OK
{
  "externalRef": "SCONTRINO-00124",
  "pointsRedeemed": 100,
  "discountValue": 5
}

Gestione errori

In caso di errore l'API risponde sempre con questo formato JSON:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key non valida o revocata"
  }
}

400 Bad Request: parametri mancanti o non validi (es. punti non multipli del blocco).
401 Unauthorized: API key mancante, non valida o revocata.
403 Forbidden: programma fedeltà disattivato per questo negozio.
404 Not Found: il cardNumber fornito non esiste.
409 Conflict: la card è già assegnata a un altro conto.
429 Too Many Requests: limite di richieste superato, riprova più tardi.
500 Internal Server Error: errore imprevisto sui nostri server.