Zynergy Requirements - Collection Service

This document outlines the data requirements for an External Collection Service to handle collection agency file generation in a common way. The service receives a JSON request with a common schema and a target format, and produces the appropriate provider-specific file.

The common schema must contain the union of all fields needed across all supported providers and file types.

Supported Providers

Provider	Claim Format	Payment Format
Svea Ekonomi	Fixed-width text	Fixed-width text
Visma Collectors	XML (VismaCollectorsAct.xsd)	Fixed-width text
Intrum	Fixed-width text	Fixed-width text

All output files are encoded as iso-8859-1. The service handles encoding conversion from UTF-8 (JSON input) to iso-8859-1 (file output), including Swedish characters (å, ä, ö, etc.).

Claim Export (System → Collection Agency)

A claim export sends unpaid invoices to a collection agency for debt recovery.

Data Hierarchy

The schema follows a four-level hierarchy: file (batch metadata), debtors (customer information), invoices (the debts), and invoice lines (per-utility/billing-point breakdown).

File Level

Field	Type	Description	Used By
`timestamp`	datetime	When the file was generated	All
`provider`	enum	Target collection agency	All
`version`	string	Calling system version identifier	Visma
`sequenceNumber`	integer	Batch sequence number	Visma

Creditor (Sending Company)

Field	Type	Description	Used By
`creditor.id`	string	Company's customer number at the collection agency	All
`creditor.department`	string	Concern/department number at the agency	Svea, Visma
`creditor.internalReference`	string	Internal reference for the creditor	Visma
`creditor.name`	string	Company display name	Svea, Visma
`creditor.legalIdentity`	string	Company org number	Intrum (payments)

Debtor (Customer)

Field	Type	Description	Used By
`debtor.customerNumber`	string	Customer's external identifier	All
`debtor.name`	string	Customer's full name	All
`debtor.legalIdentity`	string	Organization number or personal number (10 digits). Mandatory for Intrum (validation fails if missing).	All
`debtor.isCompany`	boolean	Whether the debtor is a company or private person	All
`debtor.isProtected`	boolean	Whether the customer has protected identity	Svea
`debtor.type`	enum	Debtor type: `Private`, `Company`, `PrivateCompany` (sole proprietor)	Visma
`debtor.role`	string	Debtor role (e.g., primary debtor)	Visma

Note: The address must be the debtor's national registration address (folkbokföringsadress), not an invoice or delivery address.

Field	Type	Description	Used By
`debtor.address.careOf`	string	C/O address line	Svea, Visma
`debtor.address.street`	string	Street name	All
`debtor.address.houseNumber`	string	House number	All
`debtor.address.apartmentNumber`	string	Apartment number	All
`debtor.address.poBox`	string	PO Box (alternative to street address)	Svea, Intrum
`debtor.address.postalCode`	string	Postal code	All
`debtor.address.city`	string	City	All
`debtor.address.countryCode`	string	ISO country code (default `SE`)	All
`debtor.phone`	string	Phone number	Intrum, Visma
`debtor.mobile`	string	Mobile phone number	Visma
`debtor.email`	string	Email address	Svea

Invoice

Field	Type	Description	Used By
`invoice.invoiceRef`	string	Invoice reference number	All
`invoice.invoiceDate`	date	When the invoice was issued	All
`invoice.dueDate`	date	Payment due date	All
`invoice.originalDueDate`	date	Original due date before any extensions	Visma
`invoice.invoiceAmount`	decimal	Original invoice total amount	All
`invoice.capitalAmount`	decimal	Capital (principal) amount	All
`invoice.currentBalance`	decimal	Current outstanding balance	All
`invoice.currency`	string(3)	ISO currency code (e.g., `SEK`, `NOK`, `EUR`)	All
`invoice.rounding`	decimal	Rounding amount on invoice	Svea, Intrum
`invoice.expenseAmount`	decimal	Total claim/reminder fee amount	Svea, Intrum
`invoice.interestAmount`	decimal	Total interest amount	Svea, Intrum
`invoice.interestRate`	decimal	Interest rate (percentage)	Svea, Visma
`invoice.interestType`	enum	Interest calculation type: `Fixed`, `Percentage`, `PerMonth`, `ReferenceRate`	Visma
`invoice.hasDelayCompensation`	boolean	Whether delay compensation applies	Svea, Intrum
`invoice.isFinalInvoice`	boolean	Whether this is the customer's last invoice	Svea, Intrum
`invoice.isPartiallyPaid`	boolean	Whether partial payments exist	Svea, Intrum
`invoice.hasDeviatingInvoiceAddress`	boolean	Whether invoice was sent to a non-primary address	Svea
`invoice.paymentTermDays`	integer	Payment term in days	Visma
`invoice.actionType`	enum	`Collection` or `Reminder`	Visma
`invoice.debtType`	string	Debt classification (e.g., `Debetfaktura`)	Visma

