API Piani

🤖 Spiega con l'intelligenza artificiale

L’API Piani è progettata per gestire i piani di abbonamento in modo efficiente. Supporta la creazione di piani, l’elencazione di tutti i piani, il recupero tramite ID, la modifica e l’eliminazione, consentendo una gestione fluida delle iscrizioni.

L’API garantisce risposte chiare e coerenti, inclusa una gestione dettagliata degli errori, per fornire un’esperienza ottimale agli sviluppatori.

Creare un piano¶

Questo endpoint consente di creare un nuovo piano ricorrente nel sistema inviando una richiesta POST con i dettagli del piano, come nome, descrizione, importo, valuta, intervallo (frequenza di fatturazione), trial_period_days e un’immagine opzionale. Se l’operazione ha successo, conferma la creazione del piano e fornisce la sua chiave univoca.

Parametri di query:

Campi del corpo della richiesta:

Richiesta (cURL):

curl -X POST 'https://api.4geeks.io/v1/plans/?test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Premium Plan",
           "description": "Unlimited access to all features",
           "currency": "USD",
           "amount": 9.99,
           "interval": "month",
           "interval_count": 1,
           "trial_period_days": 7,
           "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
         }'

Richiesta (Python):

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.post(
    'https://api.4geeks.io/v1/plans/?test=false',
    headers={
        'Authorization': f'Api-Key {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        "name": "Premium Plan",
        "description": "Unlimited access to all features",
        "currency": "USD",
        "amount": 9.99,
        "interval": "month",
        "interval_count": 1,
        "trial_period_days": 7
    }
)
print(response.json())

Richiesta (Postman):

1. Metodo: POST
2. URL: https://api.4geeks.io/v1/plans/?test=false
3. Autorizzazione: Api-Key con valore sk_test_51O62xYzAbcDef123
4. Corpo (raw JSON):

{
    "name": "Premium Plan",
    "description": "Unlimited access to all features",
    "currency": "USD",
    "amount": 9.99,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 7
}

Risposta (201 Created):

{
    "code": 201,
    "title": "Registrazione completata",
    "content": "La registrazione è stata completata con successo.",
    "type": "success",
    "data": {
        "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
    }
}

Ottenere tutti i piani¶

Questo endpoint recupera un elenco paginato di tutti i piani con supporto per il filtraggio avanzato.

Parametri di query:

Richiesta (Elenca tutti i piani):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&page_size=10&test=false' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Richiesta (Con filtri):

curl -X GET 'https://api.4geeks.io/v1/plans/?page=1&name=premium&price_min=5&price_max=50&status=active' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Risposta (200 OK):

{
  "count": 2,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "key": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
      "information": {
        "name": "Premium Plan",
        "created": "2025-08-17T20:00:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "9.99",
        "trial_period_days": 7,
        "credit_card_description": "PREMIUM",
        "description": "Unlimited access to all features with premium support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 150,
        "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    },
    {
      "key": "a1b2c3d4-5678-90ef-ghij-1234567890cd",
      "information": {
        "name": "Basic Plan",
        "created": "2025-08-17T20:05:00Z",
        "interval": "month",
        "interval_count": 1,
        "currency": "USD",
        "amount": "4.99",
        "trial_period_days": 0,
        "credit_card_description": "BASIC",
        "description": "Limited access to basic features with standard support.",
        "email": "developer@example.com",
        "company_name": "Acme Corp",
        "page": "https://acme.com",
        "active": true,
        "count": 45,
        "image": null,
        "image_dev": "https://acme.com/logo.png"
      },
      "test": false
    }
  ]
}

Ottenere un piano specifico¶

Questo endpoint recupera i dettagli completi di un piano specifico tramite la sua chiave univoca.

Parametri di percorso:

Parametri di query:

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Risposta (200 OK):

{
  "key": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "information": {
    "name": "Standard Plan",
    "created": "2025-03-25T08:50:15.732299Z",
    "interval": "month",
    "interval_count": 1,
    "currency": "USD",
    "amount": "19.99",
    "trial_period_days": 0,
    "credit_card_description": "STANDARD",
    "description": "This plan offers access to standard features with basic support.",
    "email": "developer@example.com",
    "company_name": "Acme Corp",
    "page": "https://acme.com",
    "active": true,
    "count": 75,
    "image": null,
    "image_dev": "https://acme.com/logo.png"
  },
  "test": true
}

Risposta (404 Not Found):

{
  "code": 404,
  "title": "Il piano non esiste",
  "content": "Il piano richiesto non esiste, per favore verifica.",
  "type": "danger"
}

Aggiornare un piano¶

Aggiorna un piano esistente con nuovi dettagli. È possibile aggiornare i singoli campi tra cui nome, descrizione, immagine e giorni del periodo di prova senza influenzare gli altri.

Parametri di percorso:

Parametri di query:

Campi del corpo della richiesta (tutti opzionali):

Richiesta:

curl -X PUT 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Updated Premium Plan",
           "description": "Updated description with full access to features",
           "trial_period_days": 14,
           "is_test": false
         }'

Risposta (200 OK):

