W Wallyfor API v1.0

Wallyfor API v1.0

API REST per integrare Wallyfor nei tuoi sistemi: leggi l'anagrafica soci, interroga gruppi, registra nuovi tesserati dal tuo form. JSON pulito, autenticazione semplice, rate limit trasparente.

Base URLhttps://wallyfor.com/auto/api/1_0
Versione1.0
Formatoapplication/json

L'API Wallyfor ti permette di connettere la tua piattaforma di tesseramento associativo a sistemi esterni — biglietteria eventi, CRM, app mobile custom, sito WordPress, gestionali. Tutte le risposte sono JSON, tutti gli endpoint sono autenticati con una API key per tenant.

Getting started

Per iniziare ad usare l'API hai bisogno di due cose: un'associazione Wallyfor con le API abilitate, e la tua API key.

1. Attivazione

Le API si attivano come acquisto In-App dall'app Wallyfor su iOS o Android. Dopo la validazione del pagamento ottieni un token con prefisso wf_live_ pronto all'uso.

2. Recupera la tua API key

Dal pannello API Connect (sidebar Wallyfor) trovi la tua API key di lettura nella sezione "Lettura dati — API v1.0". Il formato è:

wf_live_a1b2c3d4e5f6...
⚠️ Non esporre mai la tua API key lato client

Trattala come una password. Non inserirla in codice JavaScript di un sito pubblico né in app mobile distribuite. Per integrazioni server-to-server conservala in variabili d'ambiente o vault.

3. La tua prima chiamata

Prova subito a recuperare la tua prima pagina di soci. Sostituisci TUA_API_KEY e TUO_ID con i tuoi valori.

curl -H "Authorization: Bearer TUA_API_KEY" \
  "https://wallyfor.com/auto/api/1_0/passes.php?ID=TUO_ID&perPage=5"
<?php
$ch = curl_init('https://wallyfor.com/auto/api/1_0/passes.php?ID=TUO_ID&perPage=5');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer TUA_API_KEY']);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);
const res = await fetch(
  'https://wallyfor.com/auto/api/1_0/passes.php?ID=TUO_ID&perPage=5',
  { headers: { 'Authorization': 'Bearer TUA_API_KEY' } }
);
const data = await res.json();
console.log(data);
import requests

r = requests.get(
    'https://wallyfor.com/auto/api/1_0/passes.php',
    params={'ID': 'TUO_ID', 'perPage': 5},
    headers={'Authorization': 'Bearer TUA_API_KEY'}
)
print(r.json())

Autenticazione

Ogni richiesta deve includere due elementi:

  1. La API key — via header Authorization (raccomandato) o query string.
  2. Il parametro query ID — il tuo IDEsercente (identificativo associazione). Richiesto sempre, anche con header, per garantire isolamento multi-tenant.

Metodo 1 — Header Authorization (raccomandato)

curl -H "Authorization: Bearer wf_live_xxx..." \
  "https://wallyfor.com/auto/api/1_0/passes.php?ID=123"

Metodo 2 — Query string (per test rapidi)

curl "https://wallyfor.com/auto/api/1_0/passes.php?api_key=wf_live_xxx...&ID=123"
💡 Prefissi dei token

Gli ambienti Wallyfor usano prefissi diversi per riconoscere i token a colpo d'occhio: wf_live_ (produzione) e in futuro wf_test_ (sandbox). Se il token non inizia con wf_live_ non è una chiave di produzione.


Rate limit

Ogni coppia (token, IDEsercente) può effettuare fino a 1000 richieste/ora. Al superamento del limite ricevi un errore HTTP 429 con header Retry-After: 3600.

{
  "status": "KO",
  "error": "Superato il limite di 1000 richieste/ora. Riprova tra un'ora.",
  "code": "RATE_LIMIT"
}

Se hai bisogno di un limite più alto (es. migrazione massiva soci), contattaci a supporto@wallyfor.com.


Gestione errori

Tutte le risposte di errore hanno una struttura uniforme:

{
  "status": "KO",
  "error": "Descrizione leggibile del problema",
  "code": "ERROR_CODE_MACCHINA"
}

