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.
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
Attiva l'IAP, copia la tua API key e fai la prima chiamata in 2 minuti.
Autenticazione
Bearer token o query api_key, con parametro ID sempre richiesto.
Endpoints
Lettura soci, dettaglio per barcode, gruppi notifica e altro.
Gestione errori
Codici HTTP standard e payload con code e error descrittivi.
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...
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:
- La API key — via header
Authorization(raccomandato) o query string. - Il parametro query
ID— il tuoIDEsercente(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"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
| Status | Significato | Quando succede |
|---|---|---|
200 | OK | Richiesta riuscita. |
400 | Bad Request | Parametri mancanti o malformati (es. ID non valorizzato). |
401 | Unauthorized | API key mancante o non valida per l'associazione indicata. |
403 | Forbidden | API non ancora attivate per questa associazione. |
404 | Not Found | Risorsa inesistente (es. barcode non trovato nel tenant). |
429 | Too Many Requests | Rate limit superato. |
500 | Server Error | Errore interno. Segnalalo al supporto con timestamp e code. |
Codici errore applicativi
| Codice | Descrizione |
|---|---|
UNAUTHORIZED | Token mancante, errato, o associazione non trovata. |
BAD_REQUEST | Parametri richiesta non validi. |
API_NOT_ENABLED | L'associazione non ha acquistato l'IAP API Connect. |
NOT_FOUND | Risorsa richiesta inesistente. |
RATE_LIMIT | Limite 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.
.phpAttualmente 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
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
IDEsercente (identificativo associazione).1.50, massimo 500.ATTIVA, SCADUTA, REVOCATA, ND.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(){
"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
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
17766139196727864).Query parameters
IDEsercente.Per sapere se una tessera è attiva, controlla stato === "ATTIVA". Gli stati possibili sono ATTIVA, SCADUTA, REVOCATA, ND (non attivata).
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']}"){
"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"
}
}
}{
"status": "KO",
"error": "Tessera non trovata per questa associazione",
"code": "NOT_FOUND"
}Gruppi notifica
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
IDEsercente.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']{
"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
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 email → email_utente, nome → first_name, cognome → last_name:
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(){
"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:
- Apri Postman → Import → Raw Text.
- Incolla il blocco qui sotto.
- 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
| Versione | Data | Novità |
|---|---|---|
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. |
Per bug, feature request o aumento del rate limit, scrivi a supporto@wallyfor.com. Il team AI-Team risponde tipicamente entro 24h lavorative.