JSON del bundle
La struttura JSON di un bundle (versione 1), per le importazioni e per chi costruisce un bundle fuori dalla schermata.
Ultimo aggiornamento il
La scheda Righe fattura extra salva un bundle come JSON sul prodotto, sotto la chiave invoiceBundle. Per le importazioni usi la stessa struttura. Per l'uso normale questa pagina non ti serve: i campi e la loro spiegazione sono in Passaggi del bundle.
Struttura
| Campo | Significato |
|---|---|
invoiceBundle.version | Sempre 1 |
invoiceBundle.steps | Elenco di passaggi, al massimo 40. L'ordine è quello delle righe figlie sulla fattura |
Ogni passaggio è un passaggio prodotto o un passaggio info.
Passaggio prodotto
| Campo | Significato |
|---|---|
productId | Un prodotto esistente nella tua organizzazione. Obbligatorio |
quantity | Numero maggiore di 0, per impostazione predefinita 1. La quantità della riga senza formula, o quando la formula restituisce true |
quantityScale | Facoltativo. "anchor_line_quantity" moltiplica ogni quantità calcolata per la quantità della riga principale |
description | Facoltativo. Testo per la riga di fattura al posto del nome del prodotto; una formula può dare a ogni riga una propria description |
style | Facoltativo. DEFAULT o INFO |
billOncePerInvoice | Facoltativo. true lega il passaggio alla prima riga principale quando una fattura ne contiene diverse |
extendAccessMethod | Facoltativo. { "daysAfterPeriodEnd": <numero intero, da 0 a 3660> }, vedi Estensione NFC |
formula | Facoltativo. TypeScript che stabilisce quali righe produce il passaggio, vedi Formula |
Passaggio info
{
"stepKind": "info",
"description": "Inclusief toeristen-, gemeente- en provincietaksen"
}description è obbligatoria e un passaggio info non ha productId. Con style (DEFAULT o INFO) scegli lo stile della riga, per impostazione predefinita è INFO. Una formula che restituisce false omette la riga info.
Formula
formula è TypeScript che, al salvataggio di una fattura, restituisce true (una riga con quantity), false (nessuna riga), un numero (la quantità) oppure un elenco di righe { "quantity", "description", "unitPrice", "accessMethodValue" }. Quali campi ed elenchi puoi leggere e cosa fa ogni forma è spiegato in Formula per passaggio. Una formula che non compila viene rifiutata al salvataggio del prodotto. In JSON la formula è una sola stringa con \n per gli a capo.
"formula": "return {customer.customFields.exemptFromSurcharges} !== true;"Estensione NFC
Ha senso solo se il prodotto principale ha Estendi periodo occupazione come azione.
"extendAccessMethod": { "daysAfterPeriodEnd": 20 }Quando viene pagata una riga di un passaggio così, Tillor porta la validità dei metodi di accesso del cliente alla data di fine della riga principale più daysAfterPeriodEnd giorni di calendario. Per impostazione predefinita arriva fino alle 23:59 nel fuso orario dell'organizzazione, oppure fino al giorno della settimana e all'ora di Estendi metodo di accesso sul prodotto principale. Anche quali tipi e stati contano lo imposti lì. Senza una data di fine sulla riga principale non succede nulla. Con Non abbreviare all'estensione attivo, Tillor salta i metodi la cui validità è già alla nuova data o dopo. Un accessMethodValue sulla riga indica il metodo di quella riga; l'estensione stessa segue le impostazioni del prodotto principale.
Dopo un'estensione riuscita, sulla cronologia della fattura compare una riga che rimanda al pagamento.
Esempio: nota, supplemento NFC, noleggio contatore e cani
{
"invoiceBundle": {
"version": 1,
"steps": [
{
"stepKind": "info",
"description": "Inclusief toeristen-, gemeente- en provincietaksen"
},
{
"productId": "prd_nfc_toeslag",
"quantity": 1,
"quantityScale": "anchor_line_quantity",
"extendAccessMethod": { "daysAfterPeriodEnd": 20 },
"style": "INFO",
"billOncePerInvoice": true,
"formula": "const nfc = {accessMethods}.filter((a) => a.type === \"NFC\" && a.status === \"ACTIVE\");\nreturn nfc.slice(0, 1).map((a) => ({ quantity: 0, unitPrice: 0, accessMethodValue: a.value, description: `Toegangsmethode inclusief: ${a.label}` }));"
},
{
"productId": "prd_nfc_toeslag",
"quantity": 1,
"quantityScale": "anchor_line_quantity",
"extendAccessMethod": { "daysAfterPeriodEnd": 20 },
"billOncePerInvoice": true,
"formula": "const nfc = {accessMethods}.filter((a) => a.type === \"NFC\" && a.status === \"ACTIVE\");\nreturn nfc.slice(1).map((a) => ({ quantity: 1, accessMethodValue: a.value, description: `Toeslag extra toegangsmethode: ${a.label}` }));"
},
{
"productId": "prd_meterhuur",
"quantity": 1,
"quantityScale": "anchor_line_quantity",
"formula": "return {meters}.filter((m) => m.provider === \"ICY\" && m.type === \"ELECTRICITY\" && m.icyMetadata?.switchState === true).map((m) => ({ quantity: 1, description: `Huur digitale elektriciteitsmeter ${m.name}` }));"
},
{
"productId": "prd_hond",
"quantity": 1,
"quantityScale": "anchor_line_quantity",
"billOncePerInvoice": true,
"formula": "const dogs = Math.max(0, Math.floor(Number({customer.customFields.animals.dogs}) || 0));\nreturn dogs === 0 ? false : [{ quantity: dogs, description: `Honden (${dogs})` }];"
}
]
}
}Attenzione
Controlla che tutti i valori productId dei passaggi prodotto esistano nel tuo catalogo. Tillor salta i passaggi con un prodotto sconosciuto.