Producten

De productenmodule is de centrale plek waar je alles beheert dat op een factuur kan verschijnen: verblijfstarieven, diensten, energiekosten en andere artikelen. Elk product heeft een prijs inclusief BTW, en je kunt extra opties instellen zoals automatisch printen of een periodebinding.

Productenoverzicht

Je vindt alle producten via Administratie > Producten. De tabel toont per product:

• Naam en Beschrijving
• Info - het klanttype en metertype waaraan het product gekoppeld is (alleen zichtbaar als beide zijn ingesteld)
• Prijs (incl. BTW)
• BTW %
• Grootboek - het grootboeknummer voor de boekhouding (optioneel)

Zoeken en filteren

Bovenaan de tabel vind je een zoekbalk en een aantal filteropties:

• Typ in de zoekbalk om producten direct te filteren
• Filter op BTW, Klanttype, Metertype, Actietype of Rekeningen
• Gebruik de knop Reset om alle actieve filters in één keer te wissen

Een product aanmaken

1. Ga naar Administratie > Producten
2. Klik op "Nieuw Product" rechtsboven in de werkbalk
3. Vul het formulier in:
   • Naam (verplicht) - de naam zoals die op facturen verschijnt
   • Beschrijving - een korte toelichting (optioneel)
   • Prijs (incl. BTW) - het bedrag per eenheid, inclusief BTW
   • BTW % - kies het toepasselijke BTW-tarief (0%, 6%, 9%, 12% of 21%)
   • Grootboek - het grootboeknummer voor je boekhouding (optioneel)
   • Actie Type - koppel een speciale actie aan het product (zie Actietypes)
   • Klanttype - beperk het product tot een specifiek klanttype (optioneel)
   • Metertype - koppel het product aan een metertype (optioneel)
   • Thermische printkopieën - aantal exemplaren dat automatisch wordt afgedrukt bij betaling (0 = uitgeschakeld)
4. Klik op "Aanmaken"

Het product verschijnt direct in de lijst en is beschikbaar voor gebruik op facturen.

Een product bewerken

1. Ga naar Administratie > Producten
2. Klik op het potloodpictogram naast het product dat je wilt wijzigen
3. Pas de gewenste velden aan
4. Klik op "Opslaan"

Een product verwijderen

1. Ga naar Administratie > Producten
2. Klik op het prullenbakpictogram naast het product
3. Bevestig de verwijdering door op "Verwijderen" te klikken in het dialoogvenster

Actietypes

Met het veld Actie Type koppel je een product aan een specifieke automatische actie die wordt uitgevoerd wanneer een factuur met dit product wordt betaald.

Geen (standaard)

Het product heeft geen extra actie. Gebruik dit voor gewone tarieven en diensten.

NFC Tag Opladen

Wanneer een factuur met dit product wordt betaald, wordt er automatisch een NFC-tag opgeladen. Dit is bedoeld voor producten die klanten toegang geven via een NFC-tag.

Periode

Het product vertegenwoordigt een dienst over een bepaalde tijdsperiode. Als je Periode selecteert, verschijnen er twee extra velden:

• Per eenheid - het aantal eenheden per periode (minimaal 1)
• Periode-eenheid - kies Dag, Week of Maand

Gebruik dit actietype voor dagprijzen, weekabonnementen of maandelijkse tarieven.

Bezetting verlengen

Wanneer een factuur met dit product wordt betaald, verlengt Tillor Betaald tot van de gekozen bezetting tot de eerstvolgende geldige periodegrens van de ingestelde huurfrequentie. Zo lijnen alle klanten op termijn uit op dezelfde cyclus.

Bij het toevoegen van zo'n factuurregel moet je op de factuur een actieve bezetting kiezen. Tillor bewaart daarbij ook een snapshot van de gekozen bezetting in de factuurregel, zodat je achteraf nog kunt zien welke bezetting bedoeld was, ook als die bezetting later verwijderd is.

Extra factuurregels koppelen (JSON op het product)

Je kunt op een product extra factuurregels laten toevoegen wanneer dat product als hoofdregel op een conceptfactuur wordt gekozen. De configuratie staat in metadata.invoiceBundle op het product en wordt niet in het productdialoog bewerkt - je vult dit via je eigen tooling of database-import (JSON).

Vorm (version 1)

