Billing Extension 36
Commission Manager 3
Mercury 8
Payments Bundle 2
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.
| Parametro | Descrizione | Obbligatorio |
|---|---|---|
| $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 | ||
|---|---|---|
| Parametro | Descrizione | Obbligatorio |
| 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 | ||
|---|---|---|
| Nodo | Parametro | Descrizione |
| 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 | ||
| 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.
| Keyword | Descrizione |
|---|---|
| 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)