{
    "code": 200,
    "title": "Piano aggiornato",
    "content": "Il piano Updated Premium Plan è stato aggiornato correttamente.",
    "type": "success",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Risposta (404 Not Found):

{
    "code": 404,
    "title": "Piano non trovato",
    "content": "Il piano con ID f9b77185-a62e-4da9-a056-3c7b812ca334 non esiste o non hai i permessi per modificarlo.",
    "type": "danger"
}

Risposta (200 - Nessuna modifica):

{
    "code": 200,
    "title": "Nessuna modifica",
    "content": "Non sono state rilevate modifiche al piano.",
    "type": "info",
    "data": "f9b77185-a62e-4da9-a056-3c7b812ca334"
}

Eliminare un piano¶

Elimina definitivamente un piano e tutti gli abbonamenti associati. Quando un piano viene eliminato, tutti i clienti con abbonamenti attivi vengono informati via email.

Parametri di percorso:

Richiesta:

curl -X DELETE 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

Risposta (200 OK):

{
    "code": 200,
    "title": "Piano eliminato",
    "content": "Il piano f9b77185-a62e-4da9-a056-3c7b812ca334 è stato eliminato con successo.",
    "type": "success"
}

Risposta (404 Not Found):

{
    "code": 404,
    "title": "Il piano non esiste",
    "content": "Il piano f9b77185-a62e-4da9-a056-3c7b812ca334 non esiste o è già stato eliminato.",
    "type": "danger"
}

Gestione degli errori¶

L’API restituisce codici di stato HTTP standard per indicare il successo o il fallimento di una richiesta. Di seguito sono riportati gli errori comuni specifici per i piani:

400 Bad Request¶

Si verifica quando la richiesta è malformata o contiene dati non validi.

Scenari:

Esempio di risposta di errore:

{
    "code": 400,
    "title": "Intervallo di prezzo non valido",
    "content": "Il prezzo minimo non può essere superiore al massimo.",
    "type": "warning"
}

401 Unauthorized¶

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempio:

{
    "detail": "Le credenziali di autenticazione non sono state fornite."
}

Soluzione:

• Verifica di aver incluso l’header Authorization: Api-Key sk_test_...
• Assicurati che la tua chiave API sia corretta e attiva
• Testa con Postman utilizzando il metodo di autenticazione Api-Key

404 Not Found¶

Il piano richiesto non esiste.

Esempio:

{
    "code": 404,
    "title": "Il piano non esiste",
    "content": "Il piano richiesto non esiste, per favore verifica.",
    "type": "danger"
}

Soluzione:

• Verifica che la chiave del piano esista
• Usa l’endpoint di elenco per trovare la chiave del piano corretta
• Assicurati che il piano appartenga al tuo account sviluppatore

Note importanti¶

Migliori pratiche¶

1. Nomi chiari dei piani - Usa nomi descrittivi che indichino chiaramente il livello e le funzionalità
2. Descrizioni accurate - Fornisci descrizioni dettagliate di ciò che è incluso in ogni piano
3. Prezzi appropriati - Assicurati che i prezzi siano competitivi e riflettano il valore fornito
4. Periodi di prova - Valuta la possibilità di offrire periodi di prova per ridurre l’attrito nell’acquisizione dei clienti
5. Testa prima della produzione - Usa la modalità test con le chiavi API di test per la validazione
6. Monitora gli abbonati - Usa il conteggio degli abbonati nelle risposte per tracciare l’adozione dei piani
7. Versionamento dei piani - Crea nuovi piani invece di modificare pesantemente quelli esistenti con abbonati
8. Ottimizzazione immagini - Usa immagini ottimizzate per ridurre i tempi di risposta dell’API

Risoluzione dei problemi¶

Problema: “Il piano non esiste”¶

Causa: La chiave del piano non esiste o appartiene a un diverso account sviluppatore
Soluzione: - Verifica la chiave del piano utilizzando l’endpoint di elenco - Assicurati di utilizzare la chiave API corretta - Controlla che il piano non sia stato eliminato

Problema: “Le credenziali di autenticazione non sono state fornite”¶

Causa: Autenticazione con chiave API mancante o non valida
Soluzione: - Usa l’header Authorization: Api-Key sk_test_... nella tua richiesta - Verifica che la tua chiave API sia attiva - Testa con Postman utilizzando l’autenticazione Api-Key

Problema: “Il prezzo minimo non può essere superiore al massimo”¶

Causa: Filtro dell’intervallo di prezzo fornito non valido
Soluzione: - Assicurati che price_min ≤ price_max - Verifica che i valori del filtro siano numeri validi

Problema: “Il piano richiesto non esiste”¶

Causa: I filtri della query non hanno trovato alcun piano
Soluzione: - Verifica che i parametri del filtro siano corretti - Prova a elencare tutti i piani senza filtri - Controlla se il piano esiste in modalità test (regola il parametro test)

FAQ¶

D: Posso cambiare il prezzo di un piano esistente?
A: No, i prezzi del piano sono immutabili. Crea un nuovo piano con il prezzo aggiornato e migra i clienti verso di esso.

D: Cosa succede quando elimino un piano?
A: Tutti gli abbonamenti attivi vengono annullati e i clienti vengono informati. Questa azione non può essere annullata.

D: Posso avere più piani con lo stesso nome?
A: Sì, ma si consiglia di utilizzare nomi univoci per una gestione e un’identificazione più semplici.

D: Quanti piani posso creare?
A: Non c’è limite al numero di piani che puoi creare.

D: Posso aggiornare l’intervallo o il numero di intervalli dopo la creazione?
A: No, questi sono immutabili. Crea un nuovo piano con la frequenza di fatturazione desiderata.

D: Qual è la differenza tra intervallo e numero di intervalli?
A: interval è l’unità (mese, anno), e interval_count è il moltiplicatore (es. ogni 3 mesi = interval=month, interval_count=3).

D: Posso usare lo stesso piano per più prodotti?
A: Sì, i piani sono indipendenti dai prodotti. Un piano rappresenta una configurazione del ciclo di fatturazione.

D: Come faccio a controllare il numero di abbonati attivi per un piano?
A: Usa gli endpoint di elenco o di recupero. Il campo information.count mostra gli abbonamenti attivi.

• Hai ancora domande? Richiedi supporto..
• Check out the changelog.