• invoiceBundle.version - vast 1
• invoiceBundle.steps - lijst van stappen. Elke stap is óf een productstap óf een inforestap:
  • Productstap - productId (bestaand product in je organisatie), quantity, optioneel quantityScale, optioneel style (DEFAULT of INFO, zie hieronder) en optioneel description (inclusief onderstaande placeholders). Alleen nog bij de samengevoegde legacy-expand CUSTOMER_NFC_ACCESS_SURCHARGE_LINES: optioneel descriptionIncluded voor alleen de eerste NFC-regel; bij CUSTOMER_NFC_ACCESS_INCLUDED_LINE gebruik je description. NFC-extendAccessMethod (zie hieronder): alleen bij een CUSTOMER_NFC_ACCESS_*-expand onder een hoofdproduct Bezetting verlengen: bij betaling van zo'n NFC-kindregel verlengt Tillor periodTo van die NFC-toegangsmethode tot de einddatum die op de hoofdregel Staangeld staat (actionDetails.endDate van Bezetting verlengen op die bundel), plus daysAfterPeriodEnd kalenderdagen (tot het einde van die lokale dag). Die einddatum moet dus op de Staangeld-hoofdregel gekozen zijn vóór betaling. Optioneel billOncePerInvoice: true - zie hieronder.
  • Inforestap - { "stepKind": "info", "description": "<tekst>" } - geen productId en geen bedrag; standaard slaat Tillor de regel op als inforegel. Optioneel style (standaard INFO als je het weglaat). Staat de stap onder een bundelhoofdregel, dan zet de PDF ↳ automatisch vooraan als description nog niet met ↳ begint (je mag ↳ ook gewoon in de JSON zetten). De volgorde van het kindblok volgt de volgorde van steps in je JSON.
• style (optioneel, productstappen en inforestappen) - DEFAULT of INFO. Gebruik bijvoorbeeld "style": "INFO" op een productstap als je die kindregel als grijze toelichting op de PDF wilt (zelfde idee als een inforestap). Tillor zet geen stijl automatisch op basis van een expand-key - je configureert dit zelf in de JSON.
• Voor een productstap is quantity altijd één van:
  • { "kind": "fixed", "value": <positief getal> } - één kindregel met die hoeveelheid en het producttarief
  • { "kind": "resolver", "key": "<string>" } - één kindregel; de hoeveelheid wordt server-side bepaald bij het opslaan van de factuur (zie keys hieronder)
  • { "kind": "expand", "key": "<string>" } - nul of meer kindregels afhankelijk van de klant (zie keys hieronder)
• quantityScale (optioneel, alleen productstappen) - "anchor_line_quantity": Tillor vermenigvuldigt de berekende hoeveelheid van die stap met de hoeveelheid van de hoofdregel (hetzelfde jaardeel als bij Staangeld met Bezetting verlengen, bv. 0,5 bij een half jaar). Afgerond op twee decimalen; regels met hoeveelheid 0 na vermenigvuldiging worden gewoonlijk weggelaten (uitzondering: de inbegrepen NFC-regel met CUSTOMER_NFC_ACCESS_INCLUDED_LINE (hoeveelheid 0), of bij legacy CUSTOMER_NFC_ACCESS_SURCHARGE_LINES de eerste regel daarvan: die blijft bewust staan voor de zichtbare omschrijving). Voor de editor-preview hoort daarbij anchorLineQuantity op POST .../invoices/preview-bundle-lines (OpenAPI). Heeft het hoofdproduct het actietype Bezetting verlengen en bevat de bundel ICY-meterstappen, geef dan ook occupationId mee (de gekozen bezetting op die hoofdregel) zodat preview hetzelfde terrein gebruikt als bij opslaan. Bevat de bundel een stap extendAccessMethod, geef bij preview-bundle-lines ook invoiceBillingAnchorEndDateIso mee (de gekozen einddatum op die hoofdregel bij Bezetting verlengen) zodat preview hetzelfde perioderesultaat gebruikt als bij opslaan voor die NFC-actie.
  • billOncePerInvoice (optioneel, alleen productstappen, boolean true) - alleen actief bij opslaan via factuur vervangen (replaceInvoice) én bij factuureditor-preview als preview-bundle-lines wordt aangeroepen met invoiceItemsForBillOnceContext en anchorItemListIndex. Bij twee of meer hoofdregels waarvan invoiceBundle minstens één stap heeft met billOncePerInvoice true, wordt elke billOnce-stap maximaal één keer op die factuur toegepast: Tillor gebruikt het hoofdproduct-id én de volgorde in steps (dus twee NFC-stappen met hetzelfde toeslag-product kunnen elk billOnce hebben). De eerste hoofdregel in items-volgorde wint voor die stap. Met precies één bundelhoofdregel heeft deze instelling geen effect. Integrators zonder preview-context zien mogelijk meer regels per hoofdregel dan na opslaan.
  • icyElectricityMeterBilling (optioneel, alleen productstappen waar quantity ICY_ELECTRICITY_METER_COUNT of ICY_ELECTRICITY_METER_LINES gebruikt) — zie ICY-meterhuur en supply aan/uit.
  • Tip bij twee NFC-expand stappen met hetzelfde productId - zet desgewenst billOncePerInvoice: true op beide stappen (inbegrepen én extra); elk telt als aparte stap door de positie in steps.
