API Reference v3.0.3
Base URL
Headers comuni
Tutte le richieste devono includere:
Autenticazione
POST /auth/login
Ottieni un token di accesso.
Request Body:
Response (200):
{
"access_token": "string",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "string",
"scope": "string"
}
POST /auth/refresh
Rinnova un token scaduto.
Request Body:
POST /auth/logout
Invalida il token corrente.
Beneficiari
GET /beneficiaries
Recupera lista beneficiari con paginazione.
Query Parameters:
- page (integer): Numero pagina (default: 1)
- per_page (integer): Elementi per pagina (max: 100, default: 20)
- search (string): Ricerca per nome/cognome
- status (string): Filtra per stato (active, inactive, pending)
- created_from (date): Data creazione da (YYYY-MM-DD)
- created_to (date): Data creazione a (YYYY-MM-DD)
Response (200):
{
"data": [
{
"id": 1,
"first_name": "Mario",
"last_name": "Rossi",
"email": "mario.rossi@email.com",
"phone": "+39 123 456 7890",
"status": "active",
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T10:30:00Z"
}
],
"meta": {
"current_page": 1,
"total_pages": 5,
"total_count": 95,
"per_page": 20
},
"links": {
"first": "/v3/beneficiaries?page=1",
"last": "/v3/beneficiaries?page=5",
"prev": null,
"next": "/v3/beneficiaries?page=2"
}
}
GET /beneficiaries/{id}
Recupera dettagli di un beneficiario specifico.
Path Parameters:
- id (integer): ID del beneficiario
Response (200):
{
"id": 1,
"first_name": "Mario",
"last_name": "Rossi",
"email": "mario.rossi@email.com",
"phone": "+39 123 456 7890",
"date_of_birth": "1985-03-20",
"fiscal_code": "RSSMRA85C20H501X",
"address": {
"street": "Via Roma 123",
"city": "Milano",
"postal_code": "20100",
"country": "IT"
},
"status": "active",
"metadata": {
"source": "web_form",
"campaign_id": "summer2023"
},
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T10:30:00Z"
}
POST /beneficiaries
Crea un nuovo beneficiario.
Request Body:
{
"first_name": "Mario",
"last_name": "Rossi",
"email": "mario.rossi@email.com",
"phone": "+39 123 456 7890",
"date_of_birth": "1985-03-20",
"fiscal_code": "RSSMRA85C20H501X",
"address": {
"street": "Via Roma 123",
"city": "Milano",
"postal_code": "20100",
"country": "IT"
},
"metadata": {
"source": "api",
"notes": "Registrato tramite integrazione"
}
}
Response (201):
{
"id": 123,
"first_name": "Mario",
"last_name": "Rossi",
"email": "mario.rossi@email.com",
"status": "pending",
"created_at": "2023-12-01T14:30:00Z"
}
PUT /beneficiaries/{id}
Aggiorna un beneficiario esistente.
Path Parameters:
- id (integer): ID del beneficiario
Request Body: (stesso formato di POST, tutti i campi opzionali)
DELETE /beneficiaries/{id}
Elimina un beneficiario.
Response (204): Nessun contenuto
Gestione errori
Formato errore standard
{
"error": "validation_failed",
"message": "I dati forniti non sono validi",
"code": 422,
"details": [
{
"field": "email",
"message": "Il formato email non è valido"
}
]
}
Codici di stato
| Codice | Significato | Descrizione |
|---|---|---|
| 200 | OK | Richiesta completata con successo |
| 201 | Created | Risorsa creata con successo |
| 204 | No Content | Richiesta completata, nessun contenuto |
| 400 | Bad Request | Richiesta malformata |
| 401 | Unauthorized | Token mancante o non valido |
| 403 | Forbidden | Accesso negato |
| 404 | Not Found | Risorsa non trovata |
| 422 | Unprocessable Entity | Errori di validazione |
| 429 | Too Many Requests | Rate limit superato |
| 500 | Internal Server Error | Errore del server |
Rate Limiting
Limiti
- Standard endpoints: 100 richieste/minuto
- Create/Update operations: 10 richieste/minuto
- Authentication: 5 tentativi/minuto per IP
Headers di risposta
Gestione 429 Too Many Requests
{
"error": "rate_limit_exceeded",
"message": "Troppe richieste. Riprova tra 60 secondi",
"code": 429,
"retry_after": 60
}
Paginazione
Tutti gli endpoint che restituiscono liste utilizzano paginazione basata su offset:
Parametri query
page: Numero pagina (start da 1)per_page: Elementi per pagina (max 100)