Note on actionType: Visma produces separate Act blocks per action type and debtor type, meaning the same debtor can appear in multiple blocks — e.g., one for Collection + Company and one for Reminder + Company. The service groups invoices by actionType and debtor.type when generating the Visma XML.

Invoice Line (Utility/Billing Point Breakdown)

Each invoice is broken down by energy commodity and billing point. This grouping is central to Nordic energy collection.

Field	Type	Description	Used By
`line.utility`	string(2)	Utility/commodity type code (see mapping table)	All
`line.amount`	decimal	Capital amount for this utility/billing point	All
`line.currentAmount`	decimal	Current outstanding amount after payments	Svea
`line.comment`	string	Free-text description for this line (e.g., `"El: 735999100000012345, Storgatan 12 Stockholm"`)	Intrum

Note: The caller sends only the real utility lines (EL, FV, VA, etc.). The service generates format-specific additional lines (e.g., Svea's KR/PA/RA lines for rounding, fees, and interest) from the invoice-level amounts (rounding, expenseAmount, interestAmount, billingFee). For Intrum, rounding is folded into the first utility line's amount rather than creating a separate record.

Note: Visma uses only the highest-amount billing point per invoice for its Property section. The service selects it from the provided lines.

Billing Point

Each invoice line may include information about the physical billing point.

Field	Type	Description	Used By
`billingPoint.externalId`	string	External identifier for the metering/billing point	All
`billingPoint.address`	string	Full billing point address (composed)	Svea, Intrum
`billingPoint.street`	string	Street address	Visma
`billingPoint.postalCode`	string	Postal code	Visma
`billingPoint.city`	string	City	Visma
`billingPoint.countryCode`	string	Country code	Visma
`billingPoint.meterId`	string	Physical meter identifier	Svea, Visma
`billingPoint.netArea`	string	Network area code	Svea, Intrum
`billingPoint.regionCode`	string	Region/district code ("Lan")	Svea, Intrum
`billingPoint.areaCode`	string	Municipality/community code ("Kommun")	Svea, Intrum
`billingPoint.netOwnerId`	string	Network owner identifier	Visma
`billingPoint.annualConsumption`	decimal	Annual consumption estimate	Svea, Intrum
`billingPoint.isDisconnected`	boolean	Whether the billing point is disconnected	All
`billingPoint.disconnectedDate`	date	When disconnection occurred	Svea, Intrum
`billingPoint.hasMoved`	boolean	Whether the customer has moved	Svea, Intrum
`billingPoint.movedDate`	date	When the customer moved	Svea, Intrum

Costs (Claim Fees)

Field	Type	Description	Used By
`cost.type`	enum	`Claim`, `Reminder`, or `LateFee`	Visma, Intrum
`cost.date`	date	When the cost was incurred	Visma, Intrum
`cost.amount`	decimal	Cost amount	Visma, Intrum
`cost.currentAmount`	decimal	Current outstanding cost amount	Visma
`cost.invoiceRef`	string	Related invoice reference	Intrum

The service maps cost.type to provider-specific strings:

`cost.type`	Visma `Cost.Name`
`Claim`	`"Krav"`
`Reminder`	`"Påminnelse"`
`LateFee`	`"Förseningavgift"`

The service maps invoice.interestType to Visma XSD values:

`interestType` enum	Visma `InterestType`
`Fixed`	`FAST`
`Percentage`	`PER`
`PerMonth`	`PERMÅN`
`ReferenceRate`	`ÖGR`

Billing Fee

Field	Type	Description	Used By
`billingFee.amount`	decimal	Invoice billing fee (VAT-inclusive)	Svea
`billingFee.transferredAmount`	decimal	Sum of billing fees from transferred/consolidated invoices (VAT-inclusive)	Svea

Payment Export (System → Collection Agency)

After invoices have been sent to collection, the system reports payments and credits received on those invoices.

File Level

Field	Type	Description	Used By
`timestamp`	datetime	When the file was generated	All
`provider`	enum	Target collection agency	All
`creditor.id`	string	Company's payment customer number at the agency	All
`creditor.department`	string	Concern/department number	Svea, Visma
`creditor.name`	string	Company name	Svea, Visma
`creditor.legalIdentity`	string	Company org number	Intrum

Payment Record

Field	Type	Description	Used By
`payment.invoiceRef`	string	Invoice reference the payment applies to	All
`payment.amount`	decimal	Payment amount	All
`payment.date`	date	When the payment was recorded	All
`payment.currency`	string(3)	ISO currency code	Svea
`payment.type`	enum	`Payment` or `Credit` (settlement between invoices)	Svea, Visma
`payment.currentBalance`	decimal	Invoice balance after this payment	Svea, Intrum
`payment.customerNumber`	string	Customer external ID	Svea, Intrum
`payment.customerName`	string	Customer name	Svea
`payment.customerLegalIdentity`	string	Customer org/personal number (10 digits)	Intrum
`payment.settledFromInvoiceRef`	string	Source invoice ref (for cross-invoice settlements)	Svea
`payment.settledFromInvoiceDate`	date	Source invoice date	Svea
`payment.paidCapital`	decimal	Capital portion of the payment	Intrum
`payment.paidExpenses`	decimal	Expense/fee portion of the payment	Intrum
`payment.paidInterest`	decimal	Interest portion of the payment	Intrum
`payment.remainingCapital`	decimal	Remaining capital balance after payment	Intrum
`payment.invoiceCredited`	boolean	Whether the invoice this payment belongs to is credited (only one payment per invoice should set this to `true` to avoid duplicate credit records)	Intrum
`payment.creditComment`	string	Free-text credit note (e.g., "Fakturan krediterad")	Intrum

Note on Intrum payment breakdown: The paidCapital/paidExpenses/paidInterest split requires the caller to compute how a lump payment is distributed across capital, expenses, and interest. This typically involves balance calculations at the date the invoice was sent to collection. The service does not compute this split — the caller must provide it.

Note on currentBalance: The balance calculation may differ by provider. For example, Svea uses a provider-specific calculation based on both the payment creation time and the date the invoice was sent to collection. The caller is responsible for providing the correct balance per their business rules.

Response Contract

The service returns the generated file content. Format TBD — options:

Raw bytes — the caller receives the file content and handles storage/delivery
Base64-encoded string — file content as a JSON-friendly string with metadata (filename, content type, encoding)

Summary totals, record counts, and checksum records within the files are computed by the service — they are not part of the request schema.

Amount formatting: All amounts in the JSON are standard decimals (e.g., 12500.00). The service converts to the format required by each provider — fixed-width formats use öre (amount × 100, no decimals, e.g., 1250000).

Utility Type Mapping

The utility code identifies the energy commodity type. The common schema uses a 2-character code:

Code	Description (Swedish)	Description (English)	Intrum Numeric Code
`EL`	El (handel)	Electricity (trading)	`02`
`EN`	Elnat	Electricity (grid/network)	`01`
`EH`	Elhandel	Electricity (trading, alt)	`02`
`FV`	Fjarrvarme	District heating	`08`
`VA`	Vatten	Water	`07`
`BB`	Bredband	Broadband	`15`
`RH`	Renhallning	Waste management	`09`
`KD`	Kundspecifik	Customer-specific	`99`

Note: Some formats require additional synthetic line types for fees, rounding, and interest (e.g., Svea's KR, PA, RA records). These are generated by the service from the invoice-level amount fields — callers do not need to send them.

Example Schema

Claim Export

Core fields always present, provider-specific fields nullable. The service computes summary totals, record counts, and format-specific transformations (e.g., Intrum numeric utility codes) from this input.

{
  "type": "claim",
  "format": "SVEA",
  "timestamp": "2025-03-10T08:30:00Z",
  "version": "3.2.1",
  "sequenceNumber": 0,
  "creditor": {
    "id": "1234567",
    "department": "001",
    "internalReference": "REF-001",
    "name": "Energibolaget AB",
    "legalIdentity": "5561234567"
  },
  "debtors": [
    {
      "customerNumber": "K-900123",
      "name": "Anna Johansson",
      "legalIdentity": "8501011234",
      "isCompany": false,
      "isProtected": false,
      "type": "Private",
      "role": "Huvudgäldenär",
      "address": {
        "careOf": null,
        "street": "Storgatan",
        "houseNumber": "12",
        "apartmentNumber": "1102",
        "poBox": null,
        "postalCode": "11122",
        "city": "Stockholm",
        "countryCode": "SE"
      },
      "phone": "0812345678",
      "mobile": "0701234567",
      "email": "anna.johansson@example.com",
      "invoices": [
        {
          "invoiceRef": "2025001234",
          "invoiceDate": "2025-01-15",
          "dueDate": "2025-02-15",
          "originalDueDate": "2025-02-15",
          "invoiceAmount": 12500.00,
          "capitalAmount": 11800.00,
          "currentBalance": 12500.00,
          "currency": "SEK",
          "rounding": -0.50,
          "expenseAmount": 180.00,
          "interestAmount": 45.00,
          "interestRate": 0,
          "interestType": "PerMonth",
          "isFinalInvoice": false,
          "isPartiallyPaid": false,
          "hasDeviatingInvoiceAddress": false,
          "hasDelayCompensation": false,
          "paymentTermDays": 31,
          "actionType": "Collection",
          "debtType": "Debetfaktura",
          "billingFee": {
            "amount": 45.00,
            "transferredAmount": 0
          },
          "lines": [
            {
              "utility": "EL",
              "amount": 8500.00,
              "currentAmount": 8500.00,
              "comment": "El: 735999100000012345, Storgatan 12 Stockholm",
              "billingPoint": {
                "externalId": "735999100000012345",
                "address": "Storgatan 12 Stockholm 11122 SE",
                "street": "Storgatan 12",
                "postalCode": "11122",
                "city": "Stockholm",
                "countryCode": "SE",
                "meterId": "MET-12345",
                "netArea": "SN1",
                "regionCode": "01",
                "areaCode": "180",
                "netOwnerId": "ELNAT-001",
                "annualConsumption": 15000,
                "isDisconnected": false,
                "disconnectedDate": null,
                "hasMoved": false,
                "movedDate": null
              }
            },
            {
              "utility": "FV",
              "amount": 3300.00,
              "currentAmount": 3300.00,
              "comment": "Fjärrvärme: 735999100000054321, Storgatan 12 Stockholm",
              "billingPoint": {
                "externalId": "735999100000054321",
                "address": "Storgatan 12 Stockholm 11122 SE",
                "street": "Storgatan 12",
                "postalCode": "11122",
                "city": "Stockholm",
                "countryCode": "SE",
                "meterId": "MET-54321",
                "netArea": null,
                "regionCode": "01",
                "areaCode": "180",
                "netOwnerId": null,
                "annualConsumption": null,
                "isDisconnected": false,
                "disconnectedDate": null,
                "hasMoved": false,
                "movedDate": null
              }
            }
          ],
          "costs": [
            {
              "type": "Reminder",
              "date": "2025-02-20",
              "amount": 60.00,
              "currentAmount": 60.00,
              "invoiceRef": "2025001234"
            },
            {
              "type": "Claim",
              "date": "2025-03-05",
              "amount": 180.00,
              "currentAmount": 180.00,
              "invoiceRef": "2025001234"
            }
          ]
        }
      ]
    },
    {
      "customerNumber": "K-800456",
      "name": "Fastigheter i Norr AB",
      "legalIdentity": "5567891234",
      "isCompany": true,
      "isProtected": false,
      "type": "Company",
      "role": "Huvudgäldenär",
      "address": {
        "careOf": null,
        "street": "Industrivägen",
        "houseNumber": "5",
        "apartmentNumber": null,
        "poBox": null,
        "postalCode": "90325",
        "city": "Umeå",
        "countryCode": "SE"
      },
      "phone": "0901234567",
      "mobile": null,
      "email": null,
      "invoices": [
        {
          "invoiceRef": "2025005678",
          "invoiceDate": "2024-12-01",
          "dueDate": "2025-01-01",
          "originalDueDate": "2025-01-01",
          "invoiceAmount": 45200.00,
          "capitalAmount": 44000.00,
          "currentBalance": 25200.00,
          "currency": "SEK",
          "rounding": 0,
          "expenseAmount": 600.00,
          "interestAmount": 120.00,
          "interestRate": 0,
          "interestType": "PerMonth",
          "isFinalInvoice": false,
          "isPartiallyPaid": true,
          "hasDeviatingInvoiceAddress": false,
          "hasDelayCompensation": true,
          "paymentTermDays": 31,
          "actionType": "Collection",
          "debtType": "Debetfaktura",
          "billingFee": {
            "amount": 0,
            "transferredAmount": 0
          },
          "lines": [
            {
              "utility": "VA",
              "amount": 44000.00,
              "currentAmount": 24000.00,
              "comment": "Vatten: 735999200000099887, Industrivägen 5 Umeå",
              "billingPoint": {
                "externalId": "735999200000099887",
                "address": "Industrivägen 5 Umeå 90325 SE",
                "street": "Industrivägen 5",
                "postalCode": "90325",
                "city": "Umeå",
                "countryCode": "SE",
                "meterId": "MET-99887",
                "netArea": null,
                "regionCode": "24",
                "areaCode": "280",
                "netOwnerId": null,
                "annualConsumption": null,
                "isDisconnected": true,
                "disconnectedDate": "2025-02-15",
                "hasMoved": false,
                "movedDate": null
              }
            }
          ],
          "costs": [
            {
              "type": "Claim",
              "date": "2025-02-01",
              "amount": 600.00,
              "currentAmount": 600.00,
              "invoiceRef": "2025005678"
            }
          ]
        }
      ]
    }
  ]
}

Payment Export

{
  "type": "payment",
  "format": "INTRUM",
  "timestamp": "2025-03-10T09:00:00Z",
  "creditor": {
    "id": "7654321",
    "department": null,
    "name": "Energibolaget AB",
    "legalIdentity": "5561234567"
  },
  "payments": [
    {
      "invoiceRef": "2025005678",
      "amount": 20000.00,
      "date": "2025-03-08",
      "currency": "SEK",
      "type": "Payment",
      "currentBalance": 25200.00,
      "customerNumber": "K-800456",
      "customerName": "Fastigheter i Norr AB",
      "customerLegalIdentity": "5567891234",
      "settledFromInvoiceRef": null,
      "settledFromInvoiceDate": null,
      "paidCapital": 19500.00,
      "paidExpenses": 400.00,
      "paidInterest": 100.00,
      "remainingCapital": 24500.00,
      "invoiceCredited": false,
      "creditComment": null
    },
    {
      "invoiceRef": "2025001111",
      "amount": 5500.00,
      "date": "2025-03-09",
      "currency": "SEK",
      "type": "Credit",
      "currentBalance": 0,
      "customerNumber": "K-800456",
      "customerName": "Fastigheter i Norr AB",
      "customerLegalIdentity": "5567891234",
      "settledFromInvoiceRef": "2025002222",
      "settledFromInvoiceDate": "2025-01-15",
      "paidCapital": 5500.00,
      "paidExpenses": 0,
      "paidInterest": 0,
      "remainingCapital": 0,
      "invoiceCredited": true,
      "creditComment": "Fakturan krediterad"
    }
  ]
}

Format Differences Summary

Aspect	Svea	Visma	Intrum
Claim format	Fixed-width text	XML (XSD)	Fixed-width text
Payment format	Fixed-width text	Fixed-width text	Fixed-width text
Creditor ID length	7 chars	6 chars	Variable
Department length	3 chars	4 chars	N/A
Action type	Implicit	`Inkasso` / `Paminnelse`	Implicit
Debtor type	`J`/`N`/`S` (company/no/protected)	`Privatperson`/`Foretag`/`Enskild firma`	`1` (consumer) / `2` (company)
Utility code format	2-char text	2-char text (`ChargeType`)	Numeric codes
Interest handling	Separate `RA` line	`InterestPercentage` + `InterestType`	Separate record type `12`
Expense handling	Separate `PA` line	`Cost` sections per claim	Separate record type `14`
Payment breakdown	Lump sum	Lump sum	Split into capital/expenses/interest
Credit handling	Not explicit	Not explicit	Explicit credit records with comment
Phone	Not included	Included	Included
Email	Included (100 chars)	Not included	Not included

Page tree

Zynergy Requirements - Collection Service

Supported Providers

Claim Export (System → Collection Agency)

Data Hierarchy

File Level

Creditor (Sending Company)

Debtor (Customer)

Invoice

Invoice Line (Utility/Billing Point Breakdown)

Billing Point

Costs (Claim Fees)

Billing Fee

Payment Export (System → Collection Agency)

File Level

Payment Record

Response Contract

Utility Type Mapping

Example Schema

Claim Export

Payment Export

Format Differences Summary