Bundel-JSON
De JSON-structuur van een bundel (versie 1), voor imports en wie een bundel buiten het scherm opbouwt.
Laatst bijgewerkt op
De kaart Extra factuurregels schrijft een bundel weg als JSON op het product, onder de sleutel invoiceBundle. Voor imports gebruik je dezelfde structuur. Voor gewoon gebruik heb je deze pagina niet nodig: de velden en hun uitleg staan bij Bundelstappen.
Structuur
| Veld | Betekenis |
|---|---|
invoiceBundle.version | Vast 1 |
invoiceBundle.steps | Lijst met stappen, maximaal 40. De volgorde is de volgorde van de kindregels op de factuur |
Elke stap is een productstap of een inforestap.
Productstap
| Veld | Betekenis |
|---|---|
productId | Een bestaand product in je organisatie. Verplicht |
quantity | De hoeveelheid, zie Hoeveelheid. Verplicht |
quantityScale | Optioneel. "anchor_line_quantity" vermenigvuldigt de berekende hoeveelheid met de hoeveelheid van de hoofdregel |
description | Optioneel. Tekst voor de factuurregel in plaats van de productnaam, met placeholders |
style | Optioneel. DEFAULT of INFO |
billOncePerInvoice | Optioneel. true houdt de stap bij meerdere hoofdregels op een factuur bij de eerste hoofdregel |
extendAccessMethod | Optioneel. { "daysAfterPeriodEnd": <geheel getal, 0 tot 3660> }. Alleen bij de NFC-sleutels, zie NFC-verlenging |
icyElectricityMeterBilling | Optioneel. Alleen bij de ICY-sleutels, zie ICY-meters |
Inforestap
{
"stepKind": "info",
"description": "Inclusief toeristen-, gemeente- en provincietaksen"
}description is verplicht en een inforestap heeft geen productId. Met style (DEFAULT of INFO) kies je de regelstijl, standaard is dat INFO.
Hoeveelheid
quantity is altijd een van deze drie.
| Vorm | Resultaat |
|---|---|
{ "kind": "fixed", "value": 1 } | Een kindregel met die hoeveelheid, groter dan 0, en het producttarief |
{ "kind": "resolver", "key": "..." } | Een kindregel waarvan de hoeveelheid Tillor bepaalt bij het opslaan van de factuur |
{ "kind": "expand", "key": "..." } | Nul of meer kindregels, afhankelijk van de klant |
Een onbekende sleutel levert geen regels op. Een productstap zonder productId wordt overgeslagen.
Sleutels
| Sleutel | Soort | Betekenis |
|---|---|---|
ICY_ELECTRICITY_METER_COUNT | resolver | Aantal ICY-elektriciteitsmeters in scope |
CUSTOMER_DOG_COUNT | resolver | Aantal honden van de klant. Leeg of 0 betekent geen regel |
ICY_ELECTRICITY_METER_LINES | expand | Een regel per ICY-elektriciteitsmeter, hoeveelheid 1 |
CUSTOMER_NFC_ACCESS_INCLUDED_LINE | expand | Een regel voor de eerste actieve NFC, hoeveelheid 0 en tarief 0 |
CUSTOMER_NFC_ACCESS_EXTRA_SURCHARGE_LINES | expand | Een regel per tweede, derde, enzovoort actieve NFC, hoeveelheid 1 |
CUSTOMER_DOG_SURCHARGE_LINES | expand | Een regel per hond. De eerste regel heeft tarief 0 |
De betekenis in de app staat bij Dynamische sleutels.
NFC-verlenging
Alleen zinvol als het hoofdproduct Bezetting Verlengen als actie heeft en je een van de NFC-sleutels gebruikt.
"extendAccessMethod": { "daysAfterPeriodEnd": 20 }Bij betaling van zo'n NFC-kindregel zet Tillor de geldigheid van de NFC-tag op de einddatum van de Staangeld-hoofdregel plus daysAfterPeriodEnd kalenderdagen. Standaard loopt die tot 23:59 in de tijdzone van de organisatie, of tot de weekdag en tijd van Toegangsmethode verlengen op het hoofdproduct. Welke types en statussen meetellen, stel je daar ook in. Zonder einddatum op de hoofdregel gebeurt er niets. Met Niet verkorten bij verlengen aan, slaat Tillor methoden over waarvan de geldigheid al op of na de nieuwe datum ligt.
Na een geslaagde verlenging staat op de tijdlijn van de factuur een regel die naar de betaling verwijst.
ICY-meters
icyElectricityMeterBilling kan op een stap met ICY_ELECTRICITY_METER_COUNT of ICY_ELECTRICITY_METER_LINES.
| Veld | Betekenis |
|---|---|
restrictBillingToSupplyOnMeters | false is hetzelfde als het blok weglaten: alle meters tellen mee. true: alleen meters met supply aan |
billSupplyOffMetersForCustomersCreatedOnOrAfter | Optioneel, ISO-8601 datum en tijd. Klanten die op of na dat moment zijn aangemaakt, betalen ook voor meters met supply uit. Zonder dit veld betaalt niemand voor supply uit |
"icyElectricityMeterBilling": {
"restrictBillingToSupplyOnMeters": true,
"billSupplyOffMetersForCustomersCreatedOnOrAfter": "2026-01-01T00:00:00.000Z"
}Voorbeelden
Honden: een regel of een regel per hond
{
"productId": "prd_hond",
"quantity": { "kind": "resolver", "key": "CUSTOMER_DOG_COUNT" },
"description": "Honden ({dogCount})"
}Toelichting, NFC-toeslag en meterhuur
{
"invoiceBundle": {
"version": 1,
"steps": [
{
"stepKind": "info",
"description": "Inclusief toeristen-, gemeente- en provincietaksen"
},
{
"productId": "prd_nfc_toeslag",
"quantity": { "kind": "expand", "key": "CUSTOMER_NFC_ACCESS_INCLUDED_LINE" },
"quantityScale": "anchor_line_quantity",
"extendAccessMethod": { "daysAfterPeriodEnd": 20 },
"description": "Toegangsmethode inclusief: {accessMethod}",
"style": "INFO",
"billOncePerInvoice": true
},
{
"productId": "prd_nfc_toeslag",
"quantity": { "kind": "expand", "key": "CUSTOMER_NFC_ACCESS_EXTRA_SURCHARGE_LINES" },
"quantityScale": "anchor_line_quantity",
"extendAccessMethod": { "daysAfterPeriodEnd": 20 },
"description": "Toeslag extra toegangsmethode: {accessMethod}",
"billOncePerInvoice": true
},
{
"productId": "prd_meterhuur",
"quantity": { "kind": "expand", "key": "ICY_ELECTRICITY_METER_LINES" },
"description": "Huur digitale elektriciteitsmeter {meterName} ({meterCount} totaal)",
"icyElectricityMeterBilling": {
"restrictBillingToSupplyOnMeters": true,
"billSupplyOffMetersForCustomersCreatedOnOrAfter": "2026-01-01T00:00:00.000Z"
}
}
]
}
}Let op
Controleer dat alle productId-waarden op productstappen bestaan in je catalogus. Stappen met een onbekend product slaat Tillor over.