Vai al contenuto

Come mettere in pausa o cancellare gli abbonamenti dei clienti tramite l'API in 4Geeks Payments

🤖 Spiega con l'intelligenza artificiale

Gestire il ciclo di vita del cliente in modo efficiente è fondamentale per le moderne aziende SaaS e basate su abbonamento. Mentre la 4Geeks Console fornisce un’interfaccia intuitiva per la gestione manuale, il ridimensionamento delle operazioni spesso richiede un controllo programmatico. 4Geeks Payments offre un’API robusta che consente agli sviluppatori di mettere in pausa o annullare gli abbonamenti automaticamente, integrandosi perfettamente con i portali dei clienti o gli strumenti amministrativi interni.

Questo articolo ti guida attraverso i passaggi tecnici per mettere in pausa o annullare gli abbonamenti dei clienti utilizzando l’API 4Geeks Payments, garantendo che la logica di fatturazione rimanga accurata e l’esperienza del cliente fluida.

Prerequisiti

Prima di interagire con l’API, assicurati di avere quanto segue:

  • Account 4Geeks Payments attivo: Devi avere il modulo 4Geeks Payments abilitato sul tuo account.
  • Credenziali API: La tua API Key e il tuo Secret sono necessari per l’autenticazione. Questi possono essere generati nella sezione Developers della 4Geeks Console.
  • ID abbonamento: L’identificativo univoco (subscription_id) per l’abbonamento cliente specifico che desideri modificare.
  • Client API: Uno strumento come Postman, cURL o il tuo linguaggio di programmazione preferito (Python, Node.js, ecc.) per inviare richieste HTTP.

Istruzioni passo-passo

Passaggio 1: Autentica la tua richiesta

Tutte le richieste API a 4Geeks Payments devono essere autenticate per garantire la sicurezza. Ti autenticherai utilizzando un Bearer Token nell’intestazione della tua richiesta.

  1. Individua le tue credenziali API nella scheda Settings > Developers della dashboard.
  2. Includi la seguente intestazione nella tua richiesta HTTP: Authorization: Bearer YOUR_API_KEY

Passaggio 2: Recupera l’ID abbonamento

Per modificare un abbonamento, devi prima identificarlo. Se non hai già l’ID memorizzato nel tuo database, puoi recuperarlo elencando gli abbonamenti per un cliente specifico.

  1. Invia una richiesta GET all’endpoint: https://api.4geeks.io/v1/subscriptions.
  2. Filtra per email del cliente o ID cliente univoco.
  3. Dalla risposta JSON, copia la stringa id (ad es. sub_1a2b3c4d5e).

Passaggio 3: Mettere in pausa un abbonamento

La pausa è ideale per le sospensioni temporanee in cui prevedi che il cliente ritorni. Interrompe il ciclo di fatturazione senza eliminare l’oggetto abbonamento, consentendo una facile riattivazione.

  1. Endpoint: Prepara una richiesta POST a: https://api.4geeks.io/v1/subscriptions/{subscription_id}/pause
  2. Parametri del corpo (Opzionale): Puoi specificare un parametro resume_at (timestamp Unix) se desideri che l’abbonamento si riattivi automaticamente in una data specifica. 
    {
  "resume_at": 1735689600
}
  3. Esegui: Invia la richiesta.
  4. Verifica: L’API restituirà l’oggetto abbonamento con uno stato di paused. Assicurati che il tuo sistema interno aggiorni il livello di accesso dell’utente di conseguenza.

Passaggio 4: Annullamento di un abbonamento

L’annullamento termina definitivamente il ciclo di fatturazione. A seconda della configurazione, ciò può avvenire immediatamente o alla fine del periodo di fatturazione corrente.

  1. Endpoint: Prepara una richiesta DELETE (o POST, a seconda della configurazione specifica) a: https://api.4geeks.io/v1/subscriptions/{subscription_id}/cancel
  2. Parametri del corpo:
    • cancel_at_period_end (booleano): Imposta su true per consentire al cliente di terminare il mese per cui ha già pagato. Imposta su false per la revoca immediata. 
      {
  "cancel_at_period_end": true
}
  3. Esegui: Invia la richiesta.
  4. Verifica: L’API restituisce l’oggetto con uno stato di canceled (o active con un timestamp cancel_at se hai scelto di annullare alla fine del periodo).

Casi d’uso comuni

Scenario 1: La “Sospensione stagionale”

Situazione: Gestisci una piattaforma educativa utilizzando 4Geeks Payments e uno studente vuole congelare il proprio account durante le vacanze estive invece di annullarlo del tutto. Applicazione: Il tuo portale studenti attiva l’endpoint Pause (/pause) con una data resume_at impostata per il 1° settembre. Risultato: La fatturazione si interrompe immediatamente. Il 1° settembre, l’API riattiva automaticamente l’abbonamento e tenta di acquisire il pagamento, trattenendo il cliente senza intervento manuale.

Scenario 2: Gestione automatizzata dell’abbandono

Situazione: Un cliente clicca su “Cancella account” nella tua dashboard SaaS. Applicazione: Il tuo backend attiva l’endpoint Cancel (/cancel) con cancel_at_period_end: true. Risultato: Il cliente mantiene l’accesso fino alla scadenza del termine pagato. 4Geeks Payments garantisce che non vengano generate ulteriori fatture e lo stato dell’abbonamento passa infine a canceled automaticamente, mantenendo accurati i tuoi registri finanziari.

Risoluzione dei problemi

Problema 1: Errore 401 Unauthorized

  • Causa: La tua API Key è mancante, errata o scaduta.
  • Soluzione: Controlla l’intestazione Authorization. Rigenera le tue chiavi nella 4Geeks Console se necessario.

Problema 2: 404 Not Found

  • Causa: Il subscription_id fornito non esiste o appartiene a un ambiente diverso (ad es. Sandbox vs. Produzione).
  • Soluzione: Verifica che l’ID corrisponda all’ambiente che stai interrogando. Assicurati di non tentare di accedere a un ID Live nell’ambiente Sandbox.

Problema 3: Conflitto di stato dell’abbonamento (409)

  • Causa: Stai tentando di mettere in pausa un abbonamento che è già stato annullato o di annullare un abbonamento che è già in pausa senza riattivarlo prima.
  • Soluzione: Controlla sempre il campo status dell’oggetto abbonamento tramite una richiesta GET prima di tentare una modifica di stato per assicurarti che l’azione sia valida.

Conclusione

L’automazione della gestione degli abbonamenti tramite l’API consente alla tua azienda di gestire le basi clienti in crescita con precisione. Integrando la logica di pausa e annullamento direttamente nelle tue applicazioni, riduci il carico di lavoro sul personale di supporto e offri un’esperienza più fluida ai tuoi utenti.

Per configurazioni più avanzate, come la gestione della ripartizione proporzionale durante le cancellazioni o l’impostazione di webhook per le modifiche di stato, esplora la Documentazione per sviluppatori nella 4Geeks Console.