Status code HTTP

StatusSignificatoQuando succede
200OKRichiesta riuscita.
400Bad RequestParametri mancanti o malformati (es. ID non valorizzato).
401UnauthorizedAPI key mancante o non valida per l'associazione indicata.
403ForbiddenAPI non ancora attivate per questa associazione.
404Not FoundRisorsa inesistente (es. barcode non trovato nel tenant).
429Too Many RequestsRate limit superato.
500Server ErrorErrore interno. Segnalalo al supporto con timestamp e code.

Codici errore applicativi

CodiceDescrizione
UNAUTHORIZEDToken mancante, errato, o associazione non trovata.
BAD_REQUESTParametri richiesta non validi.
API_NOT_ENABLEDL'associazione non ha acquistato l'IAP API Connect.
NOT_FOUNDRisorsa richiesta inesistente.
RATE_LIMITLimite orario raggiunto.

Endpoints v1.0

L'API v1.0 espone tre endpoint di lettura e un endpoint di scrittura (configurabile via wizard). Tutti sono pensati per essere idempotenti e sicuri da chiamare.

⚠️ URL con estensione .php

Attualmente gli endpoint sono accessibili tramite il file PHP diretto (passes.php, groups.php). L'URL "rewriting" in stile REST sarà attivato in futuro.

Lista soci

GET/passes.php

Restituisce l'elenco paginato dei soci dell'associazione, con filtri opzionali per stato, gruppo, email o telefono. Tipico uso: sincronizzazione periodica con CRM esterno, export anagrafica.

Query parameters

IDrequiredinteger
Il tuo IDEsercente (identificativo associazione).
pageoptionalinteger
Numero della pagina. Default: 1.
perPageoptionalinteger
Risultati per pagina. Default 50, massimo 500.
statooptionalstring
Filtra per stato tessera: ATTIVA, SCADUTA, REVOCATA, ND.
gruppooptionalinteger
ID del gruppo notifica (vedi /groups.php).
emailoptionalstring
Match parziale sull'indirizzo email.
teloptionalstring
Match parziale sul numero di telefono.
Richiesta
curl -H "Authorization: Bearer wf_live_..." \
  "https://wallyfor.com/auto/api/1_0/passes.php?ID=123&stato=ATTIVA&page=1&perPage=50"
<?php
$params = http_build_query(['ID'=>123, 'stato'=>'ATTIVA', 'page'=>1, 'perPage'=>50]);
$ch = curl_init("https://wallyfor.com/auto/api/1_0/passes.php?$params");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer wf_live_...']);
$data = json_decode(curl_exec($ch), true);
const url = new URL('https://wallyfor.com/auto/api/1_0/passes.php');
url.search = new URLSearchParams({ID:123,stato:'ATTIVA',page:1,perPage:50});
const res = await fetch(url, {
  headers: {'Authorization':'Bearer wf_live_...'}
});
const data = await res.json();
import requests
r = requests.get(
    'https://wallyfor.com/auto/api/1_0/passes.php',
    params={'ID':123,'stato':'ATTIVA','page':1,'perPage':50},
    headers={'Authorization':'Bearer wf_live_...'}
)
data = r.json()
Risposta 200 OK
{
  "status": "OK",
  "pagination": {
    "page": 1,
    "perPage": 50,
    "total": 342,
    "totalPages": 7
  },
  "data": [
    {
      "barcode": "17766139196727864",
      "nome": "Mario",
      "cognome": "Rossi",
      "email": "mario.rossi@example.com",
      "telefono": "+393331234567",
      "stato": "ATTIVA",
      "scadenza": "31-12-2026",
      "data_prima_iscrizione": "2024-03-12",
      "gruppo": {
        "id": 7,
        "nome": "Soci ordinari",
        "colore_sfondo": "#4788ff",
        "colore_scritte": "#ffffff"
      }
    }
  ]
}

Dettaglio socio

GET/passes.php?barcode={barcode}

Restituisce il dettaglio completo di un singolo socio identificato dal barcode della tessera. Tipico uso: sistemi di check-in eventi, validazione al gate, verifica validità tessera.