• description (alleen productstappen, optioneel) - tekst voor de factuurregel in plaats van de productnaam. Placeholders waar ze van toepassing zijn:
  • {meterName} - naam van de meter op die regel (expand ICY-meterregels)
  • {meterCount} - totaal aantal ICY-elektriciteitsmeters dat voor deze klant meetelt (resolver ICY_ELECTRICITY_METER_COUNT, en hetzelfde totaal op elke ICY-meterregel bij ICY_ELECTRICITY_METER_LINES)
  • {accessMethod} en {accessMethods} - voor NFC-regels vult Tillor dit met het bekende weergavelabel uit de interne kaartlijst (bv. V040005) als die voor de opgeslagen chip-UID bekend is; anders met de ruwe UID (hex). Je zet zelf dubbele punten of spaties in description / descriptionIncluded als je dat zo op de factuur wilt (bv. Toeslag extra toegangsmethode: {accessMethod}).
  • {dogNumber} - volgnummer van de hondregel (1 … n) bij CUSTOMER_DOG_SURCHARGE_LINES
  • {dogCount} - totaal aantal honden uit extraFields.animals.dogs (resolver CUSTOMER_DOG_COUNT, en hetzelfde totaal op elke hondregel bij CUSTOMER_DOG_SURCHARGE_LINES)

Inforestap (voorbeeld)

{
  "stepKind": "info",
  "description": "Inclusief toeristen-, gemeente- en provincietaksen"
}

Server-side resolvers (bij opslaan)

Wanneer een conceptfactuur wordt opgeslagen via factuur vervangen (replaceInvoice), bouwt Tillor bundel-kindregels onder een hoofdregel met invoiceBundle alleen opnieuw als op die hoofdregel het product, de hoeveelheid of (bij actietype Bezetting verlengen) de gekozen bezetting is gewijzigd ten opzichte van de laatst opgeslagen staat. Optioneel billOncePerInvoice op een productstap wordt tijdens die rebuild alleen toegepast als er minstens twee bundel-hoofdregels met zo'n stap op de factuur staan (zie billOncePerInvoice hierboven). Anders blijven de door jou ingevoerde of verwijderde kindregels staan (bijv. een meterregel weglaten blijft weg), behalve dat Tillor onder latere hoofdregels (waar de bundel dus niet opnieuw wordt opgebouwd) kindregels voor een billOncePerInvoice-product weghaalt als dat product al onder een eerdere hoofdregel op dezelfde factuur staat - zo voorkom je dubbel tellen na autosave of preview. Voordat je opslaat gebruikt de factuureditor preview-bundle-lines wanneer je die hoofdregel aanpast op hoeveelheid of bezetting (of bij het kiezen van een ander bundel-product), met draftcontext zodat billOncePerInvoice overeenkomt met opslaan. Uitzondering: heeft het hoofdproduct het actietype Bezetting verlengen, dan verschijnen bundel-kindregels pas nadat je een bezetting hebt gekozen (idem bij opslaan zonder regeneratie zolang product/hoeveelheid/bezetting ongewijzigd zijn).

Ondersteunde resolver-keys (één regel, hoeveelheid = afgeleide waarde):

Ondersteunde expand-keys (per match gewoonlijk hoeveelheid 1, behalve waar anders beschreven):

NFC-toeslag: periodTo na betaling (extendAccessMethod)

Alleen zinvol als het hoofdproduct Bezetting verlengen is en je een expand gebruikt CUSTOMER_NFC_ACCESS_INCLUDED_LINE, CUSTOMER_NFC_ACCESS_EXTRA_SURCHARGE_LINES óf CUSTOMER_NFC_ACCESS_SURCHARGE_LINES. Voeg optioneel toe:

"extendAccessMethod": { "daysAfterPeriodEnd": 20 }

daysAfterPeriodEnd is een niet-negatief geheel getal (maximum volgens het Tillor bundels-schema). Na betaling van zo'n NFC-kindregel zet Tillor voor die NFC-toegangsmethode periodTo op de einddatum van de gekoppelde Staangeld-hoofdregel (Bezetting verlengen, veld endDate op die hoofdregel), plus daysAfterPeriodEnd kalenderdagen (aan het einde van die lokale dag). Zonder geldige endDate op die hoofdregel gebeurt er bij betaling geen automatische verlenging voor die NFC-regel. Als periodTo al later ligt, verandert er niets. Op de gebeurtenissen-tijdlijn van de factuur en van de klant verschijnt na een geslaagde verlenging een regel die verwijst naar deze betaling.

