WebService

Introduzione

La fatturazione elettronica si sta diffondendo in tutto il mondo e sta diventando velocemente obbligatoria in molti paesi. Billing Extension integra già la fatturazione elettronica italiana e presto anche quella slovena. Anche se vorremmo integrare tutti i paesi, questo è proibitivo.

La fatturazione elettronica differisce enormemente da un paese all'altro a causa delle normative e degli aspetti tecnologici. Volendo mettere le cose in prospettiva, ci sono voluti 4 mesi per completare l'integrazione con l'Italia. Non è semplicemente possibile ripetere lo stesso processo decine di volte. Ci vorrebbero anni.

Invece di lasciare i clienti non italiani e non sloveni ad affrontare da soli la fatturazione elettronica, abbiamo avuto l'idea di includere in Billing Extension un plugin che fornisce tutti i dati necessari all'integrazione tra WHMCS e la fatturazione elettronica di un qualsiasi paese.

Comprendiamo che l'idea di dover completare l'integrazione in autonomia non sia il massimo ma per lo meno c'è qualcosa su cui iniziare a lavorare. Per quella che è la nostra esperienza gran parte del lavoro riguarda la preparazione, convalida ed il recupero dei dati da WHMCS e questo plugin mette già tutto a disposizione.

Sottolineiamo che anche se non si sta creando un'integrazione per la fatturazione elettronica, il plugin piò essere utilizzato anche per diversi altri scopi. Ad esempio si può utilizzare per integrare WHMCS con un software di contabilità o un'intranet.

Per iniziare

Inizia con l'aprire la sezione Plugin (Addons > Billing Extension > Impostazioni e clicca sull'icona col più) ed attiva WebService.

Una volta fatto torna nelle Impostazioni ed espandi la nuova sezione che è stata appena aggiunta. Qui trovi tutte le configurazioni del WebService che al momento prevedono un solo parametro denominato token. Questa stringa generata casualmente viene utilizzata per stabilire una connessione sicura per la trasmissione dei dati. Premi il pulsante arancione per generare il token e poi Salva.



Abbiamo preparato uno script PHP commentato che spiega come interagire con WebService (Download). Questo utilizza lo stesso approccio di WHMCS per le richieste External API tramite libreria curl(). Le risposte sono in formato json. È necessaria una certa conoscenza di PHP.

Autenticazione

Il processo di autenticazione è molto semplice e richiede solo due parametri.

API Get

Nel momento in cui scriviamo questa è l'unica azione supportata che può essere utilizzata per recuperare i dati di fatturazione da WHMCS in base a diversi criteri. Probabilmente aggiungeremo altre azioni dopo aver ricevuto feedback.

Vale la pena evidenziare che i valori del nodo ClientData provengono dagli Snapshot delle fatture e che pertanto sono sicuri da utilizzare per finalità contabili. Inoltre questi sono modificati in modo che non siano presenti spazi all'inizio o alla fine di ogni stringa.

Errori

Abbiamo realizzato il WebService in modo che fosse semplice da utilizzare. In termini pratici quando c'è qualcosa di sbagliato nella richiesta API, il WebService fornisce dettagli chiari sull'errore direttamente nella risposta json. Tali errori non sono criptici ma forniscono una descrizione completa di ciò che è andato storto.

Keyword date

Per quanto riguarda le date, il WebService supporta parole chiave speciali che consentono di filtrare i record per gli intervalli predefiniti elencati nella tabella seguente. Il lunedì è considerato il primo giorno della settimana e le descrizioni fornite presuppongono che la data corrente sia sabato 2019-06-15.