Path parameters

barcoderequiredstring
Il barcode della tessera socio (es. 17766139196727864).

Query parameters

IDrequiredinteger
Il tuo IDEsercente.
💡 Verifica rapida validità

Per sapere se una tessera è attiva, controlla stato === "ATTIVA". Gli stati possibili sono ATTIVA, SCADUTA, REVOCATA, ND (non attivata).

Richiesta
curl -H "Authorization: Bearer wf_live_..." \
  "https://wallyfor.com/auto/api/1_0/passes.php?barcode=17766139196727864&ID=123"
<?php
$barcode = '17766139196727864';
$ch = curl_init("https://wallyfor.com/auto/api/1_0/passes.php?barcode=$barcode&ID=123");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer wf_live_...']);
$response = json_decode(curl_exec($ch), true);
if ($response['status'] === 'OK') {
    $pass = $response['data'];
    echo "Socio {$pass['nome']} {$pass['cognome']} — stato: {$pass['stato']}";
}
const barcode = '17766139196727864';
const res = await fetch(
  `https://wallyfor.com/auto/api/1_0/passes.php?barcode=${barcode}&ID=123`,
  { headers: {'Authorization':'Bearer wf_live_...'} }
);
const { status, data } = await res.json();
if (status === 'OK' && data.stato === 'ATTIVA') {
  console.log('Tessera valida per', data.nome, data.cognome);
}
import requests
barcode = '17766139196727864'
r = requests.get(
    'https://wallyfor.com/auto/api/1_0/passes.php',
    params={'ID':123, 'barcode':barcode},
    headers={'Authorization':'Bearer wf_live_...'}
)
resp = r.json()
if resp['status'] == 'OK' and resp['data']['stato'] == 'ATTIVA':
    print(f"Valida: {resp['data']['nome']} {resp['data']['cognome']}")
Risposta 200 OK
{
  "status": "OK",
  "data": {
    "barcode": "17766139196727864",
    "nome": "Mario",
    "cognome": "Rossi",
    "email": "mario.rossi@example.com",
    "telefono": "+393331234567",
    "stato": "ATTIVA",
    "scadenza": "31-12-2026",
    "data_prima_iscrizione": "2024-03-12",
    "gruppo": {
      "id": 7,
      "nome": "Soci ordinari",
      "colore_sfondo": "#4788ff",
      "colore_scritte": "#ffffff"
    }
  }
}
Se non trovato 404
{
  "status": "KO",
  "error": "Tessera non trovata per questa associazione",
  "code": "NOT_FOUND"
}

Gruppi notifica

GET/groups.php

Restituisce l'elenco dei gruppi notifica configurati per la tua associazione. I gruppi permettono di classificare i soci (es. "Ordinari", "Sostenitori", "Minorenni") con colori e quote dedicate, e di inviare messaggi push segmentati.

Query parameters

IDrequiredinteger
Il tuo IDEsercente.
Richiesta
curl -H "Authorization: Bearer wf_live_..." \
  "https://wallyfor.com/auto/api/1_0/groups.php?ID=123"
<?php
$ch = curl_init('https://wallyfor.com/auto/api/1_0/groups.php?ID=123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer wf_live_...']);
$groups = json_decode(curl_exec($ch), true)['data'];
const res = await fetch(
  'https://wallyfor.com/auto/api/1_0/groups.php?ID=123',
  { headers: {'Authorization':'Bearer wf_live_...'} }
);
const { data: groups } = await res.json();
import requests
r = requests.get(
    'https://wallyfor.com/auto/api/1_0/groups.php',
    params={'ID':123},
    headers={'Authorization':'Bearer wf_live_...'}
)
groups = r.json()['data']
Risposta 200 OK
{
  "status": "OK",
  "data": [
    {
      "id": 7,
      "nome": "Soci ordinari",
      "colore_sfondo": "#4788ff",
      "colore_scritte": "#ffffff",
      "prezzo": "25.00",
      "durata": 12,
      "benefit_descrizione": "Accesso eventi + newsletter"
    },
    {
      "id": 12,
      "nome": "Sostenitori",
      "colore_sfondo": "#ffc107",
      "colore_scritte": "#212529",
      "prezzo": "100.00",
      "durata": 12,
      "benefit_descrizione": "Accesso eventi + gadget + nominativi programma"
    }
  ]
}