Zonder gekozen bezetting op Bezetting verlengen worden er geen kindregels met deze automatische actie gegenereerd. occupationId op preview-bundle-lines blijft nodig waar meter-stappen het terrein van de bezetting nodig hebben. Optioneel invoiceBillingAnchorEndDateIso helpt de editor bij een consistente preview-context voor de hoofdregel; bij betaling gebruikt Tillor voor de verlenging uitsluitend de endDate op de Staangeld-hoofdregel in de parent-keten (die waarde wordt niet meer op de NFC-kindregel opgeslagen).

Honden: één regel vs. regel per hond

{
  "productId": "prd_hond",
  "quantity": { "kind": "resolver", "key": "CUSTOMER_DOG_COUNT" },
  "description": "Honden ({dogCount})"
}

Onbekende resolver- en expand-keys op een productstap worden genegeerd (geen extra regels). Ontbrekende productId op een productstap wordt overgeslagen. Een inforestap heeft geen productId.

ICY-meterhuur en supply aan/uit

Alleen voor stappen met resolver ICY_ELECTRICITY_METER_COUNT of expand ICY_ELECTRICITY_METER_LINES kun je optioneel icyElectricityMeterBilling op dezelfde productstap zetten.

• icyElectricityMeterBilling weglaten — Bestaand gedrag: elke ICY-elektriciteitsmeter in scope telt mee (supply aan of uit), onafhankelijk van de klant.
• restrictBillingToSupplyOnMeters: false — hetzelfde als weglaten (alle meters in scope tellen mee).
• restrictBillingToSupplyOnMeters: true — standaard tellen alleen meters met supply aan (icyMetadata.switchState === true). Optioneel billSupplyOffMetersForCustomersCreatedOnOrAfter — ISO-8601 datum/tijd (bijv. "2026-01-01T00:00:00.000Z"): klanten wiens createdAt ≥ dit tijdstip worden ook gefactureerd voor meters met supply uit. Laat dat veld weg als niemand voor supply-uit moet betalen.

Voorbeeld (supply-aan voor bestaande klanten, supply-uit ook voor klanten vanaf 2026):

"icyElectricityMeterBilling": {
  "restrictBillingToSupplyOnMeters": true,
  "billSupplyOffMetersForCustomersCreatedOnOrAfter": "2026-01-01T00:00:00.000Z"
}

Childregels worden gekoppeld aan de hoofdregel (parentItemListIndex). Op een conceptfactuur verplaats je een hoofdregel met de pijltjes alleen als heel blok ten opzichte van andere hoofdregels; je kunt hem niet tussen de kindregels van een andere bundel zetten. Kindregels herschik je alleen binnen die bundel (niet boven de hoofdregel). Verwijder je de hoofdregel, dan verdwijnen de gekoppelde kindregels mee.

Als je een product bewerkt via Administratie > Producten > Bewerken, blijft een bestaande invoiceBundle in de metadata behouden zolang je die buiten het formulier niet wijzigt. Bij gewone bundelregels zie je op de PDF een ↳ bij de omschrijving in de tabel; inforestappen verschijnen als grijze toelichtingsregel zonder bedragkolommen.

Voorbeeld (toelichting + NFC-toeslag + 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"
        }
      }
    ]
  }
}

Klanttype en metertype

Je kunt een product optioneel koppelen aan een Klanttype en een Metertype. Dit maakt het makkelijker om producten te filteren en automatisch toe te wijzen.

De beschikbare klanttypes zijn:

• Standaard - reguliere klanten
• Arbeider Huurcaravan - arbeidersklanten met een huurcaravan
• Arbeider Trekcaravan - arbeidersklanten met een trekcaravan

De beschikbare metertypes zijn:

• Elektriciteit
• Water
• Gas

Thermische printkopieën

Met het veld Thermische printkopieën stel je in hoeveel exemplaren er automatisch worden afgedrukt op de thermische (kassa)printer wanneer een factuur met dit product wordt betaald. Stel dit in op 0 om automatisch afdrukken uit te schakelen.

Het maximum is 10 kopieën per product.

Grootboeknummer

Elk product kan een grootboeknummer krijgen. Dit nummer wordt gebruikt bij het exporteren naar boekhoudsoftware. Als je een product niet aan een specifieke grootboekrekening wilt koppelen, laat je dit veld leeg.

Een wijziging van het grootboeknummer geldt voor nieuwe factuurregels. Bestaande factuurregels behouden het grootboeknummer van toen ze werden toegevoegd.