WebService

WebService

Indietro   Pubblicato 15 giugno 2019 / Aggiornato 15 ottobre 2019
Tempo di lettura 5 minuti

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.

ParametroDescrizioneObbligatorio
$URL L'URL della root di WHMCS che può essere trovato in Setup > General Settings > General > WHMCS SystemURL. Lo slash "/" finale è obbligatorio. Obbligatorio
$Token Deve essere uguale a quello che hai in Addons > Billing Extension > Impostazioni > WebService > Token Obbligatorio

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.

Parametri per la richiesta
ParametroDescrizioneObbligatorio
action “Get“ Obbligatorio
start Data di inizio per la selezione dei risultati. Supporta le date in formato YYYY-MM-DD, numeri interi (5 per recuperare gli ultimi 5 giorni) e keyword (yesterday, month to date, last year etc.). Lascia vuoto per selezionare tutte le fatture Opzionale
end Se “start“ è stato specificato in formato data, “end“ può essere utilizzato per selezionare le fatture in un range di date (es. da 2019-06-01 a 2019-06-15). YYYY-MM-DD è l'unico formato supportato. Opzionale
invoicenum Seleziona la fattura con questo specifico numero. Se in uso, i valori “start“ e “end“ sono ignorati. Non può essere utilizzato insieme a “invoiceid“ Opzionale
invoiceid Seleziona la fattura con questo specifico ID. Deve essere un numero intero. Se in uso, i valori “start“ e “end“ sono ignorati. Non può essere utilizzato insieme a “invoicenum“ Opzionale
doctype “Invoice“ e “CreditNote“ restituiscono rispettivamente fatture e note di credito. Se vuoto, vengono restituiti entrambi i tipi Opzionale
Paremetri di risposta
NodoParametroDescrizione
ClientData UserID User ID (tblclients.id)
ClientData ClientData Nome (es. “Jack“)
ClientData Lastname Cognome (es. “Black“)
ClientData ClientName Nome e cognome separati da uno spazio (es. “Jack Black“)
ClientData CompanyName Nome azienda
ClientData Email Email
ClientData Address1 Indirizzo 1
ClientData Address2 Indirizzo 2
ClientData City Città
ClientData State Stato, regione, provincia
ClientData PostCode CAP
ClientData Country ISO paese in formato da 2 lettere (es. IT, DE, ES)
ClientData PhoneNumber Numero di telefono
ClientData Currency ID valuta del cliente selezionato
ClientData TaxExempt “1“ esente da tasse. “0“ non esente da tasse
ClientData\CustomFields id ID Custom Field cliente (tblcustomfields.id)
ClientData\CustomFields fieldname Nome Custom Field cliente (eg. VAT Number)
ClientData\CustomFields value Valore Custom Field cliente
ClientData\Europe MemberState ISO paese in formato da 2 lettere (es. IT, DE, ES)
ClientData\Europe Region Principalmente “Europe“ ma può essere anche uguale a “South-America“, “Africa“ ecc. per i territori ultraperiferici e d'oltremare dell'Unione Europea
ClientData\Europe MonetaryUnion true/false (es. Italia “true“, Danimarca “false“)
ClientData\Europe VIES true/false. Se “true“ il cliente selezionato è un'azienda Intra-EU iscritta al VIES
ClientData\Europe MOSS true/false
DocData Type “Invoice“ o “CreditNote“
DocData ID ID documento (tblinvoices.id)
DocData Num Numero documento (eg. 2019-150)
DocData Status Stato fattura (“Paid“, “Draft“, “Unpaid“ ecc.)
DocData Date Data in formato YYYY-MM-DD
DocData DueDate Data scadenza in formato YYYY-MM-DD
DocData DatePaid Data/ora in cui la fattura è stata pagata in formato YYYY-MM-DD hh:mm:ss
DocData Subtotal Subtotale. 2 cifre decimale. Punto come separatore decimale
DocData Credit Credito. 2 cifre decimale. Punto come separatore decimale
DocData Tax Tassa livello. 2 cifre decimale. Punto come separatore decimale
DocData Tax2 Tassa livello 2. 2 cifre decimale. Punto come separatore decimale
DocData TaxRate Aliquota tassa livello 1. 2 cifre decimale. Punto come separatore decimale
DocData TaxRate2 Aliquota tassa livello 2. 2 cifre decimale. Punto come separatore decimale
DocData PaymentMethod Metodo di pagamento (es. paypal)
DocData\Items ID ID voce fattura (tblinvoiceitems.id)
DocData\Items Type “Setup“, “Hosting“, “Domain“, “Upgrade“, “Item“, “Addon“, “PromoHosting“, “DomainGraceFee“, “LateFee“ ecc.
DocData\Items RelID ID del relativo prodotto/servizio, dominio, addon, voce fattura ecc.
DocData\Items Description Descrizione (es. Rinnovo Dominio example.com)
DocData\Items Amount Importo voce fattura. 2 cifre decimale. Punto come separatore decimale
DocData\Items Taxed true/false


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.

KeywordDescrizione
Today Seleziona 2019-06-15
Yesterday Seleziona2019-06-14
Last 7 days Seleziona da 2019-06-08 a 2019-06-15
Last week Seleziona da 2019-06-10 a 2019-06-16
Week to date Seleziona da 2019-06-10 a 2019-06-15
Month to date Seleziona da 2019-06-01 a 2019-06-15
Previous month Seleziona da 2019-05-01 a 2019-05-31
Year to date Seleziona da 2019-01-01 a 2019-05-15
Last year Seleziona da 2018-01-01 a 2018-12-31
All Seleziona tutti i risultati

Commenti (0)

Dì ciò che pensi Cancella Risposta