Registrazione nuovo socio

POST/connect/v1/members

Registra un nuovo socio nella tua associazione a partire dai dati del tuo form. La mappatura tra i campi del tuo form e i campi Wallyfor è configurata dalla dashboard API Connect (wizard): qui definisci quali campi mappare, eventuali trasformazioni (uppercase, conversione data, prefisso telefonico) e valori di default.

Modalità supportate

  • Direct: il socio viene creato subito come attivo, tessera generata e push pass inviato.
  • Pending: il socio viene messo in coda di approvazione manuale dall'admin Wallyfor prima di essere attivato.

Autenticazione

Per questo endpoint usa il token dedicato generato dal wizard (diverso dalla API key di lettura). Lo trovi nel pannello API Connect nella sezione "Token API wizard".

Body della richiesta

JSON con i nomi dei campi del tuo form (così come definiti nella mappatura). Esempio se hai mappato emailemail_utente, nomefirst_name, cognomelast_name:

Richiesta
curl -X POST https://wallyfor.com/connect/v1/members \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "IL_TUO_TOKEN_WIZARD",
    "email_utente": "mario.rossi@example.com",
    "first_name": "Mario",
    "last_name": "Rossi",
    "cellulare": "3331234567",
    "data_nascita": "15/01/1990"
  }'
<?php
$payload = [
    'api_token' => 'IL_TUO_TOKEN_WIZARD',
    'email_utente' => 'mario.rossi@example.com',
    'first_name' => 'Mario',
    'last_name' => 'Rossi',
    'cellulare' => '3331234567',
    'data_nascita' => '15/01/1990',
];
$ch = curl_init('https://wallyfor.com/connect/v1/members');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
$response = json_decode(curl_exec($ch), true);
const res = await fetch('https://wallyfor.com/connect/v1/members', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_token: 'IL_TUO_TOKEN_WIZARD',
    email_utente: 'mario.rossi@example.com',
    first_name: 'Mario',
    last_name: 'Rossi',
    cellulare: '3331234567',
    data_nascita: '15/01/1990'
  })
});
const data = await res.json();
import requests
payload = {
    'api_token': 'IL_TUO_TOKEN_WIZARD',
    'email_utente': 'mario.rossi@example.com',
    'first_name': 'Mario',
    'last_name': 'Rossi',
    'cellulare': '3331234567',
    'data_nascita': '15/01/1990',
}
r = requests.post('https://wallyfor.com/connect/v1/members', json=payload)
data = r.json()
Risposta 200 OK
{
  "success": true,
  "message": "Socio registrato con successo",
  "data": {
    "mode": "direct",
    "member_id": 52341,
    "barcode": "17766139196727864",
    "mapped_fields": {
      "email": "mario.rossi@example.com",
      "nome": "Mario",
      "cognome": "Rossi",
      "telefono": "3331234567",
      "compleanno": "1990-01-15"
    }
  }
}

Collection Postman

Per testare velocemente gli endpoint puoi importare questa richiesta in Postman:

  1. Apri Postman → ImportRaw Text.
  2. Incolla il blocco qui sotto.
  3. Imposta le variabili di ambiente {{wf_base}}, {{wf_api_key}}, {{wf_id}}.
curl -H "Authorization: Bearer {{wf_api_key}}" \
  "{{wf_base}}/passes.php?ID={{wf_id}}&perPage=10"

Changelog

VersioneDataNovità
1.0.0 2026-04-18 Release iniziale. Endpoint GET /passes, GET /passes/{barcode}, GET /groups. Autenticazione Bearer + query, rate limit 1000/h, audit log su API_esterne.
🤝 Supporto

Per bug, feature request o aumento del rate limit, scrivi a supporto@wallyfor.com. Il team AI-Team risponde tipicamente entro 24h lavorative.