JSON do pacote
A estrutura JSON de um pacote (versão 1), para importações e para quem constrói um pacote fora do ecrã.
Última atualização em
O cartão Linhas de fatura extra grava um pacote como JSON no produto, sob a chave invoiceBundle. Para importações, use a mesma estrutura. Para a utilização normal não precisa desta página: os campos e a respetiva explicação estão em Passos do pacote.
Estrutura
| Campo | Significado |
|---|---|
invoiceBundle.version | Sempre 1 |
invoiceBundle.steps | Lista de passos, no máximo 40. A ordem é a ordem das linhas filhas na fatura |
Cada passo é um passo de produto ou um passo de informação.
Passo de produto
| Campo | Significado |
|---|---|
productId | Um produto existente na sua organização. Obrigatório |
quantity | Número maior que 0, por omissão 1. A quantidade da linha sem fórmula, ou quando a fórmula devolve true |
quantityScale | Opcional. "anchor_line_quantity" multiplica cada quantidade calculada pela quantidade da linha principal |
description | Opcional. Texto da linha de fatura em vez do nome do produto; uma fórmula pode indicar uma description própria por linha |
style | Opcional. DEFAULT ou INFO |
billOncePerInvoice | Opcional. true mantém o passo, quando há várias linhas principais numa fatura, na primeira linha principal |
extendAccessMethod | Opcional. { "daysAfterPeriodEnd": <número inteiro, 0 a 3660> }, ver Prorrogação NFC |
formula | Opcional. TypeScript que determina que linhas o passo produz, ver Fórmula |
Passo de informação
{
"stepKind": "info",
"description": "Inclusief toeristen-, gemeente- en provincietaksen"
}description é obrigatório e um passo de informação não tem productId. Com style (DEFAULT ou INFO) escolhe o estilo da linha; por omissão é INFO. Uma formula que devolva false omite a linha de informação.
Fórmula
formula é TypeScript que, ao guardar uma fatura, devolve true (uma linha com quantity), false (nenhuma linha), um número (a quantidade) ou uma lista de linhas { "quantity", "description", "unitPrice", "accessMethodValue" }. Os campos e listas que pode ler e o que cada forma faz estão em Fórmula por passo. Uma fórmula que não compila é recusada ao guardar o produto. Em JSON, a fórmula é uma única string com \n para as quebras de linha.
"formula": "return {customer.customFields.exemptFromSurcharges} !== true;"Prorrogação NFC
Só faz sentido quando o produto principal tem Prorrogar período de ocupação como ação.
"extendAccessMethod": { "daysAfterPeriodEnd": 20 }Quando é paga uma linha de um passo deste tipo, o Tillor define a validade dos métodos de acesso do cliente como a data de fim da linha principal mais daysAfterPeriodEnd dias de calendário. Por omissão, a validade vai até às 23:59 no fuso horário da organização, ou até ao dia da semana e hora de Prorrogar método de acesso no produto principal. Os tipos e estados que contam também são definidos aí. Sem data de fim na linha principal, nada acontece. Com Não encurtar ao prorrogar ativo, o Tillor ignora os métodos cuja validade já seja igual ou posterior à nova data. Um accessMethodValue na linha indica o método dessa linha; a prorrogação em si segue as definições do produto principal.
Após uma prorrogação bem-sucedida, a linha cronológica da fatura mostra uma entrada que remete para o pagamento.
Exemplo: nota explicativa, suplemento NFC, aluguer de contador e cães
{
"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})` }];"
}
]
}
}Atenção
Verifique se todos os valores productId nos passos de produto existem no seu catálogo. O Tillor ignora os passos com um produto desconhecido.